spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/runner.rb

@@ -1,62 +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
+      #
+      # @param forges [Array<Forge>] The forges to define as RSpec examples
+      #
+      def define(forges)
+        forges.each do |forge|
+          define_forge(forge)
+        end
+      end
+
+      #
+      # Runs the defined RSpec examples
+      # Executes the tests after they've been defined
       #
       def run
-        # Allows me to modify the error backtrace reporting within rspec
-        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+        prepare_for_run
 
-        RSpec::Core::Runner.disable_autorun!
-        RSpec::Core::Runner.run([], $stderr, $stdout)
+        ARGV.clear
+        RSpec::Core::Runner.invoke
       end
 
       #
-      # Defines a spec with RSpec
+      # Defines RSpec examples for a specific forge
+      # Creates the test structure for a single forge file
       #
-      # @param spec_forge [Spec] The spec to define
+      # @param forge [Forge] The forge 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 }
-              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 }
-
-              it do
-                if spec_forge.debug? || expectation.debug?
-                  runner_forge.handle_debug(expectation, self)
-                end
-
-                # Status check
-                expect(response.status).to eq(expected_status)
-
-                # JSON check
-                if expected_json
-                  expect(response.body).to be_kind_of(expected_json_class)
-                  expect(response.body).to expected_json
+      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
@@ -64,87 +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}"}
+      private
 
-        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)
-      end
-
-      def inspect
-        hash = expectation.to_h
-
-        hash[:response] = {
-          headers: response.headers,
-          status: response.status,
-          body: response.body
-        }
+      def prepare_for_run
+        # Allows modifying the error backtrace reporting within rspec
+        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
 
-        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"

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

@@ -4,42 +4,113 @@ module SpecForge
   class Spec
     class Expectation
       #
-      # Represents the "expect" hash
+      # 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,
+      #     json: {name: "matcher.eq" => "John"}
+      #   )
       #
       class Constraint < Data.define(:status, :json) # :xml, :html
         #
-        # Creates a new Constraint
+        # Creates a new constraint
         #
-        # @param status [Integer] The expected HTTP status code
+        # @param status [Integer, String] The expected HTTP status code, or reference to one
         # @param json [Hash, Array] The expected JSON with matchers
         #
-        def initialize(status:, json:)
-          super(status:, json: convert_to_matchers(json))
+        # @return [Constraint] A new constraint instance
+        #
+        def initialize(status:, json: {})
+          super(
+            status: Attribute.from(status),
+            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
 
-        private
+        #
+        # 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
+          }
+        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
 
-        def convert_to_matchers(value)
-          # This makes it easier to check if json was provided
-          return Attribute.from(nil) if value.blank?
+          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
 
-          case value
+        def resolve_json_matcher
+          case json
           when HashLike
-            value = value.transform_values { |i| convert_to_matchers(i) }
-            Attribute.from("matcher.include" => value)
-          when ArrayLike
-            value = value.map { |i| convert_to_matchers(i) }
-            Attribute.from("matcher.contain_exactly" => value)
-          when Attribute::Regex
-            Attribute.from("matcher.match" => value)
-          when Attribute::Literal
-            Attribute.from("matcher.eq" => value)
+            json.transform_values(&:resolve_as_matcher).stringify_keys
           else
-            value
+            json.resolve_as_matcher
           end
         end
       end

data/lib/spec_forge/spec/expectation.rb

@@ -1,72 +1,64 @@
 # frozen_string_literal: true
 
-require_relative "expectation/constraint"
-
 module SpecForge
   class Spec
-    class Expectation
+    #
+    # 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, :constraints)
+      #
+      # @return [Boolean] True if debugging is enabled
+      #
       attr_predicate :debug
 
-      attr_reader :name, :variables, :constraints, :http_client
+      #
+      # @return [Boolean] True if store_as is set
+      #
+      attr_predicate :store_as
 
       #
-      # Creates a new Expectation
+      # Creates a new expectation with constraints
       #
-      # @param input [Hash] A hash containing the various attributes to control the expectation
-      # @param name [String] The name of the expectation
+      # @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 expect [Hash] Expected constraints
       #
-      def initialize(input, global_options: {})
-        # This allows defining spec level attributes that can be overwritten by the expectation
-        input = Attribute.from(Configuration.overlay_options(global_options, input))
-
-        load_debug(input)
-        load_variables(input)
-
-        # Must be after load_variables
-        load_constraints(input)
-
-        @http_client = HTTP::Client.new(
-          variables:, **input.except(:name, :variables, :expect, :debug)
-        )
+      # @return [Expectation] A new expectation instance
+      #
+      def initialize(id:, name:, line_number:, debug:, store_as:, expect:)
+        constraints = Constraint.new(**expect)
 
-        # Must be after http_client
-        load_name(input)
+        super(id:, name:, line_number:, debug:, store_as:, constraints:)
       end
 
+      #
+      # Converts the expectation to a hash representation
+      #
+      # @return [Hash] Hash representation
+      #
       def to_h
         {
           name:,
-          debug: debug?,
-          variables: variables.resolve,
-          request: http_client.request.to_h,
-          constraints: constraints.to_h
+          line_number:,
+          debug:,
+          expect: constraints.to_h
         }
       end
-
-      private
-
-      def load_name(input)
-        # GET /users
-        @name = "#{http_client.request.http_verb.upcase} #{http_client.request.url}"
-
-        # GET /users - Returns a 404
-        if (name = input[:name].resolve.presence)
-          @name += " - #{name}"
-        end
-      end
-
-      def load_variables(input)
-        @variables = Attribute.bind_variables(input[:variables], input[:variables])
-      end
-
-      def load_debug(input)
-        @debug = input[:debug].resolve
-      end
-
-      def load_constraints(input)
-        constraints = Attribute.bind_variables(input[:expect], variables)
-        @constraints = Constraint.new(**constraints)
-      end
     end
   end
 end
+
+require_relative "expectation/constraint"