spec_forge 0.6.0 → 0.7.1

data/lib/spec_forge/normalizers/_shared.yml

@@ -0,0 +1,76 @@
+id: string
+
+name: string
+
+line_number: integer
+
+base_url:
+  type: string
+  default: null
+  required: false
+  aliases:
+  - base_path
+
+url:
+  type: string
+  default: null
+  required: false
+  aliases:
+  - path
+
+http_verb:
+  type: string
+  default: null # Do not default this to "GET". Leave it null. Seriously.
+  required: false
+  aliases:
+  - method
+  - http_method
+  validator: http_verb
+
+headers:
+  type: hash
+  default: {}
+  required: false
+
+query:
+  type:
+  - hash
+  - string
+  aliases:
+  - params
+  default: {}
+  required: false
+
+body:
+  type:
+  - hash
+  - string
+  aliases:
+  - data
+  default: {}
+  required: false
+
+variables:
+  type:
+  - hash
+  - string
+  default: {}
+  required: false
+
+debug:
+  type: boolean
+  aliases:
+  - pry
+  - breakpoint
+  default: false
+  required: false
+
+callback:
+  type: string
+  required: false
+  validator: callback
+
+documentation:
+  type: boolean
+  required: false
+  default: true

data/lib/spec_forge/normalizers/configuration.yml

@@ -0,0 +1,23 @@
+base_url: string
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+factories:
+  type: hash
+  default: {}
+  structure:
+    ###########################################
+    auto_discover:
+      type: boolean
+      default: true
+
+    paths:
+      type: array
+      default: []
+
+on_debug_proc:
+  type: proc

data/lib/spec_forge/normalizers/constraint.yml

@@ -0,0 +1,8 @@
+status:
+- integer
+- string
+json:
+  type:
+  - hash
+  - array
+  default: {}

data/lib/spec_forge/normalizers/expectation.yml

@@ -0,0 +1,47 @@
+# Internal
+id:
+  reference: id
+
+line_number:
+  reference: line_number
+
+# User defined
+name:
+  reference: name
+
+base_url:
+  reference: base_url
+
+url:
+  reference: url
+
+http_verb:
+  reference: http_verb
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+body:
+  reference: body
+
+variables:
+  reference: variables
+
+debug:
+  reference: debug
+
+store_as:
+  type: string
+  default: ""
+
+documentation:
+  reference: documentation
+
+expect:
+  type: hash
+  structure:
+    ###########################################
+    reference: constraint

data/lib/spec_forge/normalizers/factory.yml

@@ -0,0 +1,12 @@
+model_class:
+  type: string
+  default: ""
+  aliases:
+  - class
+
+variables:
+  reference: variables
+
+attributes:
+  type: hash
+  default: {}

data/lib/spec_forge/normalizers/factory_reference.yml

@@ -0,0 +1,15 @@
+attributes:
+  type: hash
+  default: {}
+
+build_strategy:
+  type: string
+  default: create
+  aliases:
+  - strategy
+
+size:
+  type: integer
+  default: 0
+  aliases:
+  - count

data/lib/spec_forge/normalizers/global_context.yml

@@ -0,0 +1,28 @@
+variables:
+  reference: variables
+
+callbacks:
+  type: array
+  default: []
+  structure:
+    ###########################################
+    type: hash
+    default: {}
+    structure:
+      ###########################################
+      before_file:
+        reference: callback
+      before_spec:
+        reference: callback
+      before_each:
+        reference: callback
+        aliases:
+        - before
+      after_each:
+        reference: callback
+        aliases:
+        - after
+      after_spec:
+        reference: callback
+      after_file:
+        reference: callback

data/lib/spec_forge/normalizers/spec.yml

@@ -0,0 +1,50 @@
+# Internal
+id:
+  reference: id
+
+name:
+  reference: name
+
+file_name: string
+
+file_path: string
+
+line_number:
+  reference: line_number
+
+# User defined
+base_url:
+  reference: base_url
+
+url:
+  reference: url
+
+http_verb:
+  reference: http_verb
+
+headers:
+  reference: headers
+
+query:
+  reference: query
+
+body:
+  reference: body
+
+variables:
+  reference: variables
+
+debug:
+  reference: debug
+
+documentation:
+  reference: documentation
+
+expectations:
+  type: array
+  structure:
+    ###########################################
+    type: hash
+    structure:
+      ###########################################
+      reference: expectation

data/lib/spec_forge/runner/adapter.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Bridges SpecForge specs with RSpec execution
+    #
+    # Converts SpecForge forge objects into RSpec test structures
+    # and manages the test execution lifecycle.
+    #
+    class Adapter
+      include Singleton
+
+      #
+      # Configures RSpec with forge definitions
+      #
+      # Sets up RSpec and prepares everything for running tests
+      #
+      # @param forges [Array<Forge>] The forges to set up for testing
+      #
+      def self.setup(forges)
+        # Defines the forges with RSpec
+        forges.each { |forge| instance.describe(forge) }
+
+        # Disable autorun because RSpec does it
+        RSpec::Core::Runner.disable_autorun!
+
+        # Allows modifying the error backtrace reporting within rspec
+        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+
+        # Listen for passed/failed events to trigger the "after_each" callback
+        RSpec.configuration.reporter.register_listener(
+          Listener.instance,
+          :example_passed, :example_failed
+        )
+      end
+
+      #
+      # Executes the configured RSpec tests
+      #
+      # Runs all configured tests through RSpec with optional exit behavior.
+      #
+      # @param exit_on_finish [Boolean] Whether to exit the process when done
+      # @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 self.run(exit_on_finish: false, exit_on_failure: false)
+        status = RSpec::Core::Runner.run([]).to_i
+
+        exit(status) if exit_on_finish || (exit_on_failure && status != 0)
+
+        status
+      end
+
+      ##########################################################################
+
+      #
+      # Defines RSpec examples for a specific forge
+      # Creates the test structure for a single forge file
+      #
+      # @param forge [Forge] The forge to define
+      #
+      def describe(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) }
+                  let(:match_headers) { constraints[:headers] }
+
+                  # 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
+                    # Debugging
+                    if spec.debug? || expectation.debug?
+                      Callbacks.on_debug(forge, spec, expectation, self)
+                    end
+
+                    ############################################################
+                    # Status check
+                    expect(response.status).to match_status
+
+                    ############################################################
+                    # Headers check
+                    if match_headers.present?
+                      match_headers.each do |key, matcher|
+                        expect(response.headers).to include(key.downcase => matcher)
+                      end
+                    end
+
+                    ############################################################
+                    # JSON check
+                    if match_json.present?
+                      case match_json
+                      when Hash
+                        match_json.each do |key, matcher|
+                          expect(response.body).to include(key)
+
+                          begin
+                            expect(response.body[key]).to matcher
+                          rescue RSpec::Expectations::ExpectationNotMetError => e
+                            # Add the key that failed to the front of the error message
+                            e.message.insert(0, "Key: #{key.in_quotes}\n")
+                            raise e
+                          end
+                        end
+                      else
+                        expect(response.body).to match_json
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/runner/debug_proxy.rb

@@ -30,7 +30,46 @@ module SpecForge
       # @return [Proc] The default debugging handler that outputs JSON state information
       #
       def self.default
-        -> { puts inspect }
+        lambda do
+          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
+
+          puts inspect
+        end
       end
 
       # @return [RSpec::Forge] The current Forge that is being tested
@@ -67,7 +106,7 @@ module SpecForge
       # @return [SpecForge::Runner::DebugProxy]
       #
       def initialize(forge, spec, expectation, example_group)
-        @callback = SpecForge.configuration.on_debug
+        @callback = SpecForge.configuration.on_debug_proc
 
         @forge = forge
         @spec = spec
@@ -90,43 +129,6 @@ module SpecForge
       # @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
 
@@ -179,14 +181,14 @@ module SpecForge
         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
           },
-          global:,
-          variables:,
-          request: request.to_h,
           expectation: expectation_hash,
           spec: spec_hash
         }

data/lib/spec_forge/runner/state.rb

@@ -87,11 +87,10 @@ module SpecForge
           scope:,
           request: request&.to_h,
           variables: SpecForge.context.variables.deep_dup,
-          response: {
-            headers: response&.headers,
-            status: response&.status,
-            body: response&.body
-          }
+          response:,
+          headers: response&.headers,
+          status: response&.status,
+          body: response&.body
         )
       end
     end