spec_forge 0.7.0 → 1.0.0

data/lib/spec_forge/runner/debug_proxy.rb

@@ -1,213 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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

@@ -1,58 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-# 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,75 +0,0 @@
-# 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
-      #
-      # Prepares forge objects for test execution
-      #
-      # Loads the forge helper, registers factories, loads specs from files,
-      # applies filtering, and returns ready-to-run forge objects.
-      #
-      # @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
-      #
-      # @return [Array<Forge>] Array of prepared forge objects
-      #
-      def prepare(file_name: nil, spec_name: nil, expectation_name: nil)
-        load_forge_helper
-
-        # Load factories
-        Factory.load_and_register
-
-        # Load the specs from their files and create forges from them
-        forges = Loader.load_from_files.map { |f| Forge.new(*f) }
-
-        # Filter out the specs and expectations
-        forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
-
-        # Tell the user that we filtered if we did
-        Filter.announce(forges, file_name:, spec_name:, expectation_name:)
-
-        forges
-      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 load_forge_helper
-        forge_helper = SpecForge.forge_path.join("forge_helper.rb")
-        require_relative forge_helper if File.exist?(forge_helper)
-
-        # 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"

data/lib/spec_forge/spec/expectation/constraint.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  class Spec
-    class Expectation
-      #
-      # Represents the expected response constraints for an expectation
-      #
-      # A Constraint defines what the API response should look like,
-      # including status code and body content with support for matchers.
-      #
-      # @example In code
-      #   constraint = Constraint.new(
-      #     status: 200,
-      #     headers: {response_header: "kind_of.string"},
-      #     json: {name: {"matcher.eq" => "John"}}
-      #   )
-      #
-      class Constraint < Data.define(:status, :headers, :json) # :xml, :html
-        #
-        # Creates a new constraint
-        #
-        # @param status [Integer, String] The expected HTTP status code, or reference to one
-        # @param headers [Hash] The expected headers with matchers
-        # @param json [Hash, Array] The expected JSON with matchers
-        #
-        # @return [Constraint] A new constraint instance
-        #
-        def initialize(status:, headers: {}, json: {})
-          super(
-            status: Attribute.from(status),
-            headers: Attribute.from(headers),
-            json: Attribute.from(json)
-          )
-        end
-
-        #
-        # Converts the constraint to a hash with resolved values
-        #
-        # @return [Hash] Hash representation with resolved values
-        #
-        def to_h
-          super.transform_values(&:resolve)
-        end
-
-        #
-        # Converts constraints to RSpec matchers for validation
-        #
-        # Transforms the defined constraints (status and JSON expectations) into
-        # appropriate RSpec matchers that can be used in test expectations.
-        # This method resolves all values and applies the appropriate matcher
-        # conversions to create a complete expectation structure.
-        #
-        # @return [Hash] A hash containing resolved matchers
-        #
-        # @example
-        #   constraint = Constraint.new(status: 200, json: {name: "John"})
-        #   matchers = constraint.as_matchers
-        #   # => {status: eq(200), json: include("name" => eq("John"))}
-        #
-        def as_matchers
-          {
-            status: status.resolve_as_matcher,
-            json: resolve_json_matcher,
-            headers: resolve_hash_matcher(headers)
-          }
-        end
-
-        #
-        # Generates a human-readable description of what this constraint expects in the response
-        #
-        # Creates a description string for RSpec examples that clearly explains the expected
-        # status code and JSON structure. This makes test output more informative and helps
-        # developers understand what's being tested at a glance.
-        #
-        # @return [String] A human-readable description of the constraint expectations
-        #
-        # @example Status code with JSON object
-        #   constraint.description
-        #   # => "is expected to respond with \"200 OK\" and a JSON object that contains keys: \"id\", \"name\""
-        #
-        # @example Status code with JSON array
-        #   constraint.description
-        #   # => "is expected to respond with \"201 Created\" and a JSON array that contains 3 items"
-        #
-        def description
-          description = "is expected to respond with"
-
-          description += if status.is_a?(Attribute::Literal)
-            " #{HTTP.status_code_to_description(status.input).in_quotes}"
-          else
-            " the expected status code"
-          end
-
-          size = json.size
-
-          if Type.array?(json)
-            description +=
-              " and a JSON array that contains #{size} #{"item".pluralize(size)}"
-          elsif Type.hash?(json) && size > 0
-            keys = json.keys.join_map(", ", &:in_quotes)
-
-            description +=
-              " and a JSON object that contains #{"key".pluralize(size)}: #{keys}"
-          end
-
-          description
-        end
-
-        private
-
-        def resolve_json_matcher
-          case json
-          when HashLike
-            resolve_hash_matcher(json)
-          else
-            json.resolve_as_matcher
-          end
-        end
-
-        def resolve_hash_matcher(hash)
-          hash.transform_values(&:resolve_as_matcher).stringify_keys
-        end
-      end
-    end
-  end
-end

data/lib/spec_forge/spec/expectation.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  class Spec
-    #
-    # Represents a single test expectation within a spec
-    #
-    # An Expectation defines what should be tested for a specific API request,
-    # including the expected status code and response structure.
-    #
-    # @example YAML representation
-    #   - name: "Get user successfully"
-    #     expect:
-    #       status: 200
-    #       json:
-    #         name: kind_of.string
-    #
-    class Expectation < Data.define(
-      :id, :name, :line_number,
-      :debug, :store_as, :documentation, :constraints
-    )
-      #
-      # @return [Boolean] True if debugging is enabled
-      #
-      attr_predicate :debug
-
-      #
-      # @return [Boolean] True if store_as is set
-      #
-      attr_predicate :store_as
-
-      #
-      # Creates a new expectation with constraints
-      #
-      # @param id [String] Unique identifier
-      # @param name [String] Human-readable name
-      # @param line_number [Integer] Line number in source
-      # @param debug [Boolean] Whether to enable debugging
-      # @param store_as [String] Unique Context::Store identifier
-      # @param documentation [Boolean] Whether to include in documentation generation
-      # @param expect [Hash] Expected constraints
-      #
-      # @return [Expectation] A new expectation instance
-      #
-      def initialize(id:, name:, line_number:, debug:, store_as:, expect:, documentation:)
-        constraints = Constraint.new(**expect)
-
-        super(id:, name:, line_number:, debug:, store_as:, documentation:, constraints:)
-      end
-
-      #
-      # Converts the expectation to a hash representation
-      #
-      # @return [Hash] Hash representation
-      #
-      def to_h
-        {
-          name:,
-          line_number:,
-          debug:,
-          expect: constraints.to_h
-        }
-      end
-    end
-  end
-end
-
-require_relative "expectation/constraint"