spec_forge 0.5.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/callbacks.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Manages lifecycle hooks for test execution
+    #
+    # This class provides callback methods that run at specific points during test execution
+    # to prepare the test environment, manage state, and perform cleanup operations. These
+    # callbacks integrate with RSpec's test lifecycle and maintain the SpecForge context.
+    #
+    # @example Running before file callback
+    #   Callbacks.before_file(forge)
+    #
+    class Callbacks
+      class << self
+        #
+        # Callback executed before a file's specs are run
+        #
+        # Initializes global context and sets up any file-level state needed
+        # for all specs in the file.
+        #
+        # @param forge [SpecForge::Forge] The forge representing the current file
+        #
+        def before_file(forge)
+          # Set the global variables
+          SpecForge.context.global.set(**forge.global)
+
+          # Clear the store for this file
+          SpecForge.context.store.clear
+
+          # Start fresh
+          State.clear
+
+          # Run the user's before_file callbacks
+          run_user_callbacks(:before_file, file_context(forge))
+        end
+
+        #
+        # Callback executed before each spec is run
+        #
+        # Prepares the context for a specific spec, including loading
+        # spec-level variables and configuration.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec about to be executed
+        #
+        def before_spec(forge, spec)
+          # Prepare the variables for this spec
+          SpecForge.context.variables.set(**forge.variables_for_spec(spec))
+
+          # Clear any "spec" level stored data
+          SpecForge.context.store.clear_specs
+
+          # Run the user's before_spec callbacks
+          run_user_callbacks(:before_spec, spec_context(forge, spec))
+        end
+
+        #
+        # Callback executed before each expectation is run
+        #
+        # Prepares variables for the specific expectation and sets up
+        # example metadata for error reporting.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation about to be evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        # @param example [RSpec::Core::Example] The current example
+        #
+        def before_expectation(forge, spec, expectation, example_group, example)
+          # Store metadata to failure/error messages display the correct information
+          Metadata.set_for_example(spec, expectation)
+
+          # Store state data for callbacks and persisting data into the store
+          State.set(
+            forge:, spec:, expectation:, example_group:, example:,
+            request: example_group.request
+          )
+
+          # Load the variable overlay for this expectation (if one exists)
+          SpecForge.context.variables.use_overlay(expectation.id)
+
+          # Run the user's before_each callbacks
+          run_user_callbacks(:before_each, expectation_context(forge, spec, expectation, example))
+        end
+
+        #
+        # Handles debug mode for an expectation
+        #
+        # When debugging is enabled for a spec or expectation, this method
+        # creates a debugging environment for inspecting test state.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        #
+        def on_debug(forge, spec, expectation, example_group)
+          DebugProxy.new(forge, spec, expectation, example_group).call
+        end
+
+        #
+        # Callback executed after each expectation is run
+        #
+        # Performs cleanup and stores results if needed for future reference.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation that was evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        # @param example [RSpec::Core::Example] The current example
+        #
+        def after_expectation(forge, spec, expectation, example_group, example)
+          # Note: Let variables on `example_group` have been reset by RSpec at this point.
+          # Calling them will result in a new value being returned and memoized.
+          # In other words, do not call `example_group.response` in here unless you
+          # like potentially duplicating data ;)
+          State.persist
+
+          # Run the user's after_each callbacks
+          run_user_callbacks(:after_each, expectation_context(forge, spec, expectation, example))
+
+          # Clear the state for the next expectation
+          State.clear
+        end
+
+        #
+        # Callback executed after each spec is ran
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec that was executed
+        #
+        def after_spec(forge, spec)
+          # Run the user's after_spec callbacks
+          run_user_callbacks(:after_spec, spec_context(forge, spec))
+        end
+
+        #
+        # Callback executed after a file's specs have been ran
+        #
+        # @param forge [SpecForge::Forge] The forge representing the current file
+        #
+        def after_file(forge)
+          # Run the user's after_file callbacks
+          run_user_callbacks(:after_file, file_context(forge))
+        end
+
+        private
+
+        #
+        # Executes user-defined callbacks for a specific lifecycle point
+        #
+        # Processes the callback_type to extract timing and scope information,
+        # adds this metadata to the context, and then triggers all registered
+        # callbacks for that type.
+        #
+        # @param callback_type [Symbol, String] The type of callback to run
+        #   (:before_file, :after_spec, etc.)
+        # @param context [Hash] Context data containing state information for the callback
+        #
+        # @private
+        #
+        def run_user_callbacks(callback_type, context)
+          callback_timing, callback_scope = callback_type.to_s.split("_")
+
+          # Adds "before_each", "before", and "each" into the context so callbacks
+          # can build logic off of them
+          context.merge!(
+            callback_type: callback_type.to_s,
+            callback_timing:, callback_scope:
+          )
+
+          # Run the callbacks for this type
+          SpecForge.context.global.callbacks.run(callback_type, context)
+        end
+
+        #
+        # Builds the base context for file-level callbacks
+        #
+        # @param forge [SpecForge::Forge] The forge representing the file
+        #
+        # @return [Hash] Basic file context
+        #
+        # @private
+        #
+        def file_context(forge)
+          {
+            forge: forge,
+            file_path: forge.metadata[:file_path],
+            file_name: forge.metadata[:file_name]
+          }
+        end
+
+        #
+        # Builds context for spec-level callbacks
+        # Includes file context plus spec information
+        #
+        # @param forge [SpecForge::Forge] The forge representing the file
+        # @param spec [SpecForge::Spec] The spec being executed
+        #
+        # @return [Hash] Context with file and spec information
+        #
+        # @private
+        #
+        def spec_context(forge, spec)
+          file_context(forge).merge(
+            spec: spec,
+            spec_name: spec.name,
+            variables: SpecForge.context.variables
+          )
+        end
+
+        #
+        # Builds context for expectation-level callbacks
+        # Includes spec context plus expectation information
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        # @param example [RSpec::Core::Example] The current example
+        #
+        # @return [Hash] Context with file, spec and expectation information
+        #
+        # @private
+        #
+        def expectation_context(forge, spec, expectation, example)
+          example_group = State.current.example_group
+
+          # Pull this data from the State instead of example group to avoid creating a new value
+          request = State.current.request
+          response = State.current.response
+
+          spec_context(forge, spec).merge(
+            expectation:,
+            expectation_name: expectation.name,
+            request:,
+            response:,
+            example_group:,
+            example:
+          )
+        end
+      end
+    end
+  end
+end