spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/normalizers/_shared.yml

@@ -0,0 +1,74 @@
+id: string
+
+name: string
+
+line_number: integer
+
+base_url:
+  type: string
+  default: null
+  required: false
+
+url:
+  type: string
+  default: null
+  required: false
+  aliases:
+  - path
+
+http_verb:
+  type: string
+  default: null # Do not default this to "GET". Leave it null. Seriously.
+  required: false
+  aliases:
+  - method
+  - http_method
+  validator: http_verb
+
+headers:
+  type: hash
+  default: {}
+  required: false
+
+query:
+  type:
+  - hash
+  - string
+  aliases:
+  - params
+  default: {}
+  required: false
+
+body:
+  type:
+  - hash
+  - string
+  aliases:
+  - data
+  default: {}
+  required: false
+
+variables:
+  type:
+  - hash
+  - string
+  default: {}
+  required: false
+
+debug:
+  type: boolean
+  aliases:
+  - pry
+  - breakpoint
+  default: false
+  required: false
+
+callback:
+  type: string
+  required: false
+  validator: callback
+
+documentation:
+  type: boolean
+  required: false
+  default: true

data/lib/spec_forge/normalizers/configuration.yml

@@ -0,0 +1,23 @@
+base_url: string
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+factories:
+  type: hash
+  default: {}
+  structure:
+    ###########################################
+    auto_discover:
+      type: boolean
+      default: true
+
+    paths:
+      type: array
+      default: []
+
+on_debug:
+  type: proc

data/lib/spec_forge/normalizers/constraint.yml

@@ -0,0 +1,8 @@
+status:
+- integer
+- string
+json:
+  type:
+  - hash
+  - array
+  default: {}

data/lib/spec_forge/normalizers/expectation.yml

@@ -0,0 +1,47 @@
+# Internal
+id:
+  reference: id
+
+line_number:
+  reference: line_number
+
+# User defined
+name:
+  reference: name
+
+base_url:
+  reference: base_url
+
+url:
+  reference: url
+
+http_verb:
+  reference: http_verb
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+body:
+  reference: body
+
+variables:
+  reference: variables
+
+debug:
+  reference: debug
+
+store_as:
+  type: string
+  default: ""
+
+documentation:
+  reference: documentation
+
+expect:
+  type: hash
+  structure:
+    ###########################################
+    reference: constraint

data/lib/spec_forge/normalizers/factory.yml

@@ -0,0 +1,12 @@
+model_class:
+  type: string
+  default: ""
+  aliases:
+  - class
+
+variables:
+  reference: variables
+
+attributes:
+  type: hash
+  default: {}

data/lib/spec_forge/normalizers/factory_reference.yml

@@ -0,0 +1,15 @@
+attributes:
+  type: hash
+  default: {}
+
+build_strategy:
+  type: string
+  default: create
+  aliases:
+  - strategy
+
+size:
+  type: integer
+  default: 0
+  aliases:
+  - count

data/lib/spec_forge/normalizers/global_context.yml

@@ -0,0 +1,28 @@
+variables:
+  reference: variables
+
+callbacks:
+  type: array
+  default: []
+  structure:
+    ###########################################
+    type: hash
+    default: {}
+    structure:
+      ###########################################
+      before_file:
+        reference: callback
+      before_spec:
+        reference: callback
+      before_each:
+        reference: callback
+        aliases:
+        - before
+      after_each:
+        reference: callback
+        aliases:
+        - after
+      after_spec:
+        reference: callback
+      after_file:
+        reference: callback

data/lib/spec_forge/normalizers/spec.yml

@@ -0,0 +1,50 @@
+# Internal
+id:
+  reference: id
+
+name:
+  reference: name
+
+file_name: string
+
+file_path: string
+
+line_number:
+  reference: line_number
+
+# User defined
+base_url:
+  reference: base_url
+
+url:
+  reference: url
+
+http_verb:
+  reference: http_verb
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+body:
+  reference: body
+
+variables:
+  reference: variables
+
+debug:
+  reference: debug
+
+documentation:
+  reference: documentation
+
+expectations:
+  type: array
+  structure:
+    ###########################################
+    type: hash
+    structure:
+      ###########################################
+      reference: expectation

data/lib/spec_forge/runner/adapter.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Bridges SpecForge specs with RSpec execution
+    #
+    # Converts SpecForge forge objects into RSpec test structures
+    # and manages the test execution lifecycle.
+    #
+    class Adapter
+      include Singleton
+
+      #
+      # Configures RSpec with forge definitions
+      #
+      # Sets up RSpec and prepares everything for running tests
+      #
+      # @param forges [Array<Forge>] The forges to set up for testing
+      #
+      def self.setup(forges)
+        # Defines the forges with RSpec
+        forges.each { |forge| instance.describe(forge) }
+
+        # Disable autorun because RSpec does it
+        RSpec::Core::Runner.disable_autorun!
+
+        # Allows modifying the error backtrace reporting within rspec
+        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+
+        # Listen for passed/failed events to trigger the "after_each" callback
+        RSpec.configuration.reporter.register_listener(
+          Listener.instance,
+          :example_passed, :example_failed
+        )
+      end
+
+      #
+      # Executes the configured RSpec tests
+      #
+      # Runs all configured tests through RSpec with optional exit behavior.
+      #
+      # @param exit_on_finish [Boolean] Whether to exit the process when done
+      # @param exit_on_failure [Boolean] Whether to exit the process if any test fails
+      #
+      # @return [Integer, nil] Exit status if exit_on_finish is false
+      #
+      def self.run(exit_on_finish: false, exit_on_failure: false)
+        status = RSpec::Core::Runner.run([]).to_i
+
+        exit(status) if exit_on_finish || (exit_on_failure && status != 0)
+
+        status
+      end
+
+      ##########################################################################
+
+      #
+      # Defines RSpec examples for a specific forge
+      # Creates the test structure for a single forge file
+      #
+      # @param forge [Forge] The forge to define
+      #
+      def describe(forge)
+        # This is just like writing a normal RSpec test, except with loops ;)
+        RSpec.describe(forge.name) do
+          # Callback for the file
+          before(:context) { Callbacks.before_file(forge) }
+          after(:context) { Callbacks.after_file(forge) }
+
+          # Specs
+          forge.specs.each do |spec|
+            # Describe the spec
+            describe(spec.name) do
+              # Request data is for the spec and contains the base and overlays
+              let!(:request_data) { forge.request[spec.id] }
+
+              # The HTTP client for the spec
+              let!(:http_client) { HTTP::Client.new(**request_data[:base]) }
+
+              # Callback for the spec
+              before(:context) { Callbacks.before_spec(forge, spec) }
+              after(:context) { Callbacks.after_spec(forge, spec) }
+
+              # Expectations
+              spec.expectations.each do |expectation|
+                # Onto the actual expectation itself
+                describe(expectation.name) do
+                  # Set metadata for the example group for error reporting
+                  Metadata.set_for_group(spec, expectation, self)
+
+                  # Lazily load the constraints
+                  let(:constraints) { expectation.constraints.as_matchers }
+
+                  let(:match_status) { constraints[:status] }
+                  let(:match_json) { constraints[:json] }
+                  let(:match_json_class) { be_kind_of(match_json.class) }
+                  let(:match_headers) { constraints[:headers] }
+
+                  # The request for the test itself. Overlays the expectation's data if it exists
+                  let(:request) do
+                    request = request_data[:base]
+
+                    if (overlay = request_data[:overlay][expectation.id])
+                      request = request.deep_merge(overlay)
+                    end
+
+                    HTTP::Request.new(**request)
+                  end
+
+                  # The Faraday response
+                  subject(:response) { http_client.call(request) }
+
+                  # Callbacks for the expectation
+                  before :each do
+                    Callbacks.before_expectation(
+                      forge, spec, expectation, self, RSpec.current_example
+                    )
+                  end
+
+                  # The 'after_expectation' callback is handled by Listener due to RSpec not
+                  # reporting the example's status until after the describe block has finished.
+                  after :each do
+                    # However, the downside about having the callback triggered later is that RSpec
+                    # will have reset the memoized let variables back to nil.
+                    # This causes an issue when an expectation goes to store the state, it will end
+                    # up re-calling the various variables and triggering another HTTP request.
+                    # Since the variables are still memoized in this hook, it is the perfect
+                    # time to store the referenced to them.
+                    State.set(response:)
+                  end
+
+                  # The test itself
+                  it(expectation.constraints.description) do
+                    # Debugging
+                    if spec.debug? || expectation.debug?
+                      Callbacks.on_debug(forge, spec, expectation, self)
+                    end
+
+                    ############################################################
+                    # Status check
+                    expect(response.status).to match_status
+
+                    ############################################################
+                    # Headers check
+                    if match_headers.present?
+                      match_headers.each do |key, matcher|
+                        expect(response.headers).to include(key.downcase => matcher)
+                      end
+                    end
+
+                    ############################################################
+                    # JSON check
+                    if match_json.present?
+                      expect(response.body).to match_json_class
+
+                      case match_json
+                      when Hash
+                        match_json.each do |key, matcher|
+                          expect(response.body).to include(key)
+
+                          begin
+                            expect(response.body[key]).to matcher
+                          rescue RSpec::Expectations::ExpectationNotMetError => e
+                            # Add the key that failed to the front of the error message
+                            e.message.insert(0, "Key: #{key.in_quotes}\n")
+                            raise e
+                          end
+                        end
+                      else
+                        expect(response.body).to match_json
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/runner/debug_proxy.rb

@@ -179,14 +179,14 @@ module SpecForge
         expectation_hash[:expect][:json] = matchers_to_description(expectation_hash[:expect][:json])
 
         {
+          global:,
+          variables:,
+          request: request.to_h,
           response: {
             status: response.status,
             body: response.body,
             headers: response.headers
           },
-          global:,
-          variables:,
-          request: request.to_h,
           expectation: expectation_hash,
           spec: spec_hash
         }

data/lib/spec_forge/runner/state.rb

@@ -87,11 +87,10 @@ module SpecForge
           scope:,
           request: request&.to_h,
           variables: SpecForge.context.variables.deep_dup,
-          response: {
-            headers: response&.headers,
-            status: response&.status,
-            body: response&.body
-          }
+          response:,
+          headers: response&.headers,
+          status: response&.status,
+          body: response&.body
         )
       end
     end

data/lib/spec_forge/runner.rb

@@ -8,150 +8,66 @@ module SpecForge
   class Runner
     class << self
       #
-      # Defines RSpec examples for a collection of forges
-      # Creates the test structure that will be executed
+      # Prepares forge objects for test execution
       #
-      # @param forges [Array<Forge>] The forges to define as RSpec examples
+      # Loads the forge helper, registers factories, loads specs from files,
+      # applies filtering, and returns ready-to-run forge objects.
       #
-      def define(forges)
-        forges.each do |forge|
-          define_forge(forge)
-        end
-      end
-
-      #
-      # Runs the defined RSpec examples
-      # Executes the tests after they've been defined
-      #
-      def run
-        prepare_for_run
-
-        ARGV.clear
-        RSpec::Core::Runner.invoke
-      end
-
-      #
-      # Defines RSpec examples for a specific forge
-      # Creates the test structure for a single forge file
+      # @param file_name [String, nil] Optional file name filter
+      # @param spec_name [String, nil] Optional spec name filter
+      # @param expectation_name [String, nil] Optional expectation name filter
       #
-      # @param forge [Forge] The forge to define
+      # @return [Array<Forge>] Array of prepared forge objects
       #
-      def define_forge(forge)
-        # This is just like writing a normal RSpec test, except with loops ;)
-        RSpec.describe(forge.name) do
-          # Callback for the file
-          before(:context) { Callbacks.before_file(forge) }
-          after(:context) { Callbacks.after_file(forge) }
-
-          # Specs
-          forge.specs.each do |spec|
-            # Describe the spec
-            describe(spec.name) do
-              # Request data is for the spec and contains the base and overlays
-              let!(:request_data) { forge.request[spec.id] }
-
-              # The HTTP client for the spec
-              let!(:http_client) { HTTP::Client.new(**request_data[:base]) }
-
-              # Callback for the spec
-              before(:context) { Callbacks.before_spec(forge, spec) }
-              after(:context) { Callbacks.after_spec(forge, spec) }
-
-              # Expectations
-              spec.expectations.each do |expectation|
-                # Onto the actual expectation itself
-                describe(expectation.name) do
-                  # Set metadata for the example group for error reporting
-                  Metadata.set_for_group(spec, expectation, self)
+      def prepare(file_name: nil, spec_name: nil, expectation_name: nil)
+        load_forge_helper
 
-                  # Lazily load the constraints
-                  let(:constraints) { expectation.constraints.as_matchers }
+        # Load factories
+        Factory.load_and_register
 
-                  let(:match_status) { constraints[:status] }
-                  let(:match_json) { constraints[:json] }
-                  let(:match_json_class) { be_kind_of(match_json.class) }
+        # Load the specs from their files and create forges from them
+        forges = Loader.load_from_files.map { |f| Forge.new(*f) }
 
-                  # The request for the test itself. Overlays the expectation's data if it exists
-                  let(:request) do
-                    request = request_data[:base]
+        # Filter out the specs and expectations
+        forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
 
-                    if (overlay = request_data[:overlay][expectation.id])
-                      request = request.deep_merge(overlay)
-                    end
+        # Tell the user that we filtered if we did
+        Filter.announce(forges, file_name:, spec_name:, expectation_name:)
 
-                    HTTP::Request.new(**request)
-                  end
-
-                  # The Faraday response
-                  subject(:response) { http_client.call(request) }
-
-                  # Callbacks for the expectation
-                  before :each do
-                    Callbacks.before_expectation(
-                      forge, spec, expectation, self, RSpec.current_example
-                    )
-                  end
-
-                  # The 'after_expectation' callback is handled by Listener due to RSpec not
-                  # reporting the example's status until after the describe block has finished.
-                  after :each do
-                    # However, the downside about having the callback triggered later is that RSpec
-                    # will have reset the memoized let variables back to nil.
-                    # This causes an issue when an expectation goes to store the state, it will end
-                    # up re-calling the various variables and triggering another HTTP request.
-                    # Since the variables are still memoized in this hook, it is the perfect
-                    # time to store the referenced to them.
-                    State.set(response:)
-                  end
-
-                  # The test itself
-                  it(expectation.constraints.description) do
-                    if spec.debug? || expectation.debug?
-                      Callbacks.on_debug(forge, spec, expectation, self)
-                    end
-
-                    # Status check
-                    expect(response.status).to match_status
-
-                    # JSON check
-                    if match_json.present?
-                      expect(response.body).to match_json_class
+        forges
+      end
 
-                      case match_json
-                      when Hash
-                        # Check per key for easier debugging
-                        match_json.each do |key, matcher|
-                          expect(response.body).to have_key(key)
-                          expect(response.body[key]).to matcher
-                        end
-                      else
-                        expect(response.body).to match_json
-                      end
-                    end
-                  end
-                end
-              end
-            end
-          end
-        end
+      #
+      # Runs the prepared forges through RSpec
+      #
+      # Sets up the RSpec adapter and executes all tests, with optional
+      # exit behavior for CLI usage.
+      #
+      # @param forges [Array<Forge>] The forge objects to run
+      # @param exit_on_finish [Boolean] Whether to exit the process when complete
+      # @param exit_on_failure [Boolean] Whether to exit the process if any test fails
+      #
+      # @return [Integer, nil] Exit status if exit_on_finish is false
+      #
+      def run(forges, **)
+        Adapter.setup(forges)
+        Adapter.run(**)
       end
 
       private
 
-      def prepare_for_run
-        # Allows modifying the error backtrace reporting within rspec
-        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+      def load_forge_helper
+        forge_helper = SpecForge.forge_path.join("forge_helper.rb")
+        require_relative forge_helper if File.exist?(forge_helper)
 
-        # Listen for passed/failed events to trigger the "after_each" callback
-        RSpec.configuration.reporter.register_listener(
-          Listener.instance,
-          :example_passed, :example_failed
-        )
+        # Validate in case anything was changed
+        SpecForge.configuration.validate
       end
     end
   end
 end
 
+require_relative "runner/adapter"
 require_relative "runner/callbacks"
 require_relative "runner/debug_proxy"
 require_relative "runner/listener"