spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/attribute/factory.rb

@@ -2,13 +2,54 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that references a factory to generate test data
+    #
+    # This class allows SpecForge to integrate with FactoryBot for test data generation.
+    # It supports various build strategies like create, build, build_stubbed, etc.
+    #
+    # @example Basic usage in YAML
+    #   user: factories.user
+    #
+    # @example With custom attributes
+    #   user:
+    #     factories.user:
+    #       attributes:
+    #         name: "Custom Name"
+    #         email: faker.internet.email
+    #
+    # @example With build strategy
+    #   user:
+    #     factories.user:
+    #       strategy: build
+    #       attributes:
+    #         admin: true
+    #
+    # @example With an array of 5 user attributes
+    #   user:
+    #     factories.user:
+    #       strategy: attributes_for
+    #       size: 5
+    #       attributes:
+    #         admin: true
+    #
     class Factory < Parameterized
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^factories\./i
 
-      # These are the base strategies that can be provided either with or without size
-      # stubbed will be transformed into build_stubbed
+      #
+      # An array of base strategies that can be provided either with or
+      # without a size. "stubbed" will automatically be transformed into "build_stubbed"
+      #
+      # @return [Array<String>]
+      #
       BASE_STRATEGIES = %w[
         build
         create
@@ -16,7 +57,7 @@ module SpecForge
         attributes_for
       ].freeze
 
-      # All available build strategies that are accepted
+      # @return [Array<String>] All available build strategies
       BUILD_STRATEGIES = %w[
         attributes_for
         attributes_for_list
@@ -33,9 +74,7 @@ module SpecForge
       alias_method :factory_name, :header
 
       #
-      # Represents any attribute that is a factory reference
-      #
-      #   factories.<factory_name>
+      # Creates a new factory attribute with the specified name and arguments
       #
       def initialize(...)
         super
@@ -46,8 +85,11 @@ module SpecForge
         prepare_arguments!
       end
 
-      private
-
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The result of the FactoryBot call
+      #
       def base_object
         attributes = arguments[:keyword]
 
@@ -58,19 +100,49 @@ module SpecForge
         FactoryBot.public_send(*build_arguments)
       end
 
+      #
+      # Similar to #resolved but doesn't cache the result, allowing for re-resolution.
+      # Recursively calls #resolve on all nested attributes without storing results.
+      #
+      # Use this when you need to ensure fresh values each time, particularly with
+      # factories or other attributes that should generate new values on each call.
+      #
+      # @return [Object] The completely resolved value without caching
+      #
+      # @example
+      #   factory_attr = Attribute::Factory.new("factories.user")
+      #   factory_attr.resolve # => User#1 (a new user)
+      #   factory_attr.resolve # => User#2 (another new user)
+      #
+      def resolve
+        case value
+        when ArrayLike
+          value.map(&resolved_proc)
+        when HashLike
+          value.transform_values(&resolved_proc)
+        else
+          value
+        end
+      end
+
+      private
+
+      #
+      # @private
+      #
       def construct_factory_parameters(attributes)
         build_strategy, list_size = determine_build_strategy(attributes)
 
         # This is set up for the base strategies + _pair
-        # FactoryBot.create(factory_name, **attributes)
+        # FactoryBot.<build_strategy>(factory_name, **attributes)
         build_arguments = [
           build_strategy,
           factory_name,
-          **attributes[:attributes].resolve_value
+          **attributes[:attributes].resolve
         ]
 
         # Insert the list size after the strategy
-        # FactoryBot.create_list(factory_name, list_size, **attributes)
+        # FactoryBot.<build_strategy>_list(factory_name, list_size, **attributes)
         if build_strategy.end_with?("_list")
           build_arguments.insert(2, list_size)
         end
@@ -78,10 +150,13 @@ module SpecForge
         build_arguments
       end
 
+      #
+      # @private
+      #
       def determine_build_strategy(attributes)
         # Determine build strat, and unfreeze
-        build_strategy = +attributes[:build_strategy].resolve_value
-        list_size = attributes[:size].resolve_value
+        build_strategy = +attributes[:build_strategy].resolve
+        list_size = attributes[:size].resolve
 
         # stubbed => build_stubbed
         build_strategy.prepend("build_") if build_strategy.start_with?("stubbed")
@@ -94,7 +169,9 @@ module SpecForge
           build_strategy += "_list"
         end
 
-        raise InvalidBuildStrategy, build_strategy unless BUILD_STRATEGIES.include?(build_strategy)
+        if !BUILD_STRATEGIES.include?(build_strategy)
+          raise Error::InvalidBuildStrategy, build_strategy
+        end
 
         [build_strategy, list_size]
       end

data/lib/spec_forge/attribute/faker.rb

@@ -2,17 +2,44 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that generates fake data using the Faker gem
+    #
+    # This class allows SpecForge to integrate with the Faker library to generate realistic
+    # test data like names, emails, addresses, etc.
+    #
+    # @example Basic usage in YAML
+    #   name: faker.name.name
+    #   email: faker.internet.email
+    #
+    # @example With method arguments
+    #   age:
+    #     faker.number.between:
+    #       from: 18
+    #       to: 65
+    #
+    # @example Handles nested faker classes
+    #   character: faker.games.zelda.character
+    #
     class Faker < Parameterized
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^faker\./i
 
-      attr_reader :faker_class, :faker_method
+      # @return [Class] The Faker class
+      attr_reader :faker_class
+
+      # @return [Method] The Faker class method
+      attr_reader :faker_method
 
       #
-      # Represents any attribute that is a faker call
-      #
-      #   faker.<faker_class>.<faker_method>
+      # Creates a new faker attribute with the specified name and arguments
       #
       def initialize(...)
         super
@@ -22,18 +49,37 @@ module SpecForge
         prepare_arguments!
       end
 
-      private
-
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The result of the Faker call
+      #
       def base_object
         if (positional = arguments[:positional]) && positional.present?
-          faker_method.call(*positional.resolve)
+          faker_method.call(*positional.resolved)
         elsif (keyword = arguments[:keyword]) && keyword.present?
-          faker_method.call(**keyword.resolve)
+          faker_method.call(**keyword.resolved)
         else
           faker_method.call
         end
       end
 
+      private
+
+      #
+      # Extracts the Faker class and method from the input string
+      # Handles both simple cases like "faker.name.first_name" and complex
+      # nested namespaces like "faker.games.zelda.game"
+      #
+      # @return [Array<Class, Method>] A two-element array containing:
+      #   1. The resolved Faker class (e.g., Faker::Name)
+      #   2. The method object to call on that class (e.g., #first_name)
+      #
+      # @raise [Error::InvalidFakerClassError] If the specified Faker class doesn't exist
+      # @raise [Error::InvalidFakerMethodError] If the specified method doesn't exist on the class
+      #
+      # @private
+      #
       def extract_faker_call
         class_name = header.downcase.to_s
 
@@ -42,10 +88,10 @@ module SpecForge
           return resolve_faker_class_and_method(class_name, invocation_chain.shift)
         end
 
-        # Try each part of the chain as a potential class name
-        # Example: faker.games.zelda.game.underscore
         namespace = []
 
+        # Try each part of the chain as a potential class name
+        # Example: faker.games.zelda.game.underscore
         while invocation_chain.any?
           part = invocation_chain.first.downcase
           test_class_name = ([class_name] + namespace + [part]).map(&:camelize).join("::")
@@ -65,22 +111,25 @@ module SpecForge
 
         # If we get here, we consumed all parts as classes but found no method
         class_name = ([class_name] + namespace).map(&:camelize).join("::")
-        raise InvalidFakerMethodError.new(nil, "::#{class_name}".constantize)
+        raise Error::InvalidFakerMethodError.new(nil, "::#{class_name}".constantize)
       end
 
+      #
+      # @private
+      #
       def resolve_faker_class_and_method(class_name, method_name)
         # Load the class
         faker_class = begin
           "::Faker::#{class_name.camelize}".constantize
         rescue NameError
-          raise InvalidFakerClassError, class_name
+          raise Error::InvalidFakerClassError, class_name
         end
 
         # Load the method
         faker_method = begin
           faker_class.method(method_name)
         rescue NameError
-          raise InvalidFakerMethodError.new(method_name, faker_class)
+          raise Error::InvalidFakerMethodError.new(method_name, faker_class)
         end
 
         [faker_class, faker_method]

data/lib/spec_forge/attribute/global.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that references values from the global context
+    #
+    # This class allows accessing shared data defined at the global level through
+    # namespaced references. It provides access to global variables that are shared
+    # across all specs in a file, enabling consistent test data without repetition.
+    #
+    # Currently supports the "variables" namespace.
+    #
+    # @example Basic usage in YAML
+    #   # Reference a global variable in a spec
+    #   session_token: global.variables.session_token
+    #
+    #   # Using within a request body
+    #   body:
+    #     api_version: global.variables.api_version
+    #     auth_token: global.variables.auth_token
+    #
+    class Global < Attribute
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^global\./i
+
+      #
+      # An array of valid namespaces that can be access on global
+      #
+      # @return [Array<String>]
+      #
+      VALID_NAMESPACES = %w[
+        variables
+      ].freeze
+
+      #
+      # Creates a new global attribute from the input string
+      #
+      # Parses the input string to extract the namespace to validate it
+      # Conversion happens when `#value` is called
+      #
+      # @raise [Error::InvalidGlobalNamespaceError] If an unsupported namespace is referenced
+      #
+      def initialize(...)
+        super
+
+        # Check to make sure the namespace is valid
+        namespace = input.split(".").second
+
+        if !VALID_NAMESPACES.include?(namespace)
+          raise Error::InvalidGlobalNamespaceError, namespace
+        end
+      end
+
+      #
+      # Converts the global reference into an underlying attribute
+      #
+      # Parses the input and returns the corresponding attribute based on the namespace.
+      # Currently supports extracting variables from the global context.
+      #
+      # @return [Attribute] An attribute representing the referenced global value
+      #
+      def value
+        # Skip the "global" prefix
+        components = input.split(".")[1..]
+        namespace = components.first
+
+        global_context = SpecForge.context.global
+
+        case namespace
+        when "variables"
+          variable_input = components.join(".")
+          variable = Attribute::Variable.new(variable_input)
+          variable.bind_variables(global_context.variables.to_h)
+          variable
+        end
+      end
+
+      #
+      # Resolves the global reference to its actual value
+      #
+      # Delegates resolution to the underlying attribute and caches the result
+      #
+      # @return [Object] The fully resolved value from the global context
+      #
+      def resolved
+        @resolved ||= value.resolved
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/literal.rb

@@ -2,12 +2,25 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that is a literal value
+    #
+    # This is the simplest form of attribute, storing values like strings, numbers,
+    # and booleans without any processing.
+    #
+    # @example Basic usage in YAML
+    #   name: "John Doe"
+    #   age: 42
+    #   active: true
+    #
     class Literal < Attribute
+      # @return [Object] The literal value
       attr_reader :value
 
       #
-      # Represents any attribute that is a literal value.
-      # A literal value can be any value YAML value, except Array and Hash
+      # Creates a new literal attribute with the specified value
+      #
+      # @param input [Object] The value to store
       #
       def initialize(input)
         super

data/lib/spec_forge/attribute/matcher.rb

@@ -2,28 +2,65 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that uses RSpec matchers for response validation
+    #
+    # This class allows SpecForge to integrate with RSpec's powerful matchers
+    # for flexible response validation. It supports most of the built-in RSpec matchers
+    # and most custom matchers, assuming they do not require more Ruby code
+    #
+    # @example Basic matchers in YAML
+    #   be_true: be.true
+    #   include_admin:
+    #     matcher.include:
+    #     - admin
+    #
+    # @example Comparison matchers
+    #   count:
+    #     be.greater_than: 5
+    #
+    # @example Type checking
+    #   name: kind_of.string
+    #   id: kind_of.integer
+    #
     class Matcher < Parameterized
-      class Methods
+      #
+      # Helper class to access RSpec matcher methods
+      #
+      class RSpecMatchers
         include RSpec::Matchers
       end
 
-      MATCHER_METHODS = Methods.new.freeze
-      KEYWORD_REGEX = /^matcher\.|^be\.|^kind_of\./i
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^matchers?\.|^be\.|^kind_of\./i
+
+      #
+      # Instance of Methods providing access to all RSpec matchers
+      #
+      MATCHER_METHODS = RSpecMatchers.new.freeze
 
+      #
+      # Mapping of literal string values to their Ruby equivalents
+      # Used for be.nil, be.true, and be.false matchers
+      #
       LITERAL_MAPPINGS = {
         "nil" => nil,
         "true" => true,
         "false" => false
       }.freeze
 
+      #
+      # The resolved RSpec matcher method to call
+      #
       attr_reader :matcher_method
 
       #
-      # Represents any attribute that is a matcher call.
-      #
-      #   matcher.<method>
-      #   be.<method>
-      #   kind_of.<method>
+      # Creates a new matcher attribute with the specified matcher and arguments
       #
       def initialize(...)
         super
@@ -37,28 +74,87 @@ module SpecForge
           when "kind_of"
             resolve_kind_of_matcher(method)
           else
-            resolve_matcher(method)
+            resolve_base_matcher(method)
           end
 
         prepare_arguments!
+
+        # An argument can be an expanded version of something (such as matcher.include)
+        # Move it to where it belongs
+        if (keyword = arguments[:keyword]) && !Type.hash?(keyword)
+          arguments[:positional] << keyword
+          arguments[:keyword] = {}
+        end
       end
 
+      #
+      # Returns the result of applying the matcher with the given arguments
+      # Creates an RSpec matcher that can be used in expectations
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] The configured matcher
+      #
       def value
         if (positional = arguments[:positional]) && positional.present?
-          positional = positional.resolve.each do |value|
+          positional = positional.resolved.each do |value|
             value.deep_stringify_keys! if value.respond_to?(:deep_stringify_keys!)
           end
 
           matcher_method.call(*positional)
         elsif (keyword = arguments[:keyword]) && keyword.present?
-          matcher_method.call(**keyword.resolve.deep_stringify_keys)
+          matcher_method.call(**keyword.resolved.deep_stringify_keys)
         else
           matcher_method.call
         end
       end
 
+      #
+      # Ensures proper conversion of nested matcher arguments based on context
+      #
+      # This method overrides handles a special case of matchers that take arguments
+      # which themselves might need to be converted to matchers. It skips conversion
+      # for string arguments that should remain strings
+      # (like with include, start_with, and end_with) while correctly handling nested
+      # matchers and other argument types.
+      #
+      # @example Problem case handled
+      #   # In YAML:
+      #   matcher.all:
+      #     matcher.include:
+      #     - /@/  # Should become match(/@/) when used with include
+      #
+      # @example Edge case handled
+      #   # In YAML:
+      #   matcher.include: "." # Should remain a string, not eq(".")
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] The properly configured matcher
+      #   with all arguments correctly converted based on context
+      #
+      def resolve_as_matcher
+        # Argument conversion only matters for the base matchers
+        if input.start_with?("matcher")
+          block = lambda do |argument|
+            next argument unless convert_argument?(argument)
+
+            argument.resolve_as_matcher
+          end
+
+          arguments[:positional].map!(&block)
+          arguments[:keyword].transform_values!(&block)
+        end
+
+        super
+      end
+
       private
 
+      #
+      # Extracts the namespace and method name from the input string
+      # For example, "be.empty" would return ["be", "empty"]
+      #
+      # @return [Array<String, String>] The namespace and method name
+      #
+      # @private
+      #
       def extract_namespace_and_method
         sections = input.split(".", 2)
 
@@ -69,10 +165,51 @@ module SpecForge
         end
       end
 
+      #
+      # Resolves a matcher with the "matcher" prefix
+      #
+      # @param method [String] The method part after "matcher."
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
+      def resolve_base_matcher(method)
+        if method == "and"
+          resolve_matcher("forge_and")
+        else
+          resolve_matcher(method)
+        end
+      end
+
+      #
+      # Resolves a matcher method by name from the given namespace
+      #
+      # @param method_name [String, Symbol] The matcher method name
+      # @param namespace [Object] The object to resolve the method from
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_matcher(method_name, namespace: MATCHER_METHODS)
+        if !namespace.respond_to?(method_name)
+          raise Error::UndefinedMatcherError, method_name
+        end
+
         namespace.public_method(method_name)
       end
 
+      #
+      # Resolves a matcher with the "be" prefix
+      # Handles special cases like be.true, be.nil, comparison operators, etc.
+      #
+      # @param method [String] The method part after "be."
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_be_matcher(method)
         # Resolve any custom matchers
         resolved_matcher =
@@ -107,12 +244,50 @@ module SpecForge
         resolve_matcher(:"be_#{method}")
       end
 
+      #
+      # Resolves a kind_of matcher for the given type
+      # For example, kind_of.string would check if an object is a String
+      #
+      # @param method [String] The type name to check for
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_kind_of_matcher(method)
         type_class = Object.const_get(method.capitalize)
         arguments[:positional].insert(0, type_class)
 
         resolve_matcher(:be_kind_of)
       end
+
+      #
+      # Determines whether an argument should skip conversion to a matcher
+      #
+      # This helper method handles the case where string arguments to certain matchers
+      # (include, start_with, end_with) should remain as strings rather than being
+      # converted to eq() matchers.
+      #
+      # @param argument [Object] The argument to analyze
+      #
+      # @return [Boolean] true if the argument should skip conversion, false otherwise
+      #
+      # @example Skip conversion
+      #   skip_argument_conversion?(Attribute::Literal.new(".")) #=> true
+      #   # When used with include, start_with, or end_with
+      #
+      # @example Apply conversion
+      #   skip_argument_conversion?(Attribute::Regex.new("/@/")) #=> false
+      #   # Regex should be converted to match(/@/)
+      #
+      def convert_argument?(argument)
+        return true if argument.is_a?(Attribute::Matcher) || argument.is_a?(Attribute::Regex)
+
+        return true unless [:include, :start_with, :end_with].include?(matcher_method.name)
+
+        resolved = argument.resolved
+        resolved.is_a?(Array) || resolved.is_a?(Hash)
+      end
     end
   end
 end