spec_forge 0.7.0 → 1.0.0

data/lib/spec_forge/forge/runner/content_validator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    class Runner
+      #
+      # Validates JSON content against expected matchers
+      #
+      # Recursively walks through the response body and expected values,
+      # running RSpec matchers at each leaf node and collecting failures.
+      #
+      class ContentValidator
+        #
+        # Creates a new content validator
+        #
+        # @param data [Hash, Array] The response data to validate
+        # @param expected [Hash, Array] The expected content matchers
+        #
+        # @return [ContentValidator] A new validator instance
+        #
+        def initialize(data, expected)
+          @data = data
+          @expected = expected
+          @failures = []
+        end
+
+        #
+        # Validates the data against expected content matchers
+        #
+        # @return [void]
+        #
+        # @raise [Error::ContentValidationFailure] If validation fails
+        #
+        def validate!
+          check_content(@data, @expected, path: "")
+
+          raise Error::ContentValidationFailure.new(@failures) if @failures.any?
+        end
+
+        private
+
+        def failure!(path, message)
+          @failures << {path:, message:}
+        end
+
+        def check_content(data, expected, path:)
+          case expected
+          when Hash
+            check_hash(data, expected, path:)
+          when Array
+            check_array(data, expected, path:)
+          else
+            run_matcher(data, expected, path:)
+          end
+        end
+
+        def check_hash(data, expected, path:)
+          expected.each do |key, expected_value|
+            new_path = path.empty? ? ".#{key}" : "#{path}.#{key}"
+
+            actual_key = [key.to_sym, key.to_s].detect { |k| data.respond_to?(:key?) && data.key?(k) }
+            actual_value = data[actual_key]
+
+            if actual_value.nil? && actual_key.nil?
+              failure!(new_path, "key not found")
+              next
+            end
+
+            check_content(actual_value, expected_value, path: new_path)
+          end
+        end
+
+        def check_array(data, expected, path:)
+          if !data.is_a?(Array)
+            failure!(path, "expected array, got #{data.class}")
+            return
+          end
+
+          expected.each_with_index do |expected_item, index|
+            check_content(data[index], expected_item, path: "#{path}[#{index}]")
+          end
+        end
+
+        def run_matcher(data, matcher, path:)
+          return if matcher.matches?(data)
+
+          failure!(path, matcher.failure_message.lstrip)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/runner/header_validator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    class Runner
+      #
+      # Validates HTTP response headers against expected matchers
+      #
+      # Performs case-insensitive header name matching and runs
+      # RSpec matchers against header values.
+      #
+      class HeaderValidator
+        #
+        # Creates a new header validator
+        #
+        # @param headers [Hash] The response headers to validate
+        # @param expected [Hash] The expected header matchers
+        #
+        # @return [HeaderValidator] A new validator instance
+        #
+        def initialize(headers, expected)
+          @headers = headers
+          @expected = expected
+          @failures = []
+        end
+
+        #
+        # Validates the headers against expected matchers
+        #
+        # @return [void]
+        #
+        # @raise [Error::HeaderValidationFailure] If validation fails
+        #
+        def validate!
+          @expected.each do |key, matcher|
+            actual_key = find_header_key(key)
+
+            if actual_key.nil?
+              failure!(key, "header not found")
+              next
+            end
+
+            actual_value = @headers[actual_key]
+            next if matcher.matches?(actual_value)
+
+            failure!(key, matcher.failure_message.lstrip)
+          end
+
+          raise Error::HeaderValidationFailure.new(@failures) if @failures.any?
+        end
+
+        private
+
+        def find_header_key(key)
+          return key if @headers.key?(key)
+
+          @headers.keys.find { |k| k.to_s.downcase == key.to_s.downcase }
+        end
+
+        def failure!(header, message)
+          @failures << {header:, message:}
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/runner/reporter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    class Runner
+      #
+      # RSpec formatter listener for tracking test results
+      #
+      # Receives notifications from RSpec when examples pass or fail,
+      # updating the forge's statistics and display accordingly.
+      #
+      class Reporter
+        #
+        # Creates a new reporter for the given forge instance
+        #
+        # @param forge [Forge, nil] The forge instance to report to
+        #
+        # @return [Reporter] A new reporter instance
+        #
+        def initialize(forge = nil)
+          @forge = forge
+          @stats = forge&.stats
+          @display = forge&.display
+        end
+
+        #
+        # Called when an RSpec example fails
+        #
+        # @param notification [RSpec::Core::Notifications::ExampleNotification] The failure notification
+        #
+        # @return [void]
+        #
+        def example_failed(notification)
+          return if @stats.nil? || @display.nil?
+
+          @stats[:failed] += 1
+          @display.expectation_failed(notification.example.description, indent: 1)
+        end
+
+        #
+        # Called when an RSpec example passes
+        #
+        # @param notification [RSpec::Core::Notifications::ExampleNotification] The success notification
+        #
+        # @return [void]
+        #
+        def example_passed(notification)
+          return if @stats.nil? || @display.nil?
+
+          @stats[:passed] += 1
+          @display.expectation_passed(notification.example.description, indent: 1)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/runner/schema_validator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    class Runner
+      #
+      # Validates JSON structure against a schema definition
+      #
+      # Validates that response data matches the expected types and structure
+      # defined in shape: or schema: blocks. Supports nested objects, arrays
+      # with patterns, and nullable types.
+      #
+      class SchemaValidator
+        #
+        # Creates a new schema validator
+        #
+        # @param data [Hash, Array] The response data to validate
+        # @param schema [Hash] The schema definition to validate against
+        #
+        # @return [SchemaValidator] A new validator instance
+        #
+        def initialize(data, schema)
+          @data = data
+          @schema = schema
+          @failures = []
+        end
+
+        #
+        # Validates the data against the schema definition
+        #
+        # @return [void]
+        #
+        # @raise [Error::SchemaValidationFailure] If validation fails
+        #
+        def validate!
+          check_schema(@data, @schema, path: "")
+
+          raise Error::SchemaValidationFailure.new(@failures) if @failures.size > 0
+        end
+
+        private
+
+        def failure!(path, expected_type, actual_value)
+          @failures << {
+            path: path.empty? ? "root" : path,
+            expected_type:,
+            actual_value:,
+            actual_type: actual_value.class
+          }
+        end
+
+        def check_schema(data, schema, path:)
+          check_type(data, schema[:type], path:)
+          check_structure(data, schema[:structure], path:) if schema[:structure]
+          check_pattern(data, schema[:pattern], path:) if schema[:pattern]
+        end
+
+        def check_type(data, expected_types, path:)
+          return if expected_types.any? { |type| data.is_a?(type) }
+
+          failure!(path, expected_types, data)
+        end
+
+        def check_structure(data, schema, path:)
+          case schema
+          when Hash
+            check_hash_structure(data, schema, path:)
+          when Array
+            check_array_structure(data, schema, path:)
+          end
+        end
+
+        def check_pattern(data, schema, path:)
+          # Only arrays allowed
+          check_type(data, [Array], path:)
+
+          data.each_with_index do |value, index|
+            check_schema(value, schema, path: "#{path}[#{index}]")
+          end
+        end
+
+        def check_hash_structure(data, structure, path:)
+          structure.each do |key, expected|
+            check_hash_key(
+              data, key, expected,
+              path: path.empty? ? ".#{key}" : "#{path}.#{key}"
+            )
+          end
+        end
+
+        def check_hash_key(data, key, expected, path:)
+          actual_key = [key.to_sym, key.to_s].detect { |k| data.respond_to?(:key?) && data.key?(k) }
+
+          if actual_key
+            check_schema(data[actual_key], expected, path:)
+            return
+          end
+
+          # Key is missing - only fail if not optional
+          return if expected[:optional]
+
+          failure!(path, expected[:type], nil)
+        end
+
+        def check_array_structure(data, structure, path:)
+          structure.each_with_index do |expected, index|
+            check_schema(data[index], expected, path: "#{path}[#{index}]")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/runner.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Executes expectations using RSpec as the underlying test framework
+    #
+    # Runner wraps RSpec to run individual expectation blocks, capturing
+    # results and formatting them for display. It creates isolated RSpec
+    # example groups for each expectation.
+    #
+    class Runner
+      # @return [ArrayIO] Output stream for RSpec formatter
+      attr_reader :output_io
+
+      # @return [StringIO] Error stream for RSpec formatter
+      attr_reader :error_io
+
+      #
+      # Creates a new RSpec runner with the specified CLI arguments
+      #
+      # @param cli_args [Array<String>] Command line arguments for RSpec configuration
+      #
+      # @return [Runner] A new runner instance
+      #
+      def initialize(cli_args = [])
+        options = RSpec::Core::ConfigurationOptions.new(cli_args)
+
+        @configuration = RSpec.configuration.deep_dup
+        @configuration.reset
+
+        @world = RSpec::Core::World.new
+        @runner = RSpec::Core::Runner.new(options, @configuration, @world)
+
+        @output_io = ArrayIO.new
+        @error_io = StringIO.new
+        @runner.configure(@error_io, @output_io)
+      end
+
+      #
+      # Runs an expectation and returns any failed examples
+      #
+      # @param forge [Forge] The forge instance
+      # @param step [Step] The current step
+      # @param expectation [Step::Expect] The expectation to run
+      #
+      # @return [Array<Hash>] List of failed examples (empty if all passed)
+      #
+      def run(forge, step, expectation)
+        configure_formatters(forge)
+
+        @runner.run_specs([create_example_group(forge, step, expectation)])
+
+        entry = @output_io.entries.last.to_h
+        entry[:examples].reject { |ex| ex[:status] == "passed" }
+      end
+
+      private
+
+      def configure_formatters(forge)
+        # Resetting the configuration also means resetting the Formatters/Reporters.
+        @configuration.reset
+        @configuration.add_formatter(RSpec::Core::Formatters::JsonFormatter)
+
+        # Make sure to load a formatter first and register to its reporter.
+        # Otherwise RSpec will default the reporter.
+        @configuration.formatter_loader.reporter.register_listener(
+          Reporter.new(forge), :example_passed, :example_failed
+        )
+      end
+
+      def create_example_group(forge, step, expectation)
+        RSpec::Core::ExampleGroup.describe(step.source.to_s, :spec_forge) do
+          let(:response) { forge.variables[:response] }
+
+          let(:headers) { response[:headers] }
+          let(:body) { response[:body].is_a?(Hash) ? response[:body].deep_symbolize_keys : response[:body] }
+
+          ############################################################
+          # Status check
+          if (status_matcher = expectation.status_matcher)
+            it "Status" do
+              expect(response[:status]).to status_matcher
+            end
+          end
+
+          ############################################################
+          # Headers check
+          if (headers_matcher = expectation.headers_matcher)
+            it "Headers" do
+              HeaderValidator.new(headers, headers_matcher).validate!
+            end
+          end
+
+          ############################################################
+          # JSON checks
+          if (json_size_matcher = expectation.json_size_matcher)
+            it "JSON size" do
+              expect(body.size).to json_size_matcher
+            end
+          end
+
+          if (schema_structure = expectation.json_schema)
+            it "JSON schema" do
+              SchemaValidator.new(body, schema_structure).validate!
+            end
+          end
+
+          if (content_matcher = expectation.json_content_matcher)
+            it "JSON content" do
+              ContentValidator.new(body, content_matcher).validate!
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/timer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Simple timer for tracking execution duration
+    #
+    # Used to measure how long a forge run takes from start to finish.
+    #
+    class Timer
+      # @return [Time, nil] Time when the timer started
+      attr_reader :started_at
+
+      # @return [Time, nil] Time when the timer stopped
+      attr_reader :stopped_at
+
+      #
+      # Creates a new timer in the reset state
+      #
+      # @return [Timer] A new timer instance
+      #
+      def initialize
+        reset
+      end
+
+      #
+      # Resets the timer to its initial state
+      #
+      # @return [Timer] self for chaining
+      #
+      def reset
+        @started_at = nil
+        @stopped_at = nil
+
+        self
+      end
+
+      #
+      # Starts the timer
+      #
+      # @return [Timer] self for chaining
+      #
+      def start
+        reset
+
+        @started_at ||= Time.current
+
+        self
+      end
+
+      #
+      # Stops the timer
+      #
+      # @return [Timer] self for chaining
+      #
+      def stop
+        return self if @started_at.nil?
+
+        @stopped_at ||= Time.current
+
+        self
+      end
+
+      #
+      # Returns whether the timer has been started
+      #
+      # @return [Boolean] True if the timer has been started
+      #
+      def started?
+        !started_at.nil?
+      end
+
+      #
+      # Returns whether the timer has been stopped
+      #
+      # @return [Boolean] True if the timer has been stopped
+      #
+      def stopped?
+        !stopped_at.nil?
+      end
+
+      #
+      # Returns the elapsed time in seconds
+      #
+      # @return [Float] Seconds elapsed since start (or 0 if not started)
+      #
+      def time_elapsed
+        return 0 if started_at.nil?
+
+        (stopped_at || Time.current) - started_at
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/variables.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Hash-based storage for runtime variables
+    #
+    # Manages both static (global) variables that persist across blueprints
+    # and dynamic variables that are cleared between blueprints. Static
+    # variables are restored when clear is called.
+    #
+    class Variables < Hash
+      #
+      # Creates a new Variables hash with static and dynamic values
+      #
+      # @param static [Hash] Variables that persist across blueprint clears
+      # @param dynamic [Hash] Variables that are cleared between blueprints
+      #
+      # @return [Variables] A new variables instance
+      #
+      def initialize(static: {}, dynamic: {})
+        @static = static.deep_dup
+
+        merge!(@static, dynamic.deep_dup)
+      end
+
+      #
+      # Clears dynamic variables while preserving static ones
+      #
+      # @return [Variables] self
+      #
+      def clear
+        super
+        merge!(@static)
+      end
+    end
+  end
+end