spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/http/verb.rb

@@ -2,33 +2,112 @@
 
 module SpecForge
   module HTTP
+    #
+    # Represents an HTTP verb (method)
+    #
+    # This class provides a type-safe way to work with HTTP methods,
+    # with predefined constants for common verbs like GET, POST, etc.
+    #
+    # @example Using predefined verbs
+    #   HTTP::Verb::GET    # => #<HTTP::Verb::Get @name="GET">
+    #   HTTP::Verb::POST   # => #<HTTP::Verb::Post @name="POST">
+    #
+    # @example Checking verb types
+    #   verb = HTTP::Verb::POST
+    #   verb.post?   # => true
+    #   verb.get?    # => false
+    #
     class Verb < Data.define(:name)
+      #
+      # Represents the HTTP DELETE method
+      #
+      # @return [Delete] A DELETE verb instance
+      #
       class Delete < Verb
         def initialize = super(name: "DELETE")
       end
 
+      #
+      # Represents the HTTP GET method
+      #
+      # @return [Get] A GET verb instance
+      #
       class Get < Verb
         def initialize = super(name: "GET")
       end
 
+      #
+      # Represents the HTTP PATCH method
+      #
+      # @return [Patch] A PATCH verb instance
+      #
       class Patch < Verb
         def initialize = super(name: "PATCH")
       end
 
+      #
+      # Represents the HTTP POST method
+      #
+      # @return [Post] A POST verb instance
+      #
       class Post < Verb
         def initialize = super(name: "POST")
       end
 
+      #
+      # Represents the HTTP PUT method
+      #
+      # @return [Put] A PUT verb instance
+      #
       class Put < Verb
         def initialize = super(name: "PUT")
       end
 
+      #
+      # A predefined DELETE verb instance for HTTP method usage
+      #
+      # @return [Verb::Delete] A singleton instance representing the HTTP DELETE method
+      # @see Verb
+      #
       DELETE = Delete.new
+
+      #
+      # A predefined GET verb instance for HTTP method usage
+      #
+      # @return [Verb::Get] A singleton instance representing the HTTP GET method
+      # @see Verb
+      #
       GET = Get.new
+
+      #
+      # A predefined PATCH verb instance for HTTP method usage
+      #
+      # @return [Verb::Patch] A singleton instance representing the HTTP PATCH method
+      # @see Verb
+      #
       PATCH = Patch.new
+
+      #
+      # A predefined POST verb instance for HTTP method usage
+      #
+      # @return [Verb::Post] A singleton instance representing the HTTP POST method
+      # @see Verb
+      #
       POST = Post.new
+
+      #
+      # A predefined PUT verb instance for HTTP method usage
+      #
+      # @return [Verb::Put] A singleton instance representing the HTTP PUT method
+      # @see Verb
+      #
       PUT = Put.new
 
+      #
+      # All HTTP verbs as a lookup hash
+      #
+      # @return [Hash<Symbol, Verb>]
+      #
       VERBS = {
         delete: DELETE,
         get: GET,

data/lib/spec_forge/http.rb

@@ -1,5 +1,110 @@
 # frozen_string_literal: true
 
+module SpecForge
+  #
+  # HTTP module providing request and response handling for API testing
+  #
+  # This module contains the HTTP client, request object, and other components
+  # needed to make API calls and validate responses against expectations.
+  #
+  module HTTP
+    #
+    # A mapping of HTTP status codes to their standard descriptions
+    #
+    # This constant provides a lookup table of common HTTP status codes with their
+    # official descriptions according to HTTP specifications. Used internally
+    # to generate human-readable test output.
+    #
+    # @example Looking up a status code description
+    #   HTTP::STATUS_DESCRIPTIONS[200] # => "OK"
+    #   HTTP::STATUS_DESCRIPTIONS[404] # => "Not Found"
+    #
+    STATUS_DESCRIPTIONS = {
+      # Success codes
+      200 => "OK",
+      201 => "Created",
+      202 => "Accepted",
+      204 => "No Content",
+
+      # Redirection
+      301 => "Moved Permanently",
+      302 => "Found",
+      304 => "Not Modified",
+      307 => "Temporary Redirect",
+      308 => "Permanent Redirect",
+
+      # Client errors
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      406 => "Not Acceptable",
+      407 => "Proxy Authentication Required",
+      409 => "Conflict",
+      410 => "Gone",
+      411 => "Length Required",
+      413 => "Payload Too Large",
+      414 => "URI Too Long",
+      415 => "Unsupported Media Type",
+      421 => "Misdirected Request",
+      422 => "Unprocessable Content",
+      423 => "Locked",
+      424 => "Failed Dependency",
+      428 => "Precondition Required",
+      429 => "Too Many Requests",
+      431 => "Request Header Fields Too Large",
+
+      # Server errors
+      500 => "Internal Server Error",
+      501 => "Not Implemented",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+      504 => "Gateway Timeout"
+    }
+
+    #
+    # Converts an HTTP status code to a human-readable description
+    #
+    # Takes a numeric status code and returns a formatted string containing both
+    # the code and its description. Uses predefined descriptions for common codes,
+    # with fallbacks to category-based descriptions for uncommon codes.
+    #
+    # @param code [Integer, String] The HTTP status code to convert
+    #
+    # @return [String] A formatted description string (e.g., "200 OK", "404 Not Found")
+    #
+    # @example Common status codes
+    #   HTTP.status_code_to_description(200) # => "200 OK"
+    #   HTTP.status_code_to_description(404) # => "404 Not Found"
+    #
+    # @example Fallback descriptions for uncommon codes
+    #   HTTP.status_code_to_description(299) # => "299 Success"
+    #   HTTP.status_code_to_description(499) # => "499 Client Error"
+    #
+    def self.status_code_to_description(code)
+      code = code.to_i
+      description = STATUS_DESCRIPTIONS[code]
+      return "#{code} #{description}" if description
+
+      # Fallbacks by range
+      if code >= 100 && code < 200
+        "#{code} Informational"
+      elsif code >= 200 && code < 300
+        "#{code} Success"
+      elsif code >= 300 && code < 400
+        "#{code} Redirection"
+      elsif code >= 400 && code < 500
+        "#{code} Client Error"
+      elsif code >= 500 && code < 600
+        "#{code} Server Error"
+      else
+        code.to_s
+      end
+    end
+  end
+end
+
 require_relative "http/backend"
 require_relative "http/client"
 require_relative "http/verb"

data/lib/spec_forge/loader.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Responsible for loading specs from YAML files and converting them to testable objects
+  #
+  # The Loader reads spec files, parses them as YAML, and transforms them into
+  # a structure that can be used to create Forge objects. It also extracts
+  # metadata like line numbers for error reporting.
+  #
+  # @example Loading all specs
+  #   specs = Loader.load_from_files
+  #
+  class Loader
+    class << self
+      #
+      # Loads all spec YAML files and transforms them into normalized structures
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
+      #
+      def load_from_files
+        # metadata is not normalized because its not user managed
+        load_specs_from_files.map do |global, metadata, specs|
+          global =
+            begin
+              Normalizer.normalize_global_context!(global)
+            rescue => e
+              raise Error::SpecLoadError.new(e, metadata[:relative_path])
+            end
+
+          specs =
+            specs.map do |spec|
+              Normalizer.normalize_spec!(spec, label: "spec \"#{spec[:name]}\"")
+            rescue => e
+              raise Error::SpecLoadError.new(e, metadata[:relative_path], spec:)
+            end
+
+          [global, metadata, specs]
+        end
+      end
+
+      #
+      # Internal method that handles loading specs from files
+      #
+      # This method coordinates the entire spec loading process by:
+      # 1. Reading files from the specs directory
+      # 2. Parsing them as YAML
+      # 3. Transforming them into the proper structure
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
+      #
+      # @private
+      #
+      def load_specs_from_files
+        files = read_from_files
+        parse_and_transform_specs(files)
+      end
+
+      #
+      # Reads spec files from the spec_forge/specs directory
+      #
+      # @return [Array<Array<String, String>>] Array of [file_path, file_content] pairs
+      #
+      # @private
+      #
+      def read_from_files
+        path = SpecForge.forge_path.join("specs")
+
+        Dir[path.join("**/*.yml")].map do |file_path|
+          [file_path, File.read(file_path)]
+        end
+      end
+
+      #
+      # Parses YAML content and extracts line numbers for error reporting
+      #
+      # @param files [Array<Array<String, String>>] Array of [file_path, file_content] pairs
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each file
+      #
+      # @private
+      #
+      def parse_and_transform_specs(files)
+        base_path = SpecForge.forge_path.join("specs")
+
+        files.map do |file_path, content|
+          relative_path = Pathname.new(file_path).relative_path_from(base_path)
+
+          hash = YAML.load(content).deep_symbolize_keys
+
+          file_line_numbers = extract_line_numbers(content, hash)
+
+          # Currently, only holds onto global variables
+          global = hash.delete(:global) || {}
+
+          metadata = {
+            file_name: relative_path.basename(".yml").to_s,
+            relative_path: relative_path.to_s,
+            file_path:
+          }
+
+          specs =
+            hash.map do |spec_name, spec_hash|
+              line_number, *expectation_line_numbers = file_line_numbers[spec_name]
+
+              spec_hash[:id] = "spec_#{generate_id(spec_hash)}"
+              spec_hash[:name] = spec_name.to_s
+              spec_hash[:file_path] = metadata[:file_path]
+              spec_hash[:file_name] = metadata[:file_name]
+              spec_hash[:line_number] = line_number
+
+              # Check for expectations instead of defaulting. I want it to error
+              if (expectations = spec_hash[:expectations])
+                expectations.zip(expectation_line_numbers) do |expectation_hash, line_number|
+                  expectation_hash[:id] = "expect_#{generate_id(expectation_hash)}"
+                  expectation_hash[:name] = build_expectation_name(spec_hash, expectation_hash)
+                  expectation_hash[:line_number] = line_number
+                end
+              end
+
+              spec_hash
+            end
+
+          [global, metadata, specs]
+        end
+      end
+
+      #
+      # Extracts line numbers from each YAML section for error reporting
+      #
+      # @param content [String] The raw file content
+      # @param input_hash [Hash] The parsed YAML structure
+      #
+      # @return [Hash] A mapping of spec names to line numbers
+      #
+      # @private
+      #
+      def extract_line_numbers(content, input_hash)
+        # I hate this code, lol, and it hates me.
+        # I've tried to make it better, I've tried to clean it up, but every time I break it.
+        # If you know how to make this better, please submit a PR and save me.
+        spec_names = input_hash.keys
+        keys = {}
+
+        current_spec_name = nil
+        expectations_line = nil
+        expectations_indent = nil
+
+        content.lines.each_with_index do |line, index|
+          line_number = index + 1
+          clean_line = line.rstrip
+          indentation = line[/^\s*/].size
+
+          # Skip blank lines
+          next if clean_line.empty?
+
+          # Reset on top-level elements
+          if indentation == 0
+            current_spec_name = nil
+            expectations_line = nil
+            expectations_indent = nil
+
+            # Check if this line starts a spec we're interested in
+            spec_names.each do |spec_name|
+              next unless clean_line.start_with?("#{spec_name}:")
+
+              current_spec_name = spec_name
+              keys[current_spec_name] = [line_number]
+              break
+            end
+
+            next
+          end
+
+          # Skip if we're not in a relevant spec
+          next unless current_spec_name
+
+          # Found expectations section
+          if clean_line.match?(/^[^#]\s*expectations:/i)
+            expectations_line = line_number
+            expectations_indent = indentation
+            next
+          end
+
+          # Found an expectation item
+          if expectations_line && clean_line.start_with?("#{" " * expectations_indent}- ")
+            keys[current_spec_name] << line_number
+          end
+        end
+
+        keys
+      end
+
+      #
+      # Generates a unique ID for an object based on hash and object_id
+      #
+      # @param object [Object] The object to generate an ID for
+      #
+      # @return [String] A unique ID string
+      #
+      # @private
+      #
+      def generate_id(object)
+        "#{object.hash.abs.to_s(36)}_#{object.object_id.to_s(36)}"
+      end
+
+      #
+      # Builds a name for an expectation based on HTTP verb, URL, and optional name
+      #
+      # @param spec_hash [Hash] The spec configuration
+      # @param expectation_hash [Hash] The expectation configuration
+      #
+      # @return [String] A formatted expectation name (e.g., "GET /users - Find User")
+      #
+      # @private
+      #
+      def build_expectation_name(spec_hash, expectation_hash)
+        # Create a structure for these two attributes
+        # Removing the defaults and validators to avoid issues
+        structure = Normalizer::SHARED_ATTRIBUTES.slice(:http_verb, :url)
+          .transform_values { |v| v.except(:default, :validator) }
+
+        # Ignore any errors. It'll be caught above anyway
+        normalized_spec, _errors = Normalizer.new("", spec_hash, structure:).normalize
+        normalized_expectation, _errors = Normalizer.new("", expectation_hash, structure:).normalize
+
+        request_data = normalized_spec.deep_merge(normalized_expectation)
+
+        url = request_data[:url]
+        http_verb = request_data[:http_verb].presence || "GET"
+
+        # Finally generate the name
+        generate_expectation_name(http_verb:, url:, name: expectation_hash[:name])
+      end
+
+      #
+      # Generates an expectation name from its components
+      #
+      # @param http_verb [String] The HTTP verb (GET, POST, etc.)
+      # @param url [String] The URL path
+      # @param name [String, nil] Optional descriptive name
+      #
+      # @return [String] A formatted expectation name
+      #
+      # @private
+      #
+      def generate_expectation_name(http_verb:, url:, name: nil)
+        base = "#{http_verb.upcase} #{url}"   # GET /users
+        base += " - #{name}" if name.present? # GET /users - Returns 404 because y not?
+        base
+      end
+    end
+  end
+end

data/lib/spec_forge/matchers.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Provides custom RSpec matchers for SpecForge
+  #
+  # This singleton class is responsible for defining custom RSpec matchers
+  # that can be used in SpecForge tests. It makes these matchers available
+  # through RSpec's matcher system.
+  #
+  # @example Defining all matchers
+  #   SpecForge::Matchers.define
+  #
+  class Matchers
+    include Singleton
+
+    #
+    # Defines all custom matchers for use in SpecForge tests
+    #
+    # This is the main entry point that should be called once during
+    # initialization to make all custom matchers available.
+    #
+    def self.define
+      instance.define_all
+    end
+
+    #
+    # Defines all available custom matchers
+    #
+    # This method calls individual definition methods for each
+    # custom matcher supported by SpecForge.
+    #
+    def define_all
+      define_forge_and
+      define_have_size
+    end
+
+    private
+
+    #
+    # Defines the forge_and matcher for combining multiple matchers.
+    # Explicitly has "forge_" prefix to avoid potentially clashing with someone's
+    # existing custom matchers.
+    #
+    # This matcher allows chaining multiple matchers together with an AND
+    # condition, requiring all matchers to pass. It provides detailed
+    # failure messages showing which specific matchers failed.
+    #
+    # @example Using forge_and in a test
+    #   expect(response.body).to forge_and(
+    #     have_key("name"),
+    #     have_key("email"),
+    #     include("active" => be_truthy)
+    #   )
+    #
+    # @private
+    #
+    def define_forge_and
+      RSpec::Matchers.define :forge_and do |*matchers|
+        match do |actual|
+          @failures = []
+
+          matchers.each do |matcher|
+            next if matcher.matches?(actual)
+
+            @failures << [matcher, matcher.failure_message]
+          end
+
+          @failures.empty?
+        end
+
+        failure_message do
+          pass_count = matchers.size - @failures.size
+
+          message = "Expected to satisfy ALL of these conditions on:\n   #{actual.inspect}\n\n"
+
+          matchers.each_with_index do |matcher, i|
+            failure = @failures.find { |m, _| m == matcher }
+
+            if failure
+              message += "❌ #{i + 1}. #{matcher.description}\n"
+              message += "      → #{failure[1].gsub(/\s+/, " ").strip}\n\n"
+            else
+              message += "✅ #{i + 1}. #{matcher.description}\n\n"
+            end
+          end
+
+          message += "#{pass_count}/#{matchers.size} conditions met"
+          message
+        end
+
+        description do
+          "match all: " + matchers.join_map(", ", &:description)
+        end
+      end
+    end
+
+    #
+    # Defines the have_size matcher for checking collection sizes
+    #
+    # This matcher verifies that an object responds to the :size method
+    # and that its size matches the expected value.
+    #
+    # @example Using have_size in a test
+    #   expect(response.body["items"]).to have_size(5)
+    #
+    # @private
+    #
+    def define_have_size
+      RSpec::Matchers.define :have_size do |expected|
+        expected = RSpec::Matchers::BuiltIn::Eq.new(expected) if expected.is_a?(Integer)
+
+        match do |actual|
+          actual.respond_to?(:size) && expected.matches?(actual.size)
+        end
+
+        failure_message do |actual|
+          if actual.respond_to?(:size)
+            "expected #{actual.inspect} size to #{expected.description}, but got #{actual.size}"
+          else
+            "expected #{actual.inspect} to respond to :size"
+          end
+        end
+      end
+    end
+  end
+end
+
+# Define the custom matchers
+SpecForge::Matchers.define

data/lib/spec_forge/normalizer/configuration.rb

@@ -2,7 +2,23 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes configuration hash structure for SpecForge
+    #
+    # Ensures that the global configuration has the correct structure
+    # and default values for all required settings.
+    #
     class Configuration < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
         base_url: SHARED_ATTRIBUTES[:base_url].except(:default), # Make it required
         headers: SHARED_ATTRIBUTES[:headers],
@@ -32,20 +48,20 @@ module SpecForge
       #
       # Generates an empty configuration hash
       #
-      # @return [Hash]
+      # @return [Hash] Default configuration hash
       #
       def default_configuration
         Configuration.default
       end
 
       #
-      # Normalizes a configuration hash by standardizing its keys while ensuring the required data
-      # is provided or defaulted.
-      # Raises InvalidStructureError if anything is missing/invalid type
+      # Normalizes a configuration hash with validation
       #
       # @param input [Hash] The hash to normalize
       #
-      # @return [Hash] A normalized hash as a new instance
+      # @return [Hash] A normalized hash with defaults applied
+      #
+      # @raise [Error::InvalidStructureError] If validation fails
       #
       def normalize_configuration!(input)
         raise_errors! do
@@ -55,19 +71,16 @@ module SpecForge
 
       #
       # Normalize a configuration hash
-      # Used internally by .normalize_configuration!, but is available for utility
       #
-      # @param configuration [Hash] Configuration representation as a Hash
+      # @param configuration [Hash] Configuration hash
       #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_hash, errors]
       #
       # @private
       #
       def normalize_configuration(configuration)
         if !Type.hash?(configuration)
-          raise InvalidTypeError.new(configuration, Hash, for: "configuration")
+          raise Error::InvalidTypeError.new(configuration, Hash, for: "configuration")
         end
 
         Normalizer::Configuration.new("configuration", configuration).normalize