spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/runner/debug_proxy.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Creates a debugging environment during test execution.
+    # When a breakpoint is triggered, this provides an interface to inspect
+    # the current test state including the request, response, variables, and expectations.
+    #
+    # By default, this outputs a JSON representation of the current testing context,
+    # but it can be customized by configuring SpecForge.configuration.on_debug
+    # to use any Ruby debugger (like pry or debug).
+    #
+    # @example Basic usage in a spec with `debug: true`
+    #   # In your YAML test:
+    #   get_users:
+    #     debug: true
+    #     path: /users
+    #     expectations:
+    #     - expect:
+    #         status: 200
+    #
+    # @example Custom debug handler in forge_helper.rb
+    #   SpecForge.configure do |config|
+    #     config.on_debug { binding.pry } # Requires 'pry' gem
+    #   end
+    #
+    class DebugProxy
+      #
+      # @return [Proc] The default debugging handler that outputs JSON state information
+      #
+      def self.default
+        -> { puts inspect }
+      end
+
+      # @return [RSpec::Forge] The current Forge that is being tested
+      attr_reader :forge
+
+      # @return [SpecForge::Spec] The current Spec that is being tested
+      attr_reader :spec
+
+      # @return [SpecForge::Spec::Expectation] The current expectation that is being tested
+      attr_reader :expectation
+
+      # @return [RSpec::ExampleGroup] The current RSpec example group
+      attr_reader :example_group
+
+      # @return [RSpec::Example] The current RSpec example that is running
+      attr_reader :example
+
+      # @return [Integer] The expected HTTP status code
+      attr_reader :expected_status
+
+      # @return [Object] The expected response body structure
+      attr_reader :expected_json
+
+      delegate_missing_to :@example_group
+
+      #
+      # Creates a new DebugProxy instance
+      #
+      # @param forge [SpecForge::Forge] The forge being tested
+      # @param spec [SpecForge::Spec] The spec being tested
+      # @param expectation [SpecForge::Spec::Expectation] The expectation being tested
+      # @param example_group [RSpec::Core::ExampleGroup] The current example group
+      #
+      # @return [SpecForge::Runner::DebugProxy]
+      #
+      def initialize(forge, spec, expectation, example_group)
+        @callback = SpecForge.configuration.on_debug
+
+        @forge = forge
+        @spec = spec
+        @expectation = expectation
+        @example_group = example_group
+        @example = RSpec.current_example
+
+        constraints = expectation.constraints
+
+        @expected_status = constraints.status.resolved
+        @expected_json = constraints.json.resolved
+      end
+
+      #
+      # Triggers the debugging environment
+      #
+      # Displays available debugging contexts and executes the configured debug callback.
+      # The callback runs in the context of this proxy, giving it access to all helper methods.
+      #
+      # @return [void]
+      #
+      def call
+        puts <<~STRING
+
+          Debug triggered for:
+          > #{example.metadata[:rerun_file_path]} on line #{expectation.line_number}
+
+          Available debugging contexts:
+          - spec: Current spec details
+          - expectation: Current expectation being tested
+          - variables: Variables defined for this test
+          - global: Global context shared across tests
+          - store: Stored data from expectations
+
+          Request & Response:
+          - request: HTTP request details (method, url, headers, body)
+          - response: HTTP response with headers, status and body
+
+          Expectations:
+          - expected_status: Expected HTTP status code
+          - expected_json: Expected response body structure
+
+          Matchers:
+          - match_status: Matcher used to test status
+          - match_json: Matcher used to test response body
+
+          Helper objects:
+          - http_client: The HTTP client used for the request
+          - request_data: Raw request configuration data
+          - example_group: Current RSpec example group
+          - example: Current RSpec example
+          - forge: Current file being tested
+
+          💡 Pro tips:
+            - Type 'self' or 'inspect' for a pretty-printed JSON overview
+            - Use 'to_h' for the hash representation
+            - Access the shared context with 'SpecForge.context'
+        STRING
+
+        instance_exec(&@callback)
+      end
+
+      ##########################################################################
+
+      #
+      # Returns a hash representation of the global context
+      #
+      # @return [Hash] The global context with resolved variables
+      #
+      def global
+        @global ||= SpecForge.context.global.to_h
+      end
+
+      #
+      # Returns a hash representation of the variables in the current context
+      #
+      # Includes both spec-level and expectation-level variables combined
+      # with values fully resolved.
+      #
+      # @return [Hash]
+      #
+      def variables
+        @variables ||= SpecForge.context.variables
+      end
+
+      #
+      # Returns a hash representation of the store context
+      #
+      # @return [Hash] The store context
+      #
+      def store
+        @store ||= SpecForge.context.store.to_h
+      end
+
+      ##########################################################################
+
+      #
+      # Returns a hash representation of the test state
+      #
+      # Includes the spec, expectation, request, response, variables and global context.
+      # RSpec matchers are converted to human-readable descriptions.
+      #
+      # @return [Hash]
+      #
+      def to_h
+        spec_hash = spec.to_h.except(:expectations)
+
+        expectation_hash = expectation.to_h
+        expectation_hash[:expect][:json] = matchers_to_description(expectation_hash[:expect][:json])
+
+        {
+          response: {
+            status: response.status,
+            body: response.body,
+            headers: response.headers
+          },
+          global:,
+          variables:,
+          request: request.to_h,
+          expectation: expectation_hash,
+          spec: spec_hash
+        }
+      end
+
+      #
+      # Returns a formatted JSON representation of the test state
+      #
+      # @return [String] Pretty-printed JSON of the test state
+      #
+      def inspect
+        JSON.pretty_generate(to_h)
+      end
+
+      private
+
+      def matchers_to_description(value)
+        return value unless value.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
+
+        value.description
+      end
+    end
+  end
+end

data/lib/spec_forge/runner/listener.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Listens for RSpec test result notifications and triggers the appropriate callbacks
+    #
+    # This singleton class receives notifications from RSpec when examples pass or fail,
+    # retrieves the current test context, and triggers the appropriate SpecForge callbacks.
+    # It acts as a bridge between RSpec's notification system and SpecForge's callback system.
+    #
+    class Listener
+      include Singleton
+
+      #
+      # Handles RSpec notifications for passing examples
+      #
+      # @param notification [RSpec::Core::Notifications::ExampleNotification]
+      #   The notification object
+      #
+      def example_passed(notification)
+        trigger_callback
+      end
+
+      #
+      # Handles RSpec notifications for failing examples
+      #
+      # @param notification [RSpec::Core::Notifications::FailedExampleNotification]
+      #   The notification object
+      #
+      def example_failed(notification)
+        trigger_callback
+      end
+
+      private
+
+      #
+      # Triggers the appropriate SpecForge callback with the complete context
+      #
+      # Retrieves the current example context stored during the RSpec execution, and passes
+      # everything to the appropriate callback.
+      #
+      # @private
+      #
+      def trigger_callback
+        context = Runner::State.current.to_h.slice(
+          :forge, :spec, :expectation, :example_group, :example
+        )
+
+        Runner::Callbacks.after_expectation(*context.values)
+      end
+    end
+  end
+end

data/lib/spec_forge/runner/metadata.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Manages metadata for RSpec example groups and examples
+    #
+    # This class provides methods for setting up correct metadata on RSpec groups
+    # and examples, which enables proper error reporting and command-line rerun
+    # instructions when tests fail.
+    #
+    # @example Setting metadata on an example group
+    #   Metadata.set_for_group(spec, expectation, example_group)
+    #
+    class Metadata
+      class << self
+        #
+        # Updates the example group metadata for error reporting
+        #
+        # Sets the file path, line number, and location information in the
+        # example group's metadata. This ensures that RSpec can generate the
+        # proper command to rerun the failing tests.
+        #
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The example group to update
+        #
+        def set_for_group(spec, expectation, example_group)
+          metadata = {
+            file_path: spec.file_path,
+            absolute_file_path: spec.file_path,
+            line_number: expectation.line_number,
+            location: spec.file_path,
+            rerun_file_path: "#{spec.file_name}:#{spec.name}:\"#{expectation.name}\""
+          }
+
+          example_group.metadata.merge!(metadata)
+        end
+
+        #
+        # Updates the current example's metadata for error reporting
+        #
+        # Sets location information on the currently running example.
+        # This helps RSpec generate more accurate error messages when
+        # an exception occurs during test execution.
+        #
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        #
+        def set_for_example(spec, expectation)
+          metadata = {location: "#{spec.file_path}:#{expectation.line_number}"}
+
+          RSpec.current_example.metadata.merge!(metadata)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/runner/state.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Maintains test execution state to prevent duplicate HTTP requests
+    #
+    # This singleton class captures and preserves references to the current test context,
+    # including request and response objects that would otherwise be re-evaluated
+    # when accessed after RSpec clears its memoized variables. It solves a specific
+    # issue where accessing response data in after_expectation callbacks would
+    # trigger duplicate HTTP requests.
+    #
+    class State < Struct.new(
+      :forge, :spec, :expectation, :example_group, :example, :response, :request
+    )
+      include Singleton
+
+      #
+      # Returns the singleton instance representing the current test state
+      #
+      # @return [State] The current state instance
+      #
+      def self.current
+        instance
+      end
+
+      #
+      # Updates multiple attributes of the state at once
+      #
+      # @param attributes [Hash] A hash mapping attribute names to values
+      #
+      def self.set(attributes)
+        attributes.each do |key, value|
+          instance[key] = value
+        end
+      end
+
+      #
+      # Persists the current state to the context store if needed
+      #
+      # Only runs if the current expectation has a store_as directive
+      #
+      def self.persist
+        return unless instance.expectation.store_as?
+
+        instance.persist_to_store
+      end
+
+      #
+      # Clears all state attributes
+      #
+      def self.clear
+        instance.clear
+      end
+
+      ##########################################################################
+
+      #
+      # Clears all attributes in the state
+      #
+      def clear
+        members.each { |key| self[key] = nil }
+      end
+
+      #
+      # Persists the current test execution data to the context store
+      #
+      # Handles scope determination and stores request/response data
+      # for later access via the store attribute
+      #
+      def persist_to_store
+        id = expectation.store_as
+        scope = :file
+
+        # Remove the file prefix if it was explicitly provided
+        id = id.delete_prefix("file.") if id.start_with?("file.")
+
+        # Change scope to spec if desired
+        if id.start_with?("spec.")
+          id = id.delete_prefix("spec.")
+          scope = :spec
+        end
+
+        SpecForge.context.store.set(
+          id,
+          scope:,
+          request: request&.to_h,
+          variables: SpecForge.context.variables.deep_dup,
+          response: {
+            headers: response&.headers,
+            status: response&.status,
+            body: response&.body
+          }
+        )
+      end
+    end
+  end
+end

data/lib/spec_forge/runner.rb

@@ -1,58 +1,134 @@
 # frozen_string_literal: true
 
 module SpecForge
+  #
+  # Handles the execution of specs through RSpec
+  # Converts SpecForge specs into RSpec examples and runs them
+  #
   class Runner
     class << self
       #
-      # Runs any specs
+      # Defines RSpec examples for a collection of forges
+      # Creates the test structure that will be executed
       #
-      def run
-        RSpec::Core::Runner.disable_autorun!
-        RSpec::Core::Runner.run([], $stderr, $stdout)
+      # @param forges [Array<Forge>] The forges to define as RSpec examples
+      #
+      def define(forges)
+        forges.each do |forge|
+          define_forge(forge)
+        end
       end
 
       #
-      # Defines a spec with RSpec
+      # Runs the defined RSpec examples
+      # Executes the tests after they've been defined
       #
-      # @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
-              # Set up the class metadata for error reporting
-              runner_forge.set_group_metadata(self, spec_forge, expectation)
-
-              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
-
-                # Set up the example metadata for error reporting
-                runner_forge.set_example_metadata(spec_forge, expectation)
-              end
-
-              subject(:response) { expectation.http_client.call }
-
-              it do
-                if spec_forge.debug? || expectation.debug?
-                  runner_forge.handle_debug(expectation, self)
-                end
+      def run
+        prepare_for_run
 
-                # Status check
-                expect(response.status).to eq(expected_status)
+        ARGV.clear
+        RSpec::Core::Runner.invoke
+      end
 
-                # JSON check
-                if constraints.json.size > 0
-                  expect(response.body).to be_kind_of(Hash)
-                  expect(response.body).to include(expected_json)
+      #
+      # Defines RSpec examples for a specific forge
+      # Creates the test structure for a single forge file
+      #
+      # @param forge [Forge] The forge to define
+      #
+      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)
+
+                  # 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) }
+
+                  # 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
+                    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
+
+                      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
@@ -60,86 +136,24 @@ module SpecForge
         end
       end
 
-      # @private
-      def handle_debug(...)
-        DebugProxy.new(...).call
-      end
-
-      # @private
-      def set_group_metadata(context, spec, expectation)
-        metadata = {
-          file_path: spec.file_path,
-          absolute_file_path: spec.file_path,
-          line_number: spec.line_number,
-          location: spec.file_path,
-          rerun_file_path: "#{spec.file_name}:#{spec.name}:\"#{expectation.name}\""
-        }
-
-        context.metadata.merge!(metadata)
-      end
-
-      # @private
-      def set_example_metadata(spec, expectation)
-        # This is needed when an error raises in an example
-        metadata = {location: "#{spec.file_path}:#{spec.line_number}"}
-
-        RSpec.current_example.metadata.merge!(metadata)
-      end
-    end
+      private
 
-    ################################################################################################
+      def prepare_for_run
+        # Allows modifying the error backtrace reporting within rspec
+        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
 
-    class DebugProxy
-      def self.default
-        -> { puts inspect }
-      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)
+        # Listen for passed/failed events to trigger the "after_each" callback
+        RSpec.configuration.reporter.register_listener(
+          Listener.instance,
+          :example_passed, :example_failed
+        )
       end
     end
   end
 end
+
+require_relative "runner/callbacks"
+require_relative "runner/debug_proxy"
+require_relative "runner/listener"
+require_relative "runner/metadata"
+require_relative "runner/state"