spec_forge 0.5.0 → 0.7.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])
+
+        {
+          global:,
+          variables:,
+          request: request.to_h,
+          response: {
+            status: response.status,
+            body: response.body,
+            headers: response.headers
+          },
+          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,98 @@
+# 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,150 +1,75 @@
 # 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
+      # Prepares forge objects for test execution
       #
-      def run
-        # Allows me to modify the error backtrace reporting within rspec
-        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
-
-        RSpec::Core::Runner.disable_autorun!
-        RSpec::Core::Runner.run([], $stderr, $stdout)
-      end
-
+      # Loads the forge helper, registers factories, loads specs from files,
+      # applies filtering, and returns ready-to-run forge objects.
       #
-      # Defines a spec with RSpec
+      # @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 spec_forge [Spec] The spec to define
+      # @return [Array<Forge>] Array of prepared forge objects
       #
-      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 }
-              let!(:expected_json_class) { expected_json&.expected.class }
-
-              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 }
+      def prepare(file_name: nil, spec_name: nil, expectation_name: nil)
+        load_forge_helper
 
-              it do
-                if spec_forge.debug? || expectation.debug?
-                  runner_forge.handle_debug(expectation, self)
-                end
+        # Load factories
+        Factory.load_and_register
 
-                # Status check
-                expect(response.status).to eq(expected_status)
+        # Load the specs from their files and create forges from them
+        forges = Loader.load_from_files.map { |f| Forge.new(*f) }
 
-                # JSON check
-                if expected_json
-                  expect(response.body).to be_kind_of(expected_json_class)
-                  expect(response.body).to expected_json
-                end
-              end
-            end
-          end
-        end
-      end
-
-      # @private
-      def handle_debug(...)
-        DebugProxy.new(...).call
-      end
+        # Filter out the specs and expectations
+        forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
 
-      # @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}\""
-        }
+        # Tell the user that we filtered if we did
+        Filter.announce(forges, file_name:, spec_name:, expectation_name:)
 
-        context.metadata.merge!(metadata)
+        forges
       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
-
-    ################################################################################################
-
-    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
-          - expected_json_class: Expected response body class
-          - 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)
+      #
+      # 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
 
-      def inspect
-        hash = expectation.to_h
+      private
 
-        hash[:response] = {
-          headers: response.headers,
-          status: response.status,
-          body: response.body
-        }
+      def load_forge_helper
+        forge_helper = SpecForge.forge_path.join("forge_helper.rb")
+        require_relative forge_helper if File.exist?(forge_helper)
 
-        JSON.pretty_generate(hash)
+        # 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"
+require_relative "runner/metadata"
+require_relative "runner/state"