spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/forge.rb

@@ -0,0 +1,170 @@
+# 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)] }
+          .reject { |_k, v| v.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).reject { |_k, v| v.blank? }
+          ]
+        end
+
+        overlay.reject! { |_k, v| v.blank? }
+
+        base = spec.extract!(*HTTP::REQUEST_ATTRIBUTES)
+        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,110 @@ 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.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 +181,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

data/lib/spec_forge/http/request.rb

@@ -2,88 +2,100 @@
 
 module SpecForge
   module HTTP
-    class Request < Data.define(:base_url, :url, :http_method, :headers, :query, :body)
-      HEADER = /^[A-Z][A-Za-z0-9!-]*$/
+    #
+    # The attributes used to build a Request
+    #
+    # @return [Array<Symbol>]
+    #
+    REQUEST_ATTRIBUTES = [:base_url, :url, :http_verb, :headers, :query, :body].freeze
 
+    #
+    # Represents an HTTP request configuration
+    #
+    # This data object contains all the necessary information to construct
+    # an HTTP request, including URL, method, headers, query params, and body.
+    #
+    # @example Creating a request
+    #   request = HTTP::Request.new(
+    #     base_url: "https://api.example.com",
+    #     url: "/users",
+    #     http_verb: "GET",
+    #     headers: {"Content-Type" => "application/json"},
+    #     query: {page: 1},
+    #     body: {}
+    #   )
+    #
+    class Request < Data.define(*REQUEST_ATTRIBUTES)
       #
-      # Initializes a new Request instance with the given options
-      #
-      # @param [Hash] options The options to create the Request with
+      # Regex that attempts to match a valid header
       #
-      # @option options [String] :url The request URL
+      # @return [Regexp]
       #
-      # @option options [String, Verb] :http_method The HTTP method to use
+      HEADER = /^[A-Z][A-Za-z0-9!-]*$/
+
       #
-      # @option options [Hash] :headers Any headers
+      # Creates a new Request with standardized headers and values
       #
-      # @option options [Hash] :query The query parameters for the request (defaults to {})
+      # @param base_url [String, nil] The base URL for the request
+      # @param url [String, nil] The path portion of the URL
+      # @param http_verb [String, Symbol, nil] The HTTP method (GET, POST, etc.)
+      # @param headers [Hash, nil] HTTP headers for the request
+      # @param query [Hash, nil] Query parameters to include
+      # @param body [Hash, nil] Request body data
       #
-      # @option options [Hash] :body The request body (defaults to {})
+      # @return [Request] A new immutable request object
       #
       def initialize(**options)
-        url = extract_url(options)
-        base_url = extract_base_url(options)
-        http_method = normalize_http_method(options)
-        headers = normalize_headers(options)
-        query = normalize_query(options)
-        body = normalize_body(options)
+        base_url = options[:base_url] || ""
+        url = options[:url] || ""
+        http_verb = Verb.from(options[:http_verb].presence || "GET")
+        query = Attribute.from(options[:query] || {})
+        body = Attribute.from(options[:body] || {})
+        headers = normalize_headers(options[:headers] || {})
 
-        super(base_url:, url:, http_method:, headers:, query:, body:)
-      end
-
-      def http_verb
-        http_method.name.downcase
+        super(base_url:, url:, http_verb:, headers:, query:, body:)
       end
 
+      #
+      # Returns a hash representation with all attributes fully resolved
+      #
+      # @return [Hash] The request data with all dynamic values resolved
+      #
       def to_h
-        super.transform_values { |v| v.respond_to?(:resolve) ? v.resolve : v }
+        super.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
       end
 
       private
 
-      def extract_base_url(options)
-        options[:base_url].resolve
-      end
-
-      def extract_url(options)
-        options[:url].resolve
-      end
-
-      def normalize_http_method(options)
-        method = options[:http_method].resolve.presence || "GET"
-
-        if method.is_a?(String)
-          Verb.from(method)
-        else
-          method
-        end
-      end
-
-      def normalize_headers(options)
-        headers = options[:headers].transform_keys do |key|
-          key = key.to_s
+      #
+      # Normalizes HTTP header keys to standard format
+      #
+      # Converts snake_case and other formats to HTTP Header-Case format
+      # Examples:
+      #   content_type -> Content-Type
+      #   api_key -> Api-Key
+      #
+      # @param headers [Hash] The headers to normalize
+      #
+      # @return [Attribute::ResolvableHash] Normalized headers as attributes
+      #
+      # @private
+      #
+      def normalize_headers(headers)
+        headers =
+          headers.transform_keys do |key|
+            key = key.to_s
 
-          # If the key is already like a header, don't change it
-          if key.match?(HEADER)
-            key
-          else
-            # content_type => Content-Type
-            key.downcase.titleize.gsub(/\s+/, "-")
+            # If the key is already like a header, don't change it
+            if key.match?(HEADER)
+              key
+            else
+              # content_type => Content-Type
+              key.downcase.titleize.gsub(/\s+/, "-")
+            end
           end
-        end
-
-        headers = Attribute.bind_variables(headers, options[:variables])
-        Attribute::ResolvableHash.new(headers)
-      end
-
-      def normalize_query(options)
-        query = Attribute.bind_variables(options[:query], options[:variables])
-        Attribute::ResolvableHash.new(query)
-      end
 
-      def normalize_body(options)
-        body = Attribute.bind_variables(options[:body], options[:variables])
-        Attribute::ResolvableHash.new(body)
+        Attribute.from(headers)
       end
     end
   end