spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/factory.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 module SpecForge
+  #
+  # Manages factory definitions and registration with FactoryBot
+  # Provides methods for loading factories from YAML files
+  #
   class Factory
     #
-    # Loads the factories from their yml files and registers them with FactoryBot
+    # Loads factories from files and registers them with FactoryBot
+    # Sets up paths and loads definitions based on configuration
     #
     def self.load_and_register
       if SpecForge.configuration.factories.paths?
@@ -17,19 +22,18 @@ module SpecForge
     end
 
     #
-    # Loads any factories defined in the factories. A single file can contain one or more factories
+    # Loads factory definitions from YAML files
+    # Creates Factory instances but doesn't register them with FactoryBot
     #
-    # @return [Array<Factory>] An array of factories that were loaded.
-    #   Note: This factories have not been registered with FactoryBot.
-    #   See #register
+    # @return [Array<Factory>] Array of loaded factory instances
     #
     def self.load_from_files
-      path = SpecForge.forge.join("factories", "**/*.yml")
+      path = SpecForge.forge_path.join("factories", "**/*.yml")
 
       factories = []
 
       Dir[path].each do |file_path|
-        hash = YAML.load_file(file_path).deep_symbolize_keys
+        hash = YAML.load_file(file_path, symbolize_names: true)
 
         hash.each do |factory_name, factory_hash|
           factory_hash[:name] = factory_name
@@ -43,17 +47,32 @@ module SpecForge
 
     ############################################################################
 
-    attr_reader :name, :input, :model_class, :variables, :attributes
+    # @return [Symbol, String] The name of the factory
+    attr_reader :name
 
+    # @return [Hash] The raw input that defined this factory
+    attr_reader :input
+
+    # @return [String, nil] The model class name this factory represents, if specified
+    attr_reader :model_class
+
+    # @return [Hash<Symbol, Attribute>] Variables defined for this factory
+    attr_reader :variables
+
+    # @return [Hash<Symbol, Attribute>] The attributes that define this factory
+    attr_reader :attributes
+
+    #
+    # Creates a new Factory instance
     #
-    # Creates a new Factory
+    # @param name [String, Symbol] The name of the factory
+    # @param input [Hash] The attributes defining the factory
     #
-    # @param name [String] The name of the factory
-    # @param **input [Hash] Attributes to define the factory. See Normalizer::Factory
+    # @return [Factory] A new factory instance
     #
     def initialize(name:, **input)
       @name = name
-      input = Normalizer.normalize_factory!(input)
+      input = Normalizer.normalize!(input, using: :factory)
 
       @input = input
       @model_class = input[:model_class]
@@ -63,10 +82,10 @@ module SpecForge
     end
 
     #
-    # Registers this factory with FactoryBot.
-    # Once registered, you can call FactoryBot.build and other methods
+    # Registers this factory with FactoryBot
+    # Makes the factory available for use in specs
     #
-    # @return [Self]
+    # @return [self] Returns self for method chaining
     #
     def register
       dsl = FactoryBot::Syntax::Default::DSL.new
@@ -78,7 +97,7 @@ module SpecForge
       factory_forge = self
       dsl.factory(name, options) do
         factory_forge.attributes.each do |name, attribute|
-          add_attribute(name) { attribute.resolve_value }
+          add_attribute(name) { attribute.resolve }
         end
       end
 

data/lib/spec_forge/filter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Provides filtering capabilities for test suites based on different criteria
+  #
+  # The Filter class allows running specific tests by filtering forges, specs,
+  # and expectations based on file name, spec name, and expectation name.
+  #
+  # @example Filtering specs by name
+  #   forges = Loader.load_from_files
+  #   filtered = Filter.apply(forges, file_name: "users", spec_name: "create_user")
+  #
+  class Filter
+    class << self
+      #
+      # Prints out a message if any of the filters were used
+      #
+      # @param forges [Array<Forge>] The collection of forges that was filtered
+      # @param file_name [String, nil] Optional file name that was used by the filter
+      # @param spec_name [String, nil] Optional spec name that was used by the filter
+      # @param expectation_name [String, nil] Optional expectation name that was used by the filter
+      #
+      def announce(forges, file_name:, spec_name:, expectation_name:)
+        filters = {file_name:, spec_name:, expectation_name:}.compact_blank
+        return if filters.size == 0
+
+        filters_display = filters.join_map(", ") { |k, v| "#{k.in_quotes} => #{v.in_quotes}" }
+
+        expectation_count = forges.sum do |forge|
+          forge.specs.sum { |spec| spec.expectations.size }
+        end
+
+        puts "Applied filter #{filters_display}"
+        puts "Found #{expectation_count} #{"expectation".pluralize(expectation_count)}"
+      end
+
+      #
+      # Filters a collection of forges based on specified criteria
+      #
+      # This method allows running specific tests by filtering forges, specs,
+      # and expectations based on file name, spec name, and expectation name.
+      # It returns only the forges, specs, and expectations that match the criteria.
+      #
+      # @param forges [Array<Forge>] The collection of forges to filter
+      # @param file_name [String, nil] Optional file name to filter by
+      # @param spec_name [String, nil] Optional spec name to filter by
+      # @param expectation_name [String, nil] Optional expectation name to filter by
+      #
+      # @return [Array<Forge>] The filtered collection of forges
+      #
+      # @raise [ArgumentError] If filtering parameters are provided in an invalid combination
+      #
+      def apply(forges, file_name: nil, spec_name: nil, expectation_name: nil)
+        # Guard against invalid partial filters
+        if expectation_name && spec_name.blank?
+          raise ArgumentError, "The spec's name is required when filtering by an expectation's name"
+        end
+
+        if spec_name && file_name.blank?
+          raise ArgumentError, "The spec's filename is required when filtering by a spec's name"
+        end
+
+        forges.filter_map do |forge|
+          specs = forge.specs.filter_map do |spec|
+            next if file_name && spec.file_name != file_name  # File filter
+            next if spec_name && spec.name != spec_name       # Name filter
+
+            # Expectation filter
+            next spec unless expectation_name
+
+            spec.expectations.select! { |e| e.name == expectation_name }
+            next if spec.expectations.empty?
+
+            spec
+          end
+
+          next if specs.empty?
+
+          forge.specs = specs
+          forge
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Represents a collection of related specs loaded from a single YAML file
+  #
+  # A Forge contains multiple specs with their expectations, global variables,
+  # and request configuration. It acts as the container for all tests defined
+  # in a single file and manages their shared context.
+  #
+  # @example Creating a forge
+  #   global = {variables: {api_key: "123"}}
+  #   metadata = {file_name: "users", file_path: "/path/to/users.yml"}
+  #   specs = [{name: "list_users", url: "/users", expectations: [...]}]
+  #   forge = Forge.new(global, metadata, specs)
+  #
+  class Forge
+    #
+    # The name of this forge from the relative path
+    #
+    # @return [String] The name derived from the file path
+    #
+    attr_reader :name
+
+    #
+    # Global variables and configuration shared across all specs
+    #
+    # @return [Hash] The global variables and configuration
+    #
+    attr_reader :global
+
+    #
+    # Metadata about the spec file
+    #
+    # @return [Hash] File information such as path and name
+    #
+    attr_reader :metadata
+
+    #
+    # Variables defined at the spec and expectation levels
+    #
+    # @return [Hash] Variable definitions organized by spec
+    #
+    attr_reader :variables
+
+    #
+    # Request configuration for the specs
+    #
+    # @return [Hash] HTTP request configuration by spec
+    #
+    attr_reader :request
+
+    #
+    # Collection of specs contained in this forge
+    #
+    # @return [Array<Spec>] The specs defined in this file
+    #
+    attr_accessor :specs
+
+    #
+    # Creates a new Forge instance containing specs from a YAML file
+    #
+    # @param global [Hash] Global variables shared across all specs in the file
+    # @param metadata [Hash] Information about the spec file
+    # @param specs [Array<Hash>] Array of spec definitions from the file
+    #
+    # @return [Forge] A new forge instance with the processed specs
+    #
+    def initialize(global, metadata, specs)
+      @name = metadata[:relative_path]
+
+      @global = global
+      @metadata = metadata
+
+      @variables = extract_variables!(specs)
+      @request = extract_request!(specs)
+      @specs = specs.map { |spec| Spec.new(**spec) }
+    end
+
+    #
+    # Retrieves variables for a specific spec
+    #
+    # Returns the variables defined for a specific spec, including
+    # both base variables and any overlay variables for its expectations.
+    #
+    # @param spec [Spec] The spec to get variables for
+    #
+    # @return [Hash] The variables for the spec
+    #
+    def variables_for_spec(spec)
+      @variables[spec.id]
+    end
+
+    private
+
+    #
+    # Extracts variables from specs and organizes them into base and overlay variables
+    #
+    # @param specs [Array<Hash>] Array of spec definitions
+    #
+    # @return [Hash] A hash mapping spec IDs to their variables
+    #
+    # @private
+    #
+    def extract_variables!(specs)
+      #
+      # Creates a hash that looks like this:
+      #
+      # {
+      #   spec_1: {
+      #     base: {var_1: true, var_2: false},
+      #     overlay: {
+      #       expectation: {var_1: false}
+      #     }
+      #   },
+      #   spec_2: ...
+      # }
+      #
+      specs.each_with_object({}) do |spec, hash|
+        overlay = spec[:expectations].to_h { |e| [e[:id], e.delete(:variables)] }.compact_blank
+
+        hash[spec[:id]] = {base: spec.delete(:variables), overlay:}
+      end
+    end
+
+    #
+    # Extracts request configuration from specs and organizes them into base and overlay configs
+    #
+    # @param specs [Array<Hash>] Array of spec definitions
+    #
+    # @return [Hash] A hash mapping spec IDs to their request configurations
+    #
+    # @private
+    #
+    def extract_request!(specs)
+      #
+      # Creates a hash that looks like this:
+      #
+      # {
+      #   spec_1: {
+      #     base: {base_url: "https://foo.bar", url: "", ...},
+      #     overlay: {
+      #       expectation: {base_url: "https://bar.baz", ...}
+      #     }
+      #   },
+      #   spec_2: ...
+      # }
+      #
+      config = SpecForge.configuration.to_h.slice(:base_url, :headers, :query)
+
+      specs.each_with_object({}) do |spec, hash|
+        overlay = spec[:expectations].to_h do |expectation|
+          [
+            expectation[:id],
+            expectation.extract!(*HTTP::REQUEST_ATTRIBUTES).compact_blank
+          ]
+        end
+
+        overlay.compact_blank!
+
+        base = spec.extract!(*HTTP::REQUEST_ATTRIBUTES)
+        base.compact_blank!
+
+        base = config.deep_merge(base)
+        base[:http_verb] ||= "GET"
+
+        hash[spec[:id]] = {base:, overlay:}
+      end
+    end
+  end
+end

data/lib/spec_forge/http/backend.rb

@@ -2,16 +2,44 @@
 
 module SpecForge
   module HTTP
+    #
+    # Handles the low-level HTTP operations using Faraday
+    #
+    # This class is responsible for creating and configuring the Faraday connection,
+    # executing the actual HTTP requests, and handling URL path parameter substitution.
+    #
+    # @example Basic usage
+    #   backend = Backend.new(request)
+    #   response = backend.get("/users")
+    #
     class Backend
+      #
+      # Regular expression to match { placeholder } style URL parameters
+      #
+      # @return [Regexp]
+      #
       CURLY_PLACEHOLDER = /\{(\w+)\}/
+
+      #
+      # Regular expression to match :placeholder style URL parameters
+      #
+      # @return [Regexp]
+      #
       COLON_PLACEHOLDER = /:(\w+)/
 
+      #
+      # The configured Faraday connection
+      #
+      # @return [Faraday::Connection]
+      #
       attr_reader :connection
 
       #
-      # Configures Faraday with the config values
+      # Configures a new Faraday connection based on the request configuration
+      #
+      # @param request [HTTP::Request] The request configuration to use
       #
-      # @param request [HTTP::Request]
+      # @return [Backend] A new backend instance with a configured connection
       #
       def initialize(request)
         @connection =
@@ -23,7 +51,7 @@ module SpecForge
             end
 
             # Headers
-            builder.headers.merge!(request.headers.resolve)
+            builder.headers.merge!(request.headers.resolved)
           end
       end
 
@@ -31,79 +59,112 @@ module SpecForge
       # Executes a DELETE request to <base_url>/<provided_url>
       #
       # @param url [String] The URL path to DELETE
-      # @param query [Hash] Any query attributes to send
-      # @param body [Hash]  Any body data to send
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Any query parameters to send
+      # @param body [Hash] Any body data to send
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def delete(url, query: {}, body: {})
+      def delete(url, headers: {}, query: {}, body: {})
         url = normalize_url(url, query)
-        connection.delete(url) { |request| update_request(request, query, body) }
+        connection.delete(url) { |request| update_request(request, headers, query, body) }
       end
 
       #
       # Executes a GET request to <base_url>/<provided_url>
       #
       # @param url [String] The URL path to GET
-      # @param query [Hash] Any query attributes to send
-      # @param body [Hash]  Any body data to send
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Any query parameters to send
+      # @param body [Hash] Any body data to send
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def get(url, query: {}, body: {})
+      def get(url, headers: {}, query: {}, body: {})
         url = normalize_url(url, query)
-        connection.get(url) { |request| update_request(request, query, body) }
+        connection.get(url) { |request| update_request(request, headers, query, body) }
       end
 
       #
       # Executes a PATCH request to <base_url>/<provided_url>
       #
       # @param url [String] The URL path to PATCH
-      # @param query [Hash] Any query attributes to send
-      # @param body [Hash]  Any body data to send
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Any query parameters to send
+      # @param body [Hash] Any body data to send
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def patch(url, query: {}, body: {})
+      def patch(url, headers: {}, query: {}, body: {})
         url = normalize_url(url, query)
-        connection.patch(url) { |request| update_request(request, query, body) }
+        connection.patch(url) { |request| update_request(request, headers, query, body) }
       end
 
       #
       # Executes a POST request to <base_url>/<provided_url>
       #
       # @param url [String] The URL path to POST
-      # @param query [Hash] Any query attributes to send
-      # @param body [Hash]  Any body data to send
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Any query parameters to send
+      # @param body [Hash] Any body data to send
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def post(url, query: {}, body: {})
+      def post(url, headers: {}, query: {}, body: {})
         url = normalize_url(url, query)
-        connection.post(url) { |request| update_request(request, query, body) }
+        connection.post(url) { |request| update_request(request, headers, query, body) }
       end
 
       #
       # Executes a PUT request to <base_url>/<provided_url>
       #
       # @param url [String] The URL path to PUT
-      # @param query [Hash] Any query attributes to send
-      # @param body [Hash]  Any body data to send
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Any query parameters to send
+      # @param body [Hash] Any body data to send
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def put(url, query: {}, body: {})
+      def put(url, headers: {}, query: {}, body: {})
         url = normalize_url(url, query)
-        connection.put(url) { |request| update_request(request, query, body) }
+        connection.put(url) { |request| update_request(request, headers, query, body) }
       end
 
       private
 
-      def update_request(request, query, body)
+      #
+      # Updates the request with query parameters and body
+      #
+      # @param request [Faraday::Request] The request to update
+      # @param headers [Hash] HTTP headers to add
+      # @param query [Hash] Query parameters to add
+      # @param body [Hash] Body data to add
+      #
+      # @private
+      #
+      def update_request(request, headers, query, body)
+        request.headers.merge!(headers)
+        request.headers.transform_values!(&:to_s)
+
         request.params.merge!(query)
         request.body = body.to_json
       end
 
+      #
+      # Normalizes a URL by replacing path parameters with their values
+      #
+      # Handles both curly brace style {param} and colon style :param
+      # Parameters are extracted from the query hash and removed after substitution
+      #
+      # @param url [String] The URL pattern with potential placeholders
+      # @param query [Hash] Query parameters that may contain values for placeholders
+      #
+      # @return [String] The URL with placeholders replaced by actual values
+      #
+      # @raise [URI::InvalidURIError] If the resulting URL is invalid
+      #
+      # @private
+      #
       def normalize_url(url, query)
         # /users/<user_id>
         url = replace_url_placeholder(url, query, CURLY_PLACEHOLDER)
@@ -122,6 +183,17 @@ module SpecForge
         url
       end
 
+      #
+      # Replaces URL placeholders with values from the query hash
+      #
+      # @param url [String] The URL with placeholders
+      # @param query [Hash] The query parameters containing values
+      # @param regex [Regexp] The pattern to match (curly or colon style)
+      #
+      # @return [String] The URL with placeholders replaced
+      #
+      # @private
+      #
       def replace_url_placeholder(url, query, regex)
         match = url.match(regex)
         return url if match.nil?

data/lib/spec_forge/http/client.rb

@@ -2,30 +2,40 @@
 
 module SpecForge
   module HTTP
+    #
+    # HTTP client that executes requests and returns responses
+    #
+    # This class serves as a mediator between the test expectations
+    # and the actual HTTP backend implementation.
+    #
+    # @example Basic usage
+    #   client = HTTP::Client.new(base_url: "https://api.example.com")
+    #   response = client.call(request)
+    #
     class Client
-      attr_reader :request
-
       #
-      # Creates a new HTTP client to middleman between the tests and the backend
+      # Creates a new HTTP client with configured backend
       #
-      # @param ** [Hash] Request attributes
+      # @return [Client] A new HTTP client instance
       #
       def initialize(**)
-        @request = Request.new(**)
-        @adapter = Backend.new(request)
+        @backend = Backend.new(HTTP::Request.new(**))
       end
 
       #
-      # Triggers an HTTP request to the URL
+      # Executes an HTTP request and returns the response
+      #
+      # @param request [HTTP::Request] The request to execute
       #
-      # @return [Hash] The response
+      # @return [Faraday::Response] The HTTP response
       #
-      def call
-        @adapter.public_send(
-          request.http_verb,
+      def call(request)
+        @backend.public_send(
+          request.http_verb.to_s.downcase,
           request.url,
-          query: request.query.resolve,
-          body: request.body.resolve
+          headers: request.headers.resolved,
+          query: request.query.resolved,
+          body: request.body.resolved
         )
       end
     end