spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/attribute/resolvable_hash.rb

@@ -3,23 +3,81 @@
 module SpecForge
   class Attribute
     #
-    # Represents a hash that may contain Attributes
+    # Represents a hash that may contain attributes that need resolution
+    #
+    # This delegator wraps a hash and provides methods to recursively resolve
+    # any attribute objects contained within it. It allows hashes to contain
+    # dynamic content like variables and faker values.
+    #
+    # @example In code
+    #   hash = {name: Attribute::Faker.new("faker.name.name"), id: 123}
+    #   resolvable = Attribute::ResolvableHash.new(hash)
+    #   resolvable.resolved # => {name: "John Smith", id: 123}
     #
     class ResolvableHash < SimpleDelegator
       include Resolvable
 
+      #
+      # Returns the underlying hash
+      #
+      # @return [Hash] The delegated hash
+      #
       def value
         __getobj__
       end
 
+      #
+      # Returns a new hash with all values fully resolved to their final values.
+      # Uses the cached version of each value if available.
+      #
+      # @return [Hash] A new hash with all values fully resolved to their final values
+      #
+      # @example
+      #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+      #   hash_attr.resolved # => {name: "Jane Doe"} (with result cached)
+      #
+      def resolved
+        value.transform_values(&resolved_proc)
+      end
+
+      #
+      # Freshly resolves all values in the hash.
+      # Unlike #resolved, this doesn't use cached values, ensuring fresh resolution.
+      #
+      # @return [Hash] A new hash with all values freshly resolved
+      #
+      # @example
+      #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+      #   hash_attr.resolve # => {name: "John Smith"} (fresh value each time)
+      #
       def resolve
-        value.transform_values(&resolvable_proc)
+        value.transform_values(&resolve_proc)
       end
 
-      def resolve_value
-        value.transform_values(&resolvable_value_proc)
+      #
+      # Converts all values in the hash to RSpec matchers.
+      # Transforms each hash value to a matcher using resolve_as_matcher_proc,
+      # then wraps the entire result in a matcher suitable for hash comparison.
+      #
+      # This ensures proper nesting of matchers in hash structures,
+      # which is vital for readable failure messages in complex expectations.
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher for this hash
+      #
+      # @example
+      #   hash = Attribute::ResolvableHash.new({name: "Test", age: 42})
+      #   hash.resolve_as_matcher # => include("name" => eq("Test"), "age" => eq(42))
+      #
+      def resolve_as_matcher
+        result = value.transform_values(&resolve_as_matcher_proc)
+        Attribute::Literal.new(result).resolve_as_matcher
       end
 
+      #
+      # Binds variables to any attribute objects in the hash values
+      #
+      # @param variables [Hash] The variables to bind
+      #
       def bind_variables(variables)
         value.each_value { |v| Attribute.bind_variables(v, variables) }
       end

data/lib/spec_forge/attribute/store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that references values from stored test results
+    #
+    # This class allows accessing data from previous test executions that were
+    # saved using the `store_as` directive. It provides access to response data
+    # including status, headers, and body from previously run expectations.
+    #
+    # @example Basic usage in YAML
+    #   create_user:
+    #     path: /users
+    #     method: post
+    #     expectations:
+    #     - store_as: new_user
+    #       body:
+    #         name: faker.name.name
+    #       expect:
+    #         status: 201
+    #
+    #   get_user:
+    #     path: /users/{id}
+    #     expectations:
+    #     - query:
+    #         id: store.new_user.body.id
+    #       expect:
+    #         status: 200
+    #
+    # @example Accessing specific response components
+    #   check_status:
+    #     path: /health
+    #     expectations:
+    #     - variables:
+    #         expected_status: store.new_user.status
+    #         auth_token: store.new_user.headers.authorization
+    #         user_name: store.new_user.body.user.name
+    #       expect:
+    #         status: 200
+    #
+    class Store < Attribute
+      include Chainable
+
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^store\./i
+
+      alias_method :stored_id, :header
+
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Context::Store::Entry, nil] The stored entry or nil if not found
+      #
+      def base_object
+        @base_object ||= SpecForge.context.store[stored_id.to_s]
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/transform.rb

@@ -2,9 +2,34 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that transforms other attributes
+    #
+    # This class provides transformation functions like join that can be applied
+    # to other attributes or values. It allows complex data manipulation without
+    # writing Ruby code.
+    #
+    # @example Join transformation in YAML
+    #   full_name:
+    #     transform.join:
+    #     - variables.first_name
+    #     - " "
+    #     - variables.last_name
+    #
     class Transform < Parameterized
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^transform\./i
 
+      #
+      # The available transformation methods
+      #
+      # @return [Array<String>]
+      #
       TRANSFORM_METHODS = %w[
         join
       ].freeze
@@ -12,9 +37,7 @@ module SpecForge
       attr_reader :function
 
       #
-      # Represents any attribute that is a transform call
-      #
-      #   transform.<function>
+      # Creates a new transform attribute with the specified function and arguments
       #
       def initialize(...)
         super
@@ -22,16 +45,21 @@ module SpecForge
         # Remove prefix
         @function = @input.sub("transform.", "")
 
-        raise InvalidTransformFunctionError, input unless TRANSFORM_METHODS.include?(function)
+        raise Error::InvalidTransformFunctionError, input unless TRANSFORM_METHODS.include?(function)
 
         prepare_arguments!
       end
 
+      #
+      # Returns the result of applying the transformation function
+      #
+      # @return [Object] The transformed value
+      #
       def value
         case function
         when "join"
           # Technically supports any attribute, but I ain't gonna test all them edge cases
-          arguments[:positional].resolve.join
+          arguments[:positional].resolved.join
         end
       end
     end

data/lib/spec_forge/attribute/variable.rb

@@ -3,26 +3,57 @@
 module SpecForge
   class Attribute
     #
-    # Represents any attribute that is a variable reference
+    # Represents an attribute that references a variable
     #
-    #   variables.<variable_name>
+    # This class allows referencing variables defined in the test context.
+    # It supports chained access to methods and properties of variable values.
+    #
+    # @example Basic usage in YAML
+    #   user_id: variables.user.id
+    #   company_name: variables.company.name
+    #
+    # @example Nested access in YAML
+    #   post_author: variables.post.comments.first.author.name
     #
     class Variable < Attribute
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^variables\./i
 
       alias_method :variable_name, :header
 
+      #
+      # Binds the referenced variable to this attribute
+      #
+      # @param variables [Hash] A hash of variables to look up in
+      #
+      # @raise [Error::MissingVariableError] If the variable is not found
+      # @raise [Error::InvalidTypeError] If variables is not a hash
+      #
       def bind_variables(variables)
-        raise InvalidTypeError.new(variables, Hash, for: "'variables'") unless Type.hash?(variables)
+        if !Type.hash?(variables)
+          raise Error::InvalidTypeError.new(variables, Hash, for: "'variables'")
+        end
 
         # Don't nil check here.
-        raise MissingVariableError, variable_name unless variables.key?(variable_name)
+        raise Error::MissingVariableError, variable_name unless variables.key?(variable_name)
 
-        @base_object = variables[variable_name]
+        @variable = variables[variable_name]
+      end
 
-        self
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The variable value
+      #
+      def base_object
+        @variable || bind_variables(SpecForge.context.variables)
       end
     end
   end

data/lib/spec_forge/attribute.rb

@@ -5,18 +5,21 @@ require_relative "attribute/parameterized"
 require_relative "attribute/chainable"
 require_relative "attribute/resolvable"
 
-# Doesn't matter
-require_relative "attribute/factory"
-require_relative "attribute/faker"
-require_relative "attribute/literal"
-require_relative "attribute/matcher"
-require_relative "attribute/regex"
-require_relative "attribute/resolvable_array"
-require_relative "attribute/resolvable_hash"
-require_relative "attribute/transform"
-require_relative "attribute/variable"
-
 module SpecForge
+  #
+  # Base class for all attribute types in SpecForge.
+  # Attributes represent values that can be transformed, resolved, or have special meaning
+  # in the context of specs and expectations.
+  #
+  # The Attribute system handles dynamic data generation, variable references,
+  # matchers, transformations and other special values in YAML specs.
+  #
+  # @example Basic usage in YAML
+  #   username: faker.internet.username    # A dynamic faker attribute
+  #   email: /\w+@\w+\.\w+/                # A regex attribute
+  #   status: kind_of.integer              # A matcher attribute
+  #   user_id: variables.user.id           # A variable reference
+  #
   class Attribute
     include Resolvable
 
@@ -66,7 +69,7 @@ module SpecForge
     end
 
     #
-    # Creates an Attribute instance from a string, handling any macros
+    # Creates an Attribute instance from a string
     #
     # @param string [String] The input string
     #
@@ -75,24 +78,31 @@ module SpecForge
     # @private
     #
     def self.from_string(string)
-      case string
-      when Faker::KEYWORD_REGEX
-        Faker.new(string)
-      when Variable::KEYWORD_REGEX
-        Variable.new(string)
-      when Matcher::KEYWORD_REGEX
-        Matcher.new(string)
-      when Factory::KEYWORD_REGEX
-        Factory.new(string)
-      when Regex::KEYWORD_REGEX
-        Regex.new(string)
-      else
-        Literal.new(string)
-      end
+      klass =
+        case string
+        when Factory::KEYWORD_REGEX
+          Factory
+        when Faker::KEYWORD_REGEX
+          Faker
+        when Global::KEYWORD_REGEX
+          Global
+        when Matcher::KEYWORD_REGEX
+          Matcher
+        when Regex::KEYWORD_REGEX
+          Regex
+        when Store::KEYWORD_REGEX
+          Store
+        when Variable::KEYWORD_REGEX
+          Variable
+        else
+          Literal
+        end
+
+      klass.new(string)
     end
 
     #
-    # Creates an Attribute instance from a hash, handling any macros
+    # Creates an Attribute instance from a hash
     #
     # @param hash [Hash] The input hash
     #
@@ -118,66 +128,156 @@ module SpecForge
       end
     end
 
+    #
+    # The original input value
+    #
+    # @return [Object]
+    #
     attr_reader :input
 
     #
-    # @param input [Object] Anything
+    # Creates a new attribute
+    #
+    # @param input [Object] The original input value
     #
     def initialize(input)
       @input = input
     end
 
     #
-    # Returns the processed value of the input
+    # Compares this attributes input to other
+    #
+    # @param other [Object, Attribute] If another Attribute, the input will be compared
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      other =
+        if other.is_a?(Attribute)
+          other.input
+        else
+          other
+        end
+
+      input == other
+    end
+
+    #
+    # Returns the processed value of this attribute.
+    # Recursively calls #value on underlying attributes, but does NOT resolve
+    # all nested structures completely.
     #
-    # For literals, this is the input itself.
-    # For generated values (Faker, Transform), this is the result of their operations.
+    # This returns an intermediate representation - for fully resolved values, use #resolve instead.
     #
     # @return [Object] The processed value of this attribute
     #
     # @raise [RuntimeError] if not implemented by subclass
     #
+    # @example
+    #   variable_attr = Attribute::Variable.new("variables.user")
+    #   variable_attr.value # => User instance, but any attributes of User remain
+    #   as Attribute objects
+    #
     def value
       raise "not implemented"
     end
 
     #
-    # Returns the fully evaluated result, recursively resolving any nested attributes
+    # Returns the fully evaluated result with complete recursive resolution.
+    # Calls #value internally and then resolves all nested attributes, caching the result.
     #
-    # @return [Object] The resolved value
+    # Use this when you need the final, fully-resolved value with all nested attributes
+    # fully evaluated to their primitive values.
     #
-    # @example Simple literal
-    #   attr = Attribute::Literal.new("hello")
-    #   attr.resolve # => "hello"
+    # @return [Object] The completely resolved value with cached results
     #
-    # @example Nested array with faker
-    #   attr = Attribute::Literal.new(["faker.number.positive", ["faker.name.first_name"]])
-    #   attr.resolve # => [42, ["Jane"]]
+    # @example
+    #   faker_attr = Attribute::Faker.new("faker.name.first_name")
+    #   faker_attr.resolved # => "Jane" (result is cached in @resolved)
+    #   faker_attr.resolved # => "Jane" (returns same cached value)
     #
-    def resolve
-      @resolved ||= resolve_value
+    def resolved
+      @resolved ||= resolve
     end
 
-    def resolve_value
-      __resolve(value)
+    #
+    # Performs recursive resolution of the attribute's value.
+    # Handles nested arrays and hashes by recursively resolving their elements.
+    #
+    # Unlike #resolved, this method doesn't cache results and can be used
+    # when fresh resolution is needed each time.
+    #
+    # @return [Object] The recursively resolved value without caching
+    #
+    # @example
+    #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+    #   hash_attr.resolve # => {name: "John Smith"}
+    #   hash_attr.resolve # => {name: "Jane Doe"} (different value on each call)
+    #
+    def resolve
+      case value
+      when ArrayLike
+        value.map(&resolved_proc)
+      when HashLike
+        value.transform_values(&resolved_proc)
+      else
+        value
+      end
     end
 
     #
-    # Compares this attributes input to other
+    # Converts this attribute to an appropriate RSpec matcher.
+    # Handles different types of values by creating the right matcher type:
+    # - Arrays become contain_exactly matchers
+    # - Hashes become include matchers
+    # - Regexp become match matchers
+    # - Existing matchers are passed through
+    # - Other values become eq matchers
     #
-    # @param other [Object, Attribute] If another Attribute, the input will be compared
+    # This method is crucial for nested matcher structures and compound matchers
+    # like matcher.and that require all values to be proper matchers.
     #
-    # @return [Boolean]
+    # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher representing this attribute
     #
-    def ==(other)
-      other =
-        if other.is_a?(Attribute)
-          other.input
+    # @example Converting different values to matchers
+    #   literal_attr = Attribute::Literal.new("hello")
+    #   literal_attr.resolve_as_matcher # => eq("hello")
+    #
+    #   array_attr = Attribute::ResolvableArray.new([1, 2, 3])
+    #   array_attr.resolve_as_matcher # => contain_exactly(eq(1), eq(2), eq(3))
+    #
+    #   hash_attr = Attribute::ResolvableHash.new({name: "Test"})
+    #   hash_attr.resolve_as_matcher # => include("name" => eq("Test"))
+    #
+    def resolve_as_matcher
+      methods = Attribute::Matcher::MATCHER_METHODS
+
+      case resolved
+      when Array, ArrayLike
+        resolved_array = resolved.map(&resolve_as_matcher_proc)
+
+        if resolved_array.size > 0
+          methods.contain_exactly(*resolved_array)
         else
-          other
+          methods.eq([])
         end
+      when Hash, HashLike
+        resolved_hash = resolved.transform_values(&resolve_as_matcher_proc).stringify_keys
 
-      input == other
+        if resolved_hash.size > 0
+          methods.include(**resolved_hash)
+        else
+          methods.eq({})
+        end
+      when Attribute::Matcher, Regexp
+        methods.match(resolved)
+      when RSpec::Matchers::BuiltIn::BaseMatcher,
+          RSpec::Matchers::DSL::Matcher,
+          Class
+        resolved # Pass through
+      else
+        methods.eq(resolved)
+      end
     end
 
     #
@@ -185,20 +285,20 @@ module SpecForge
     #
     # @param variables [Hash] A hash of variable attributes
     #
-    def bind_variables(_variables)
-    end
-
-    protected
-
-    def __resolve(value)
-      case value
-      when ArrayLike
-        value.map(&resolvable_proc)
-      when HashLike
-        value.transform_values(&resolvable_proc)
-      else
-        value
-      end
+    def bind_variables(variables)
     end
   end
 end
+
+# Order doesn't matter
+require_relative "attribute/factory"
+require_relative "attribute/faker"
+require_relative "attribute/global"
+require_relative "attribute/literal"
+require_relative "attribute/matcher"
+require_relative "attribute/regex"
+require_relative "attribute/resolvable_array"
+require_relative "attribute/resolvable_hash"
+require_relative "attribute/store"
+require_relative "attribute/transform"
+require_relative "attribute/variable"

data/lib/spec_forge/backtrace_formatter.rb

@@ -2,18 +2,41 @@
 
 module SpecForge
   #
-  # Used internally by RSpec
-  # This class handles formatting backtraces, hence the name ;)
+  # Used internally by RSpec to format backtraces for test failures
+  # Customizes error output to make it more readable and useful for SpecForge
   #
   module BacktraceFormatter
+    #
+    # Returns the RSpec backtrace formatter instance
+    # Lazily initializes the formatter on first access
+    #
+    # @return [RSpec::Core::BacktraceFormatter] The backtrace formatter
+    #
     def self.formatter
       @formatter ||= RSpec::Core::BacktraceFormatter.new
     end
 
+    #
+    # Formats a single backtrace line
+    # Delegates to the RSpec formatter
+    #
+    # @param line [String] The backtrace line to format
+    #
+    # @return [String] The formatted backtrace line
+    #
     def self.backtrace_line(line)
       formatter.backtrace_line(line)
     end
 
+    #
+    # Formats a complete backtrace for an example
+    # Adds the YAML location to the front of the backtrace for better context
+    #
+    # @param backtrace [Array<String>] The raw backtrace lines
+    # @param example_metadata [Hash] Metadata about the failing example
+    #
+    # @return [Array<String>] The formatted backtrace with YAML location first
+    #
     def self.format_backtrace(backtrace, example_metadata)
       backtrace = SpecForge.backtrace_cleaner.clean(backtrace)
 
@@ -21,7 +44,7 @@ module SpecForge
       line_number = example_metadata[:example_group][:line_number]
 
       # Add the yaml location to the front so it's the first thing people see
-      ["#{location}:#{line_number}"] + backtrace
+      ["#{location}:#{line_number}"] + backtrace[0..50]
     end
   end
 end