spec_forge 0.1.0 → 0.3.0

data/lib/spec_forge/normalizer/configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    class Configuration < Normalizer
+      STRUCTURE = {
+        base_url: SHARED_ATTRIBUTES[:base_url].except(:default), # Make it required
+        headers: SHARED_ATTRIBUTES[:headers],
+        query: SHARED_ATTRIBUTES[:query],
+        factories: {
+          type: Hash,
+          default: {},
+          structure: {
+            auto_discover: {
+              type: [TrueClass, FalseClass],
+              default: true
+            },
+            paths: {
+              type: Array,
+              default: []
+            }
+          }
+        },
+        on_debug: {
+          type: Proc
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty configuration hash
+      #
+      # @return [Hash]
+      #
+      def default_configuration
+        Configuration.default
+      end
+
+      #
+      # Normalizes a configuration hash by standardizing its keys while ensuring the required data
+      # is provided or defaulted.
+      # Raises InvalidStructureError if anything is missing/invalid type
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash as a new instance
+      #
+      def normalize_configuration!(input)
+        raise_errors! do
+          normalize_configuration(input)
+        end
+      end
+
+      #
+      # Normalize a configuration hash
+      # Used internally by .normalize_configuration!, but is available for utility
+      #
+      # @param configuration [Hash] Configuration representation as a Hash
+      #
+      # @return [Array] Two item array
+      #   First - The normalized hash
+      #   Second - Array of errors, if any
+      #
+      # @private
+      #
+      def normalize_configuration(configuration)
+        if !Type.hash?(configuration)
+          raise InvalidTypeError.new(configuration, Hash, for: "configuration")
+        end
+
+        Normalizer::Configuration.new("configuration", configuration).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/expectation.rb

@@ -12,6 +12,7 @@ module SpecForge
         query: Normalizer::SHARED_ATTRIBUTES[:query],
         body: Normalizer::SHARED_ATTRIBUTES[:body],
         variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        debug: Normalizer::SHARED_ATTRIBUTES[:debug],
         expect: {type: Hash}
       }.freeze
     end

data/lib/spec_forge/normalizer/spec.rb

@@ -11,6 +11,7 @@ module SpecForge
         query: Normalizer::SHARED_ATTRIBUTES[:query],
         body: Normalizer::SHARED_ATTRIBUTES[:body],
         variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        debug: Normalizer::SHARED_ATTRIBUTES[:debug],
         expectations: {type: Array}
       }.freeze
     end

data/lib/spec_forge/normalizer.rb

@@ -34,6 +34,11 @@ module SpecForge
       variables: {
         type: Hash,
         default: {}
+      },
+      debug: {
+        type: [TrueClass, FalseClass],
+        default: false,
+        aliases: %i[pry breakpoint]
       }
     }.freeze
 
@@ -103,10 +108,12 @@ module SpecForge
     #
     def default
       structure.transform_values do |value|
-        if (default = value[:default])
-          default.dup
+        if value.key?(:default)
+          value[:default].dup
         elsif value[:type] == Integer # Can't call new on int
           0
+        elsif value[:type] == Proc # Sameeee
+          -> {}
         else
           value[:type].new
         end
@@ -172,12 +179,8 @@ module SpecForge
   end
 end
 
-#######################################################################
-# These need to be required after the base class due to them requiring
-# a constant
-require_relative "normalizer/config"
-require_relative "normalizer/constraint"
-require_relative "normalizer/expectation"
-require_relative "normalizer/factory_reference"
-require_relative "normalizer/factory"
-require_relative "normalizer/spec"
+####################################################################################################
+# These need to be required after the base class due to them requiring constants on Normalizer
+Dir[File.expand_path("normalizer/*.rb", __dir__)].sort.each do |path|
+  require path
+end

data/lib/spec_forge/runner.rb

@@ -2,89 +2,115 @@
 
 module SpecForge
   class Runner
-    #
-    # Creates a spec runner and defines the spec with RSpec
-    #
-    # @param spec [Spec] The spec to run
-    #
-    def initialize(spec)
-      define_spec(spec)
-    end
+    class << self
+      #
+      # Runs any specs
+      #
+      def run
+        RSpec::Core::Runner.disable_autorun!
+        RSpec::Core::Runner.run([], $stderr, $stdout)
+      end
 
-    #
-    # Runs any RSpec specs
-    #
-    def run
-      RSpec::Core::Runner.disable_autorun!
-      RSpec::Core::Runner.run([], $stderr, $stdout)
-    end
+      #
+      # Defines a spec with RSpec
+      #
+      # @param spec_forge [Spec] The spec to define
+      #
+      def define_spec(spec_forge)
+        runner_forge = self
+
+        RSpec.describe(spec_forge.name) do
+          spec_forge.expectations.each do |expectation|
+            # Define the example group
+            describe(expectation.name) do
+              constraints = expectation.constraints
+
+              let!(:expected_status) { constraints.status.resolve }
+              let!(:expected_json) { constraints.json.resolve.deep_stringify_keys }
+
+              before do
+                # Ensure all variables are called and resolved, in case they are not referenced
+                expectation.variables.resolve
+              end
+
+              subject(:response) { expectation.http_client.call }
+
+              it do
+                if spec_forge.debug? || expectation.debug?
+                  runner_forge.handle_debug(expectation, self)
+                end
 
-    #
-    # Defines a spec with RSpec
-    #
-    # @param spec_forge [Spec] The spec to define
-    #
-    def define_spec(spec_forge)
-      runner_forge = self
-
-      RSpec.describe(spec_forge.name) do
-        spec_forge.expectations.each do |expectation_forge|
-          describe(expectation_forge.name) do
-            runner_forge.define_variables(self, expectation_forge)
-            runner_forge.define_examples(self, expectation_forge)
+                # Status check
+                expect(response.status).to eq(expected_status)
+
+                # JSON check
+                if constraints.json.size > 0
+                  expect(response.body).to be_kind_of(Hash)
+                  expect(response.body).to include(expected_json)
+                end
+              end
+            end
           end
         end
       end
-    end
 
-    #
-    # Defines any variables as let statements in RSpec
-    #
-    # @param context [RSpec::ExampleGroup] The rspec example group for this spec
-    # @param expectation [Expectation] The expectation that holds the variables
-    #
-    def define_variables(context, expectation)
-      expectation.variables.each do |variable_name, attribute|
-        context.let(variable_name, &attribute.to_proc)
+      def handle_debug(...)
+        DebugProxy.new(...).call
       end
     end
 
-    #
-    # Defines the expectation itself using the constraint
-    #
-    # @param context [RSpec::ExampleGroup] The RSpec example group for this spec
-    # @param expectation [Expectation] The expectation that holds the constraint
-    #
-    def define_examples(context, expectation)
-      context.instance_exec(expectation) do |expectation|
-        # Ensures the only one API call occurs per expectation
-        before(:all) { @response = expectation.http_client.call }
-
-        constraints = expectation.constraints.resolve
-        request = expectation.http_client.request
-
-        # Define the example group
-        context "#{request.http_method} #{request.url}" do
-          subject(:response) { @response }
-
-          # Status check
-          expected_status = constraints[:status]
-          it "expects the response to return a status code of #{expected_status}" do
-            expect(response.status).to eq(expected_status)
-          end
+    ################################################################################################
 
-          # JSON check
-          expected_json = constraints[:json]
-          if expected_json.size > 0
-            it "expects the body to return valid JSON" do
-              expect(response.body).to be_kind_of(Hash)
-            end
+    class DebugProxy
+      def self.default
+        -> { puts inspect }
+      end
 
-            it "expects the body to include values" do
-              expect(response.body).to include(expected_json)
-            end
-          end
-        end
+      attr_reader :expectation, :variables, :expected_status, :expected_json, :request, :response
+
+      def initialize(expectation, spec_context)
+        @callback = SpecForge.configuration.on_debug
+
+        @expected_status = spec_context.expected_status
+        @expected_json = spec_context.expected_json
+
+        @request = expectation.http_client.request
+        @response = spec_context.response
+
+        @variables = expectation.variables
+        @expectation = expectation
+      end
+
+      def call
+        puts <<~STRING
+
+          Debug triggered for: #{expectation.name}
+
+          Available methods:
+          - expectation: Full expectation context
+          - variables: Current variable definitions
+          - expected_status: Expected HTTP status code (#{expected_status})
+          - expected_json: Expected response body
+          - request: HTTP request details (method, url, headers, body)
+          - response: HTTP response
+
+          Tip: Type 'self' for a JSON overview of the current state
+               Individual methods return full object details for advanced debugging
+        STRING
+
+        instance_exec(&@callback)
+      end
+
+      def inspect
+        hash = expectation.to_h
+
+        hash[:response] = {
+          headers: response.headers,
+          status: response.status,
+          body: response.body
+        }
+
+        JSON.pretty_generate(hash)
       end
     end
   end

data/lib/spec_forge/spec/expectation/constraint.rb

@@ -17,11 +17,8 @@ module SpecForge
           super(status:, json: normalize_hash(json))
         end
 
-        def resolve
-          {
-            status: status.resolve,
-            json: json.resolve.deep_stringify_keys
-          }
+        def to_h
+          super.transform_values(&:resolve)
         end
 
         private

data/lib/spec_forge/spec/expectation.rb

@@ -5,6 +5,8 @@ require_relative "expectation/constraint"
 module SpecForge
   class Spec
     class Expectation
+      attr_predicate :debug
+
       attr_reader :name, :variables, :constraints, :http_client
 
       #
@@ -13,37 +15,54 @@ module SpecForge
       # @param input [Hash] A hash containing the various attributes to control the expectation
       # @param name [String] The name of the expectation
       #
-      def initialize(name, input, global_options: {})
-        load_name(name, input)
-
+      def initialize(input, global_options: {})
         # This allows defining spec level attributes that can be overwritten by the expectation
-        input = Attribute.from(overlay_options(global_options, input))
+        input = Attribute.from(Configuration.overlay_options(global_options, input))
 
+        load_debug(input)
         load_variables(input)
 
         # Must be after load_variables
         load_constraints(input)
 
-        # Must be last
-        @http_client = HTTP::Client.new(variables:, **input.except(:name, :variables, :expect))
+        @http_client = HTTP::Client.new(
+          variables:, **input.except(:name, :variables, :expect, :debug)
+        )
+
+        # Must be after http_client
+        load_name(input)
+      end
+
+      def to_h
+        {
+          name:,
+          debug: debug?,
+          variables: variables.resolve,
+          request: http_client.request.to_h,
+          constraints: constraints.to_h
+        }
       end
 
       private
 
-      def overlay_options(source, overlay)
-        # Remove any blank values to avoid overwriting anything from source
-        overlay = overlay.delete_if { |_k, v| v.blank? }
-        source.deep_merge(overlay)
-      end
+      def load_name(input)
+        # GET /users
+        @name = "#{http_client.request.http_verb.upcase} #{http_client.request.url}"
 
-      def load_name(name, input)
-        @name = input[:name].presence || name
+        # GET /users - Returns a 404
+        if (name = input[:name].resolve.presence)
+          @name += " - #{name}"
+        end
       end
 
       def load_variables(input)
         @variables = Attribute.bind_variables(input[:variables], input[:variables])
       end
 
+      def load_debug(input)
+        @debug = input[:debug].resolve
+      end
+
       def load_constraints(input)
         constraints = Attribute.bind_variables(input[:expect], variables)
         @constraints = Constraint.new(**constraints)

data/lib/spec_forge/spec.rb

@@ -5,13 +5,13 @@ require_relative "spec/expectation"
 module SpecForge
   class Spec
     #
-    # Loads the specs from their yml files and runs them
+    # Loads the specs from their yml files and defines them with the test runner
     #
     # @param path [String, Path] The base path where the specs directory is located
     #
-    def self.load_and_run(base_path)
+    def self.load_and_define(base_path)
       specs = load_from_path(base_path.join("specs", "**/*.yml"))
-      specs.each(&:run)
+      specs.each(&:define)
     end
 
     #
@@ -40,6 +40,8 @@ module SpecForge
 
     ############################################################################
 
+    attr_predicate :debug
+
     attr_reader :name, :file_path, :expectations
 
     #
@@ -55,23 +57,27 @@ module SpecForge
       @file_path = file_path
 
       input = Normalizer.normalize_spec!(input)
-      global_options = input.except(:expectations)
+
+      # Don't pass this down to the expectations
+      @debug = input.delete(:debug) || false
+
+      global_options = normalize_global_options(input)
 
       @expectations =
         input[:expectations].map.with_index do |expectation_input, index|
-          Expectation.new(
-            "expectations (item #{index})",
-            expectation_input,
-            global_options:
-          )
+          Expectation.new(expectation_input, global_options:)
         end
     end
 
-    #
-    # Runs the spec
-    #
-    def run
-      Runner.new(self).run
+    def define
+      Runner.define_spec(self)
+    end
+
+    private
+
+    def normalize_global_options(input)
+      config = SpecForge.configuration.to_h.slice(:base_url, :headers, :query)
+      Configuration.overlay_options(config, input.except(:expectations))
     end
   end
 end

data/lib/spec_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpecForge
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/spec_forge.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+
 require "active_support"
 require "active_support/core_ext"
 require "commander"
@@ -17,8 +18,7 @@ require "yaml"
 
 require_relative "spec_forge/attribute"
 require_relative "spec_forge/cli"
-require_relative "spec_forge/config"
-require_relative "spec_forge/environment"
+require_relative "spec_forge/configuration"
 require_relative "spec_forge/error"
 require_relative "spec_forge/factory"
 require_relative "spec_forge/http"
@@ -35,10 +35,15 @@ module SpecForge
   # @param path [String] The file path that contains factories and specs
   #
   def self.run(path = SpecForge.forge)
-    SpecForge.environment.load
+    forge_helper = path.join("forge_helper.rb")
+    require_relative forge_helper if File.exist?(forge_helper)
+
+    configuration.validate
 
     Factory.load_and_register(path)
-    Spec.load_and_run(path)
+    Spec.load_and_define(path)
+
+    Runner.run
   end
 
   #
@@ -60,12 +65,20 @@ module SpecForge
   end
 
   #
-  # Returns SpecForge's config
+  # Returns SpecForge's configuration
   #
   # @return [Config]
   #
-  def self.config
-    @config ||= Config.new
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  #
+  # Yields SpecForge's configuration to a block
+  #
+  def self.configure(&block)
+    block&.call(configuration)
+    configuration
   end
 
   #
@@ -83,8 +96,4 @@ module SpecForge
       cleaner
     end
   end
-
-  def self.environment
-    @environment ||= Environment.new
-  end
 end

data/lib/templates/forge_helper.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##########################################
+# Framework Integration
+##########################################
+
+# Rails Integration
+# require_relative "../config/environment"
+
+# RSpec Integration (includes your existing configurations)
+# require_relative "../spec/spec_helper"
+
+# Custom requires (models, libraries, etc)
+# Dir[File.join(__dir__, "..", "lib", "**", "*.rb")].sort.each { |f| require f }
+
+##########################################
+# Configuration
+##########################################
+
+SpecForge.configure do |config|
+  # Base configuration
+  config.base_url = "http://localhost:3000"
+
+  # Default request headers
+  config.headers = {
+    "Authorization" => "Bearer #{ENV.fetch("API_TOKEN", "")}"
+  }
+
+  # Optional: Default query parameters
+  # config.query = {api_key: ENV['API_KEY']}
+
+  # Factory configuration
+  # config.factories.auto_discover = false        # Default: true
+  # config.factories.paths += ["lib/factories"]   # Adds to default paths
+
+  # Debug configuration
+  # Available in specs with debug: true (aliases: breakpoint, pry)
+  # Defaults to printing state overview (-> { puts inspect })
+  # Available context: expectation, variables, request, response,
+  #                   expected_status, expected_json
+  # config.on_debug { binding.pry }
+
+  # Test Framework Configuration
+  # Useful for database cleaners, test data setup, etc
+  # config.specs.before(:suite) { }
+  # config.specs.around { |example| example.run }
+  # config.specs.formatter = :documentation
+end

data/spec_forge/forge_helper.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+## Using Rails? Uncomment to load your app
+# ENV["RAILS_ENV"] ||= "test"
+# require_relative "../config/environment"
+
+## Not using Rails? Load anything you need here
+# Dir[SpecForge.root.join("lib", "my_api", "models", "**/*.rb")].sort.each { |path| require path }
+
+## Using RSpec? Uncomment to use your existing configurations
+# require_relative "../spec/spec_helper"
+
+SpecForge.configure do |config|
+  ## Base URL prefix for all API requests. All test paths will be appended to this URL
+  config.base_url = "http://localhost:3000"
+
+  ## Default request headers - commonly used for authentication and content negotiation
+  api_token = ENV.fetch("API_TOKEN", "")
+  config.headers = {
+    "Authorization" => "Bearer #{api_token}"
+  }
+
+  ## Default query parameters - useful for API keys or additional request context
+  # config.query = {api_token:}
+
+  ## Factory configuration options
+  ##
+  ## Enable/disable automatic factory discovery. When enabled, SpecForge will automatically
+  ## load factories from FactoryBot's default paths. Note: Factories defined in
+  ## "spec_forge/factories" are always loaded regardless of this setting.
+  # config.factories.auto_discover = false  # Default: true
+
+  ##
+  ## Additional paths, relative to the project folder, for discovering FactoryBot factories
+  ## By default, FactoryBot looks in "spec/factories" and "test/factories"
+  # config.factories.paths += ["custom/factories/path"]
+end

data/spec_forge/specs/users.yml

@@ -7,15 +7,17 @@ index_users:
 show_user:
   url: /users/{id}
   expectations:
-  - expect:
+  - query:
+      id: -1
+    expect:
       status: 404
-  - expect:
+  - query:
+      id: 1
+    expect:
       status: 200
       json:
         name: kind_of.string
         email: /\w+@example\.com/i
-    query:
-      id: 1
 
 create_user:
   url: /users