spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/configuration.rb

@@ -1,46 +1,62 @@
 # frozen_string_literal: true
 
 module SpecForge
-  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :specs, :on_debug)
-    ############################################################################
-
+  #
+  # Configuration container for SpecForge settings
+  # Defines default values and validation for all configuration options
+  #
+  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :on_debug)
+    #
+    # Manages factory configuration settings
+    # Controls auto-discovery behavior and custom factory paths
+    #
+    # @example
+    #   config.factories.auto_discover = false
+    #   config.factories.paths += ["lib/factories"]
+    #
     class Factories < Struct.new(:auto_discover, :paths)
+      #
+      # Creates reader methods that return boolean values
+      # Allows for checking configuration with predicate methods
+      #
       attr_predicate :auto_discover, :paths
 
+      #
+      # Initializes a new Factories configuration
+      # Sets default values for auto-discovery and paths
+      #
+      # @param auto_discover [Boolean] Whether to auto-discover factories (default: true)
+      # @param paths [Array<String>] Additional paths to look for factories (default: [])
+      #
+      # @return [Factories] A new factories configuration instance
+      #
       def initialize(auto_discover: true, paths: []) = super
     end
 
-    ############################################################################
-
-    def self.overlay_options(source, overlay)
-      source.deep_merge(overlay) do |key, source_value, overlay_value|
-        # If overlay has a populated value, use it
-        if overlay_value.present? || overlay_value == false
-          overlay_value
-        # If source is nil and overlay exists (but wasn't "present"), use overlay
-        elsif source_value.nil? && !overlay_value.nil?
-          overlay_value
-        # Otherwise keep source value
-        else
-          source_value
-        end
-      end
-    end
-
+    #
+    # Initializes a new Configuration with default values
+    # Sets up the configuration structure including factory settings and debug proxy
+    #
+    # @return [Configuration] A new configuration instance with defaults
+    #
     def initialize
       config = Normalizer.default_configuration
 
-      # Allows me to modify the error backtrace reporting within rspec
-      RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
-
       config[:base_url] = "http://localhost:3000"
       config[:factories] = Factories.new
-      config[:specs] = RSpec.configuration
       config[:on_debug] = Runner::DebugProxy.default
 
       super(**config)
     end
 
+    #
+    # Validates the configuration and applies normalization
+    # Ensures all required fields have values and applies defaults when needed
+    #
+    # @return [self] Returns self for method chaining
+    #
+    # @api private
+    #
     def validate
       output = Normalizer.normalize_configuration!(to_h)
 
@@ -52,10 +68,63 @@ module SpecForge
       self
     end
 
+    #
+    # Recursively converts the configuration to a hash representation
+    #
+    # @return [Hash] Hash representation of the configuration
+    #
     def to_h
-      hash = super.except(:specs)
+      hash = super
       hash[:factories] = hash[:factories].to_h
       hash
     end
+
+    #
+    # Returns the RSpec configuration object
+    # Provides access to RSpec's internal configuration for test customization
+    #
+    # @return [RSpec::Core::Configuration] RSpec's configuration object
+    #
+    # @example Setting formatter options
+    #   SpecForge.configure do |config|
+    #     config.specs.formatter = :documentation
+    #   end
+    #
+    def specs
+      RSpec.configuration
+    end
+
+    alias_method :rspec, :specs
+
+    #
+    # Registers a callback for a specific test lifecycle event
+    # Allows custom code execution at specific points during test execution
+    #
+    # @param name [Symbol, String] The callback point to register for
+    #   (:before_file, :after_expectation, etc.)
+    # @yield A block to execute when the callback is triggered
+    # @yieldparam context [Object] An object containing context-specific state data, depending
+    #   on which hook the callback is triggered from.
+    #
+    # @return [Proc] The registered callback
+    #
+    # @example Registering a custom debug handler
+    #   SpecForge.configure do |config|
+    #     config.register_callback(:on_debug) { binding.pry }
+    #   end
+    #
+    # @example Cleaning database after each test
+    #   SpecForge.configure do |config|
+    #     config.register_callback(:after_expectation) do
+    #       DatabaseCleaner.clean
+    #     end
+    #   end
+    #
+    def register_callback(name, &)
+      Callbacks.register(name, &)
+    end
+
+    alias_method :define_callback, :register_callback
+    alias_method :callback, :register_callback
   end
 end

data/lib/spec_forge/context/callbacks.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages user-defined callbacks grouped by lifecycle hook
+    #
+    # This class collects and organizes callbacks by their hook type
+    # (before_file, after_each, etc.) to support the test lifecycle.
+    # It ensures callbacks are properly categorized for execution.
+    #
+    # @example Creating callback groups
+    #   callbacks = Context::Callbacks.new([
+    #     {before_file: "setup_environment"},
+    #     {after_each: "log_test_result"}
+    #   ])
+    #
+    class Callbacks
+      #
+      # Creates a new callbacks collection
+      #
+      # @param callback_array [Array] Optional initial callbacks to register
+      #
+      # @return [Callbacks] A new callbacks collection
+      #
+      def initialize(callback_array = [])
+        set(callback_array)
+      end
+
+      #
+      # Updates the callbacks collection
+      #
+      # @param callback_array [Array] New callbacks to register
+      #
+      # @return [self]
+      #
+      def set(callback_array)
+        @inner = organize_callbacks_by_hook(callback_array)
+        self
+      end
+
+      #
+      # Returns the hash representation of callbacks
+      #
+      # @return [Hash] Callbacks organized by hook type
+      #
+      def to_h
+        @inner
+      end
+
+      #
+      # Executes all registered callbacks for a specific lifecycle hook
+      #
+      # @param hook_name [String, Symbol] The lifecycle hook (before_file, after_each, etc.)
+      # @param context [Hash] State data that will be converted to a structured object
+      #   and passed to callbacks
+      #
+      def run(hook_name, context = {})
+        context = context.to_struct
+
+        @inner[hook_name].each do |callback_name|
+          SpecForge::Callbacks.run(callback_name, context)
+        end
+      end
+
+      private
+
+      #
+      # Organizes callbacks from an array to hash structure by hook type
+      # Groups callbacks like before_file, after_each, etc. for easier lookup
+      #
+      # @param callback_array [Array] The array of callbacks
+      #
+      # @return [Hash] Callbacks indexed by hook type
+      #
+      # @private
+      #
+      def organize_callbacks_by_hook(callback_array)
+        groups = Hash.new { |h, k| h[k] = Set.new }
+
+        callback_array.each_with_object(groups) do |callbacks, groups|
+          callbacks.each do |hook, name|
+            next if name.blank?
+
+            groups[hook].add(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context/global.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages global state and variables at the spec file level.
+    #
+    # The Global class provides access to variables that are defined at the global level
+    # in a spec file and are accessible across all specs and expectations in a file.
+    # Unlike regular variables, global variables do not support overlaying - they maintain
+    # consistent values throughout test execution.
+    #
+    # @example Basic usage
+    #   global = Global.new(variables: {api_version: "v2", environment: "test"})
+    #
+    #   global.variables[:api_version] #=> "v2"
+    #   global.variables[:environment] #=> "test"
+    #
+    #   # Update global variables
+    #   global.set(variables: {environment: "staging"})
+    #   global.variables[:environment] #=> "staging"
+    #   global.variables[:api_version] #=> nil
+    #
+    class Global
+      # @return [Context::Variables] The container for global variables
+      attr_reader :variables
+
+      # @return [Context::Callbacks] The container for callbacks
+      attr_reader :callbacks
+
+      #
+      # Creates a new Global context instance
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [Global] The new Global instance
+      #
+      def initialize(variables: {}, callbacks: [])
+        @variables = Variables.new(base: variables)
+        @callbacks = Callbacks.new(callbacks)
+      end
+
+      #
+      # Sets the global variables
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [self]
+      #
+      def set(variables: {}, callbacks: [])
+        @variables.set(base: variables)
+        @callbacks.set(callbacks)
+
+        self
+      end
+
+      #
+      # Returns a hash representation of the global context
+      #
+      # @return [Hash]
+      #
+      def to_h
+        {
+          variables: variables.to_h,
+          callbacks: callbacks.to_h
+        }
+      end
+    end
+  end
+end

data/lib/spec_forge/context/store.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages storage of API responses for use in subsequent tests
+    #
+    # This class provides a mechanism to store HTTP requests and responses
+    # during test execution, allowing values to be referenced in later tests
+    # through the `store.id.body.attribute` syntax.
+    #
+    # @example Storing and retrieving a response in specs
+    #   # In one expectation:
+    #   store_as: user_creation
+    #
+    #   # In a later test:
+    #   query:
+    #     id: store.user_creation.body.id
+    #
+    class Store
+      #
+      # Represents a single stored entry with request, variables, and response data
+      #
+      # Entries are immutable once created and contain a deep-frozen
+      # snapshot of the test state at the time of storage.
+      #
+      # @example Accessing stored entry data
+      #   entry = store["user_creation"]
+      #   entry.status    # => 201
+      #   entry.body.id   # => 42
+      #
+      class Entry < Data.define(:scope, :request, :variables, :response)
+        #
+        # Creates a new immutable store entry
+        #
+        # @param request [Hash] The HTTP request that was executed
+        # @param variables [Hash] Variables from the test context
+        # @param response [Hash] The HTTP response received
+        # @param scope [Symbol] Scope of this entry, either :file or :spec
+        #
+        # @return [Entry] A new immutable entry instance
+        #
+        def initialize(request:, variables:, response:, scope: :file)
+          request = request.deep_freeze
+          variables = variables.deep_freeze
+          response = response.deep_freeze
+
+          super
+        end
+
+        #
+        # Shorthand accessor for the HTTP status code
+        #
+        # @return [Integer] The response status code
+        #
+        def status = response[:status]
+
+        #
+        # Shorthand accessor for the response body
+        #
+        # @return [Hash, Array, String] The parsed response body
+        #
+        def body = response[:body]
+
+        #
+        # Shorthand accessor for the response headers
+        #
+        # @return [Hash] The response headers
+        #
+        def headers = response[:headers]
+
+        #
+        # Returns all available methods that can be called
+        #
+        # @return [Array] The method names
+        #
+        def available_methods
+          members + [:status, :body, :headers]
+        end
+      end
+
+      #
+      # Creates a new empty store
+      #
+      # @return [Store] A new store instance
+      #
+      def initialize
+        @inner = {}
+      end
+
+      #
+      # Retrieves a stored entry by ID
+      #
+      # @param id [String, Symbol] The identifier for the stored entry
+      #
+      # @return [Entry, nil] The stored entry or nil if not found
+      #
+      def [](id)
+        @inner[id]
+      end
+
+      #
+      # Returns the number of entries in the store
+      #
+      # @return [Integer] The count of stored entries
+      #
+      def size
+        @inner.size
+      end
+
+      #
+      # Stores an entry with the specified ID
+      #
+      # @param id [String, Symbol] The identifier to store the entry under
+      #
+      # @return [self]
+      #
+      def set(id, **)
+        @inner[id] = Entry.new(**)
+
+        self
+      end
+
+      #
+      # Removes all entries from the store
+      #
+      def clear
+        @inner.clear
+      end
+
+      #
+      # Removes all spec entries from the store
+      #
+      def clear_specs
+        @inner.delete_if { |_k, v| v.scope == :spec }
+      end
+
+      #
+      # Returns a hash representation of store
+      #
+      # @return [Hash]
+      #
+      def to_h
+        @inner.transform_values(&:to_h).deep_stringify_keys
+      end
+    end
+  end
+end

data/lib/spec_forge/context/variables.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages variable resolution across different expectations in SpecForge tests.
+    #
+    # The Variables class handles two layers of variable definitions:
+    #   - Base variables: The core set of variables defined at the spec level
+    #   - Overlay variables: Additional variables defined at the expectation level
+    #       that can override base variables with the same name.
+    #
+    # @example Basic usage
+    #   variables = Variables.new(
+    #     base: {user_id: 123, name: "Test User"},
+    #     overlay: {
+    #       "expectation_1": {name: "Override User"}
+    #     }
+    #   )
+    #
+    #   variables[:user_id] #=> 123
+    #   variables[:name]    #=> "Test User"
+    #
+    #   variables.use_overlay("expectation_1")
+    #   variables[:name]    #=> "Override User"
+    #   variables[:user_id] #=> 123 (unchanged)
+    #
+    class Variables < Hash
+      attr_reader :base, :overlay
+
+      #
+      # Creates a new Variables container with base and overlay definitions
+      #
+      # @param base [Hash] The base set of variables (typically defined at spec level)
+      # @param overlay [Hash<String, Hash>] A hash of overlay variable sets keyed by ID
+      #
+      # @return [Variables]
+      #
+      def initialize(base: {}, overlay: {})
+        set(base:, overlay:)
+      end
+
+      #
+      # Sets the base and overlay variable hashes
+      #
+      # @param base [Hash] The new base variable hash
+      # @param overlay [Hash<String, Hash>] The new overlay variable hashes
+      #
+      # @return [self]
+      #
+      def set(base:, overlay: {})
+        @base = Attribute.from(base)
+        @overlay = overlay
+
+        resolve_into_self(@base)
+        self
+      end
+
+      #
+      # Applies a specific overlay to the base variables
+      # If the overlay doesn't exist or is empty, no changes are made.
+      #
+      # @param id [String] The ID of the overlay to apply
+      #
+      # @return [nil]
+      #
+      def use_overlay(id)
+        active = @base
+
+        if (overlay = @overlay[id]) && overlay.present?
+          active = active.deep_merge(overlay)
+        end
+
+        resolve_into_self(active)
+        self
+      end
+
+      private
+
+      def resolve_into_self(hash)
+        # Start fresh
+        clear
+
+        # Load the resolved values into self
+        hash.each do |key, value|
+          self[key] = Attribute.from(value).resolved
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Core data structure that maintains context during test execution
+  #
+  # Context stores and provides access to global variables, test variables, and
+  # shared state across specs.
+  # It acts as a central repository for test data during execution.
+  #
+  # @example Accessing the current context
+  #   SpecForge.context.variables[:user_id] #=> 123
+  #
+  class Context < Data.define(:global, :store, :variables)
+    #
+    # Creates a new context with default values
+    #
+    # @param global [Hash] Global variables shared across all specs
+    # @param variables [Hash] Test variables specific to the current context
+    #
+    # @return [Context] A new context instance
+    #
+    def initialize(global: {}, variables: {})
+      super(
+        global: Global.new(**global),
+        store: Store.new,
+        variables: Variables.new(**variables)
+      )
+    end
+  end
+end
+
+require_relative "context/callbacks"
+require_relative "context/global"
+require_relative "context/store"
+require_relative "context/variables"

data/lib/spec_forge/core_ext/rspec.rb

@@ -1,18 +1,38 @@
 # frozen_string_literal: true
 
+return if defined?(SPEC_FORGE_INTERNAL_TESTING)
+
+#
+# RSpec's core testing framework module
+# Provides the fundamental structure and functionality for RSpec tests
+#
 module RSpec
+  #
+  # Core implementation details and extensions for RSpec
+  # Contains the fundamental building blocks of the RSpec testing framework
+  #
   module Core
+    #
+    # Handles notifications and reporting for RSpec test runs
+    # Manages how test results and metadata are processed and communicated
+    #
     module Notifications
       #
-      # I did attempt to do this without monkey patching
-      # Getting around the `rspec` word was making it difficult
+      # A monkey patch of an internal RSpec class to allow SpecForge to replace parts of
+      # RSpec's reporting output in order to provide useful feedback to the user.
+      # This replaces "rspec" in commands with "spec_forge", removes any line numbers, and
+      # ensures that failures properly report the YAML file that it occurred in.
       #
       class SummaryNotification
+        #
+        # Create an alias to RSpec original colorized_rerun_commands so it can be called at a
+        # later point.
+        #
+        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
+
         # Customizes RSpec's failure output to:
         # 1. Use 'spec_forge' instead of 'rspec' for rerun commands
         # 2. Remove line numbers since SpecForge uses dynamic spec generation
-        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
-
         def colorized_rerun_commands(colorizer)
           # Updating these at this point fixes the re-run for some failures - it depends
           failed_examples.each do |example|