spec_forge 0.5.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