spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/error.rb

@@ -1,150 +1,304 @@
 # frozen_string_literal: true
 
 module SpecForge
-  # Pass into to_sentence
-  OR_CONNECTOR = {
-    last_word_connector: ", or ",
-    two_words_connector: " or ",
-    # This is a minor performance improvement to avoid locales being loaded
-    # This will need to be removed if locales are added
-    locale: false
-  }.freeze
-
-  private_constant :OR_CONNECTOR
-
-  class Error < StandardError; end
-
   #
-  # Raised by Attribute::Faker when a provided classname does not exist in Faker
+  # Base error class for all SpecForge-specific exceptions
   #
-  class InvalidFakerClassError < Error
-    CLASS_CHECKER = DidYouMean::SpellChecker.new(
-      dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
-    )
+  class Error < StandardError
+    # Pass into to_sentence
+    OR_CONNECTOR = {
+      last_word_connector: ", or ",
+      two_words_connector: " or ",
+      # This is a minor performance improvement to avoid locales being loaded
+      # This will need to be removed if locales are added
+      locale: false
+    }.freeze
 
-    def initialize(input)
-      corrections = CLASS_CHECKER.correct(input)
+    private_constant :OR_CONNECTOR
 
-      super(<<~STRING.chomp
-        Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
-
-        For available classes, please check https://github.com/faker-ruby/faker#generators.
-      STRING
+    #
+    # Raised when a provided Faker class name doesn't exist
+    # Provides helpful suggestions for similar class names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.invalid.method")
+    #   # => InvalidFakerClassError: Undefined Faker class "invalid". Did you mean? name, games, ...
+    #
+    class InvalidFakerClassError < Error
+      #
+      # A spell checker for Faker classes
+      #
+      # @return [DidYouMean::SpellChecker]
+      #
+      CLASS_CHECKER = DidYouMean::SpellChecker.new(
+        dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
       )
+
+      def initialize(input)
+        corrections = CLASS_CHECKER.correct(input)
+
+        super(<<~STRING.chomp
+          Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
+
+          For available classes, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Faker when a provided method for a Faker class does not exist.
-  #
-  class InvalidFakerMethodError < Error
-    def initialize(input, klass)
-      spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
-      corrections = spell_checker.correct(input)
+    #
+    # Raised when a provided method for a Faker class doesn't exist
+    # Provides helpful suggestions for similar method names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.name.invlaid")
+    #   # => InvalidFakerMethodError: Undefined Faker method "invlaid" for "Faker::Name".
+    #                                 Did you mean? first_name, last_name, ...
+    #
+    class InvalidFakerMethodError < Error
+      def initialize(input, klass)
+        spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
+        corrections = spell_checker.correct(input)
 
-      super(<<~STRING.chomp
-        Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
+        super(<<~STRING.chomp
+          Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
 
-        For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
-      STRING
-      )
+          For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Transform when the provided transform function is not valid
-  #
-  class InvalidTransformFunctionError < Error
-    def initialize(input)
-      # TODO: Update link to docs
-      super(<<~STRING.chomp
-        Undefined transform function "#{input}".
-
-        For available functions, please check https://github.com/itsthedevman/spec_forge.
-      STRING
-      )
+    #
+    # Raised when an unknown transform function is referenced
+    # Indicates when a transform name isn't supported
+    #
+    class InvalidTransformFunctionError < Error
+      def initialize(input)
+        # TODO: Update link to docs
+        super(<<~STRING.chomp
+          Undefined transform function "#{input}".
+
+          For available functions, please check https://github.com/itsthedevman/spec_forge.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Chainable when an step in the invocation chain is invalid
-  #
-  class InvalidInvocationError < Error
-    def initialize(step, object)
-      valid_operations =
-        case object
-        when ArrayLike
-          "Array index (0, 1, 2, etc.) or any Array methods (first, last, size, etc.)"
-        when HashLike
-          "Any Hash key: #{object.keys.join(", ")}"
-        else
-          "Any method available on #{object.class}"
+    #
+    # Raised when a step in an invocation chain is invalid
+    # Provides detailed information about where in the chain the error occurred
+    #
+    # @example
+    #   variable_attr = Attribute::Variable.new("variables.user.invalid_method")
+    #   variable_attr.resolved
+    #   # => InvalidInvocationError: Cannot invoke "invalid_method" on User
+    #
+    class InvalidInvocationError < Error
+      def initialize(step, object, resolution_path = {})
+        @step = step
+        @object = object
+        @resolution_path = resolution_path
+
+        object_class =
+          case object
+          when Data
+            object.class.name || "Data"
+          when Struct
+            object.class.name || "Struct"
+          else
+            object.class
+          end
+
+        super(<<~STRING.chomp
+          Cannot invoke "#{step}" on #{object_class}
+          #{resolution_path_message}
+        STRING
+        )
+      end
+
+      #
+      # Creates a new InvalidInvocationError with a new resolution path
+      #
+      # @param path [Hash] The steps taken up until this point
+      #
+      def with_resolution_path(path)
+        self.class.new(@step, @object, path)
+      end
+
+      private
+
+      def resolution_path_message
+        return "" if @resolution_path.empty?
+
+        message =
+          @resolution_path.map.with_index do |(path, description), index|
+            "#{index + 1}. #{path} --> #{description}"
+          end.join("\n")
+
+        "\nResolution path:\n#{message}"
+      end
+    end
+
+    #
+    # An extended version of TypeError with better error messages
+    # Makes it easier to understand type mismatches in the codebase
+    #
+    # @example
+    #   raise Error::InvalidTypeError.new(123, String, for: "name parameter")
+    #   # => Expected String, got Integer for name parameter
+    #
+    class InvalidTypeError < Error
+      def initialize(object, expected_type, **opts)
+        if expected_type.instance_of?(Array)
+          expected_type = expected_type.to_sentence(**OR_CONNECTOR)
         end
 
-      super(<<~STRING.chomp
-        Cannot invoke "#{step}" on #{object.class}.
+        message = "Expected #{expected_type}, got #{object.class}"
+        message += " for #{opts[:for]}" if opts[:for].present?
 
-        Valid operations include: #{valid_operations}
-      STRING
-      )
+        super(message)
+      end
     end
-  end
 
-  #
-  # An extended version of TypeError to make things easier when reporting invalid types
-  #
-  class InvalidTypeError < Error
-    def initialize(object, expected_type, **opts)
-      if expected_type.instance_of?(Array)
-        expected_type = expected_type.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when a variable reference cannot be resolved
+    # Indicates when a spec or expectation references an undefined variable
+    #
+    class MissingVariableError < Error
+      def initialize(variable_name)
+        super("Undefined variable \"#{variable_name}\" referenced in expectation")
       end
+    end
 
-      message = "Expected #{expected_type}, got #{object.class}"
-      message += " for #{opts[:for]}" if opts[:for].present?
+    #
+    # Raised when a YAML structure doesn't match expectations
+    # Acts as a container for multiple validation errors
+    #
+    class InvalidStructureError < Error
+      def initialize(errors)
+        message = errors.to_a.join_map("\n") do |error|
+          next error if error.is_a?(SpecForge::Error)
 
-      super(message)
+          # Normal errors, let's get verbose
+          backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
+          "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+        end
+
+        super(message)
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Variable when the provided variable name is not defined
-  #
-  class MissingVariableError < Error
-    def initialize(variable_name)
-      super("Undefined variable \"#{variable_name}\" referenced in expectation")
+    #
+    # Raised when an unknown factory build strategy is provided
+    # Indicates when a strategy string doesn't match supported options
+    #
+    class InvalidBuildStrategy < Error
+      def initialize(build_strategy)
+        valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+
+        super(<<~STRING.chomp
+          Unknown build strategy "#{build_strategy}" referenced in spec.
+
+          Valid strategies include: #{valid_strategies}
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Normalizer when any errors are returned. Acts like a grouping of errors
-  #
-  class InvalidStructureError < Error
-    def initialize(errors)
-      message = errors.to_a.join_map("\n") do |error|
-        next error if error.is_a?(SpecForge::Error)
-
-        # Normal errors, let's get verbose
-        backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
-        "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+    #
+    # Raised when a spec file cannot be loaded
+    # Provides detailed information about the cause of the loading error
+    #
+    class SpecLoadError < Error
+      def initialize(error, file_path, spec: nil)
+        message =
+          if spec
+            "Error loading spec #{spec[:name].in_quotes} in file #{file_path.in_quotes} (line #{spec[:line_number]})"
+          else
+            "Error loading spec file #{file_path.in_quotes}"
+          end
+
+        causes = error.message.split("\n").map(&:strip).reject(&:empty?)
+
+        message +=
+          if causes.size > 1
+            "\nCauses:\n  - #{causes.join_map("\n  - ")}"
+          else
+            "\nCause: #{error}"
+          end
+
+        super(message)
       end
+    end
 
-      super(message)
+    #
+    # Raised when the provided namespace is not defined on the global context
+    #
+    class InvalidGlobalNamespaceError < Error
+      def initialize(provided_namespace)
+        super("Invalid global namespace #{provided_namespace.in_quotes}. Currently supported namespaces are: \"variables\"")
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Factory when an unknown build strategy is provided
-  #
-  class InvalidBuildStrategy < Error
-    def initialize(build_strategy)
-      valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when the provided matcher name does not defined with RSpec
+    #
+    class UndefinedMatcherError < Error
+      def initialize(matcher_name)
+        matcher_categories = {
+          Equality: ["matcher.eq", "matcher.eql", "matcher.equal"],
+          Types: ["kind_of.string", "kind_of.integer", "kind_of.array", "kind_of.hash"],
+          Truthiness: ["be.true", "be.false", "be.nil"],
+          Comparison: ["be.within", "be.between", "be.greater_than", "be.less_than"],
+          Collections: ["matcher.include", "matcher.contain_exactly", "matcher.all"],
+          Strings: ["/regex/", "matcher.start_with", "matcher.end_with"]
+        }
 
-      super(<<~STRING.chomp
-        Unknown build strategy "#{build_strategy}" referenced in spec.
+        formatted_categories =
+          matcher_categories.join_map("\n") do |category, matchers|
+            "  #{category}: #{matchers.join(", ")}"
+          end
 
-        Valid strategies include: #{valid_strategies}
-      STRING
-      )
+        super(<<~STRING.chomp
+          Undefined matcher method "#{matcher_name}" is not available in RSpec matchers.
+
+          Common matchers you can use:
+          #{formatted_categories}
+
+          For the complete list of available matchers, check the RSpec documentation:
+          https://rspec.info/documentation/3.12/rspec-expectations/RSpec/Matchers.html
+        STRING
+        )
+      end
+    end
+
+    #
+    # Raised when a callback is referenced in config but hasn't been defined
+    #
+    class UndefinedCallbackError < Error
+      def initialize(callback_name, available_callbacks = [])
+        message = "The callback #{callback_name.in_quotes} was referenced but hasn't been defined."
+
+        message +=
+          if available_callbacks.any?
+            <<~STR.chomp
+
+              Available callbacks are: #{available_callbacks.join_map(", ", &:in_quotes)}
+            STR
+          else
+            <<~STR.chomp
+
+              No callbacks have been defined yet. Register callbacks with:
+
+                SpecForge.register_callback(:#{callback_name}) do |context|
+                  # Your callback code
+                end
+            STR
+          end
+
+        super(message)
+      end
     end
   end
 end

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,14 +22,13 @@ 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 = []
 
@@ -43,13 +47,28 @@ 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
@@ -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,87 @@
+# 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:}.reject { |k, v| v.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
+
+            expectations = spec.expectations.select { |e| e.name == expectation_name }
+            next if expectations.empty?
+
+            spec.expectations = expectations
+            spec
+          end
+
+          next if specs.empty?
+
+          forge.specs = specs
+          forge
+        end
+      end
+    end
+  end
+end