matchi 4.1.1 → 4.2.0

data/lib/matchi/raise_exception.rb

@@ -1,16 +1,59 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Expecting errors* matcher.
+  # Exception matcher that verifies if a block of code raises a specific exception.
+  #
+  # This matcher ensures that code raises an expected exception by executing it within
+  # a controlled environment. It supports matching against specific exception classes
+  # and their subclasses, providing a reliable way to test error handling.
+  #
+  # @example Basic usage with standard exceptions
+  #   matcher = Matchi::RaiseException.new(ArgumentError)
+  #   matcher.match? { raise ArgumentError }    # => true
+  #   matcher.match? { raise RuntimeError }     # => false
+  #   matcher.match? { "no error" }             # => false
+  #
+  # @example Working with inheritance hierarchy
+  #   class CustomError < StandardError; end
+  #   class SpecificError < CustomError; end
+  #
+  #   matcher = Matchi::RaiseException.new(CustomError)
+  #   matcher.match? { raise CustomError }      # => true
+  #   matcher.match? { raise SpecificError }    # => true
+  #   matcher.match? { raise StandardError }    # => false
+  #
+  # @example Using string class names
+  #   matcher = Matchi::RaiseException.new("ArgumentError")
+  #   matcher.match? { raise ArgumentError }    # => true
+  #
+  # @example With custom exception hierarchies
+  #   module Api
+  #     class Error < StandardError; end
+  #     class AuthenticationError < Error; end
+  #   end
+  #
+  #   matcher = Matchi::RaiseException.new("Api::Error")
+  #   matcher.match? { raise Api::AuthenticationError } # => true
+  #
+  # @see https://ruby-doc.org/core/Exception.html
+  # @see https://ruby-doc.org/core/StandardError.html
   class RaiseException
-    # Initialize the matcher with a descendant of class Exception.
+    # Initialize the matcher with an exception class.
     #
-    # @example
-    #   require "matchi/raise_exception"
+    # @api public
+    #
+    # @param expected [Exception, #to_s] The expected exception class or its name
+    #   Can be provided as a Class, String, or Symbol
     #
-    #   Matchi::RaiseException.new(NameError)
+    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
     #
-    # @param expected [Exception, #to_s] The expected exception name.
+    # @return [RaiseException] a new instance of the matcher
+    #
+    # @example
+    #   RaiseException.new(ArgumentError)         # Using class
+    #   RaiseException.new("ArgumentError")       # Using string
+    #   RaiseException.new(:ArgumentError)        # Using symbol
+    #   RaiseException.new("Api::CustomError")    # Using namespaced class
     def initialize(expected)
       @expected = String(expected)
       return if /\A[A-Z]/.match?(@expected)
@@ -19,18 +62,34 @@ module Matchi
             "expected must start with an uppercase letter (got: #{@expected})"
     end
 
-    # Boolean comparison between the actual value and the expected value.
+    # Checks if the yielded block raises the expected exception.
     #
-    # @example
-    #   require "matchi/raise_exception"
+    # This method executes the provided block within a begin/rescue clause and verifies
+    # that it raises an exception of the expected type. It also handles inheritance,
+    # allowing subclasses of the expected exception to match.
+    #
+    # @api public
+    #
+    # @yield [] Block that should raise an exception
+    # @yieldreturn [Object] The result of the block (if it doesn't raise)
     #
-    #   matcher = Matchi::RaiseException.new(NameError)
-    #   matcher.match? { Boom } # => true
+    # @return [Boolean] true if the block raises the expected exception
     #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
+    # @raise [ArgumentError] if no block is provided
+    # @raise [ArgumentError] if expected exception class doesn't inherit from Exception
+    # @raise [NameError] if the expected exception class cannot be found
     #
-    # @return [Boolean] Comparison between actual and expected values.
+    # @example Standard usage
+    #   matcher = RaiseException.new(ArgumentError)
+    #   matcher.match? { raise ArgumentError }     # => true
+    #
+    # @example With inheritance
+    #   matcher = RaiseException.new(StandardError)
+    #   matcher.match? { raise ArgumentError }     # => true
+    #
+    # @example Without exception
+    #   matcher = RaiseException.new(StandardError)
+    #   matcher.match? { "no error" }             # => false
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -40,25 +99,33 @@ module Matchi
       begin
         yield
         false
-      rescue Exception => e # rubocop:disable Lint/RescueException
-        e.class <= klass # Checks if the class of the thrown exception is klass or one of its subclasses
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        e.class <= klass
       end
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
+    #
+    # @return [String] A string describing what this matcher verifies
     #
-    # @return [String] a human-readable description of the matcher
+    # @example
+    #   RaiseException.new(ArgumentError).to_s  # => "raise exception ArgumentError"
     def to_s
       "raise exception #{@expected}"
     end
 
     private
 
-    # Resolves the expected class name to an actual Class object.
-    # This method handles both string and symbol class names through constant resolution.
+    # Resolves the expected class name to an actual Exception class.
+    #
+    # @api private
+    #
+    # @return [Class] The resolved exception class
+    # @raise [NameError] If the class name cannot be resolved to an actual class
     #
-    # @return [Class] the resolved class
-    # @raise [NameError] if the class doesn't exist
+    # @note This method handles both string and symbol class names through constant resolution
     def expected_class
       ::Object.const_get(@expected)
     end

data/lib/matchi/satisfy.rb

@@ -1,43 +1,114 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Satisfy* matcher.
+  # Custom predicate matcher that validates values against an arbitrary condition.
+  #
+  # This matcher provides a flexible way to test values against custom conditions
+  # defined in a block. Unlike specific matchers that test for predetermined
+  # conditions, Satisfy allows you to define any custom validation logic at runtime.
+  # This makes it particularly useful for complex or composite conditions that
+  # aren't covered by other matchers.
+  #
+  # @example Basic numeric validation
+  #   matcher = Matchi::Satisfy.new { |n| n.positive? && n.even? }
+  #   matcher.match? { 2 }             # => true
+  #   matcher.match? { -2 }            # => false
+  #   matcher.match? { 3 }             # => false
+  #
+  # @example String pattern validation
+  #   matcher = Matchi::Satisfy.new { |s| s.start_with?("test") && s.length < 10 }
+  #   matcher.match? { "test_123" }    # => true
+  #   matcher.match? { "test_12345" }  # => false
+  #   matcher.match? { "other" }       # => false
+  #
+  # @example Complex object validation
+  #   class User
+  #     attr_reader :age, :name
+  #     def initialize(name, age)
+  #       @name, @age = name, age
+  #     end
+  #   end
+  #
+  #   matcher = Matchi::Satisfy.new { |user|
+  #     user.age >= 18 && user.name.length >= 2
+  #   }
+  #   matcher.match? { User.new("Alice", 25) }  # => true
+  #   matcher.match? { User.new("B", 20) }      # => false
+  #
+  # @example Using with collections
+  #   matcher = Matchi::Satisfy.new { |arr|
+  #     arr.all? { |x| x.is_a?(Integer) } && arr.sum.even?
+  #   }
+  #   matcher.match? { [2, 4, 6] }      # => true
+  #   matcher.match? { [1, 3, 5] }      # => false
+  #   matcher.match? { [1, "2", 3] }    # => false
+  #
+  # @see https://ruby-doc.org/core/Proc.html
+  # @see Matchi::Predicate  For testing existing predicate methods
   class Satisfy
-    # Initialize the matcher with a block.
+    # Initialize the matcher with a validation block.
     #
-    # @example
-    #   require "matchi/satisfy"
+    # @api public
+    #
+    # @yield [Object] Block that defines the validation condition
+    # @yieldparam value The value to validate
+    # @yieldreturn [Boolean] true if the value meets the condition
+    #
+    # @raise [ArgumentError] if no block is provided
     #
-    #   Matchi::Satisfy.new { |value| value == 42 }
+    # @return [Satisfy] a new instance of the matcher
     #
-    # @param block [Proc] A block of code.
+    # @example Simple numeric validation
+    #   Satisfy.new { |n| n > 0 }
+    #
+    # @example Complex condition
+    #   Satisfy.new { |obj|
+    #     obj.respond_to?(:length) && obj.length.between?(2, 10)
+    #   }
     def initialize(&block)
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       @expected = block
     end
 
-    # Boolean comparison between the actual value and the expected value.
+    # Checks if the yielded value satisfies the validation block.
     #
-    # @example
-    #   require "matchi/satisfy"
+    # This method passes the value returned by the provided block to the
+    # validation block defined at initialization. The matcher succeeds if
+    # the validation block returns a truthy value.
+    #
+    # @api public
     #
-    #   matcher = Matchi::Satisfy.new { |value| value == 42 }
-    #   matcher.match? { 42 } # => true
+    # @yield [] Block that returns the value to validate
+    # @yieldreturn [Object] The value to check against the condition
     #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
+    # @return [Boolean] true if the value satisfies the condition
     #
-    # @return [Boolean] Comparison between actual and expected values.
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Using with direct values
+    #   matcher = Satisfy.new { |n| n.positive? }
+    #   matcher.match? { 42 }    # => true
+    #   matcher.match? { -1 }    # => false
+    #
+    # @example Using with computed values
+    #   matcher = Satisfy.new { |s| s.length.even? }
+    #   matcher.match? { "test".upcase }  # => true
+    #   matcher.match? { "a" * 3 }        # => false
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       @expected.call(yield)
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
     #
-    # @return [String] a human-readable description of the matcher
+    # @return [String] A string describing what this matcher verifies
+    #
+    # @example
+    #   Satisfy.new { |n| n > 0 }.to_s  # => "satisfy &block"
     def to_s
       "satisfy &block"
     end

data/lib/matchi.rb

@@ -1,311 +1,65 @@
 # frozen_string_literal: true
 
-# A collection of damn simple expectation matchers.
+# Main namespace for the Matchi gem, providing a collection of expectation matchers.
 #
-# The Matchi module provides two ways to create and use matchers:
+# Matchi is a framework-agnostic Ruby library that offers a comprehensive set of
+# matchers for testing and verification purposes. Each matcher follows a consistent
+# interface pattern, making them easy to use and extend.
 #
-# 1. Direct instantiation through classes:
-#    ```ruby
-#    matcher = Matchi::Eq.new("foo")
-#    matcher.match? { "foo" } # => true
-#    ```
+# @example Basic usage with equality matcher
+#   Matchi::Eq.new("hello").match? { "hello" }     # => true
+#   Matchi::Eq.new("hello").match? { "world" }     # => false
 #
-# 2. Helper methods by including/extending the Matchi module:
-#    ```ruby
-#    # Via include in a class
-#    class MyTestFramework
-#      include Matchi
+# @example Type checking with inheritance awareness
+#   Matchi::BeAKindOf.new(Numeric).match? { 42 }   # => true
+#   Matchi::BeAKindOf.new(String).match? { 42 }    # => false
 #
-#      def test_something
-#        # Helpers are now available as instance methods
-#        matcher = eq("foo")
-#        matcher.match? { "foo" } # => true
+# @example Verifying state changes
+#   array = []
+#   Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) }  # => true
 #
-#        # Multiple helpers can be chained
-#        change(@array, :length).by(1).match? { @array << 1 }
-#      end
-#    end
+# @example Pattern matching with regular expressions
+#   Matchi::Match.new(/^test/).match? { "test_string" }  # => true
 #
-#    # Or via extend for direct usage
-#    class MyOtherFramework
-#      extend Matchi
+# Each matcher in the Matchi ecosystem implements a consistent interface:
+# - An initializer that sets up the expected values or conditions
+# - A #match? method that takes a block and returns a boolean
+# - An optional #to_s method that provides a human-readable description
 #
-#      def self.assert_equals(expected, actual)
-#        eq(expected).match? { actual }
-#      end
-#    end
-#    ```
+# @example Creating a custom matcher
+#   module Matchi
+#     class BePositive
+#       def match?
+#         raise ArgumentError, "a block must be provided" unless block_given?
+#         yield.positive?
+#       end
 #
-# The helper method approach provides a more readable and fluent interface,
-# making tests easier to write and understand. It's particularly useful when
-# integrating with testing frameworks or creating custom assertions.
+#       def to_s
+#         "be positive"
+#       end
+#     end
+#   end
 #
-# Available helpers include:
-#   - eq/eql    : Equivalence matching
-#   - be/equal  : Identity matching
-#   - be_within : Delta comparison
-#   - match     : Regular expression matching
-#   - change    : State change verification
-#   - be_true/be_false/be_nil : State verification
-#   - be_an_instance_of : Exact type matching
-#   - be_a_kind_of     : Type hierarchy matching
-#   - satisfy   : Custom block-based matching
-#   - be_* & have_* : Dynamic predicate matching
-#
-# @api public
+# @see Matchi::Be
+# @see Matchi::BeAKindOf
+# @see Matchi::BeAnInstanceOf
+# @see Matchi::BeWithin
+# @see Matchi::Change
+# @see Matchi::Eq
+# @see Matchi::Match
+# @see Matchi::Predicate
+# @see Matchi::RaiseException
+# @see Matchi::Satisfy
 module Matchi
-  # Equivalence matcher
-  #
-  # @example
-  #   matcher = eq("foo")
-  #   matcher.match? { "foo" } # => true
-  #   matcher.match? { "bar" } # => false
-  #
-  # @param expected [#eql?] An expected equivalent object.
-  #
-  # @return [#match?] An equivalence matcher.
-  #
-  # @api public
-  def eq(expected)
-    ::Matchi::Eq.new(expected)
-  end
-
-  alias eql eq
-
-  # Identity matcher
-  #
-  # @example
-  #   object = "foo"
-  #   matcher = be(object)
-  #   matcher.match? { object } # => true
-  #   matcher.match? { "foo" } # => false
-  #
-  # @param expected [#equal?] The expected identical object.
-  #
-  # @return [#match?] An identity matcher.
-  #
-  # @api public
-  def be(expected)
-    ::Matchi::Be.new(expected)
-  end
-
-  alias equal be
-
-  # Comparisons matcher
-  #
-  # @example
-  #   matcher = be_within(1).of(41)
-  #   matcher.match? { 42 } # => true
-  #   matcher.match? { 43 } # => false
-  #
-  # @param delta [Numeric] A numeric value.
-  #
-  # @return [#match?] A comparison matcher.
-  #
-  # @api public
-  def be_within(delta)
-    ::Matchi::BeWithin.new(delta)
-  end
-
-  # Regular expressions matcher
-  #
-  # @example
-  #   matcher = match(/^foo$/)
-  #   matcher.match? { "foo" } # => true
-  #   matcher.match? { "bar" } # => false
-  #
-  # @param expected [#match] A regular expression.
-  #
-  # @return [#match?] A regular expression matcher.
-  #
-  # @api public
-  def match(expected)
-    ::Matchi::Match.new(expected)
-  end
-
-  # Expecting errors matcher
-  #
-  # @example
-  #   matcher = raise_exception(NameError)
-  #   matcher.match? { Boom } # => true
-  #   matcher.match? { true } # => false
-  #
-  # @param expected [Exception, #to_s] The expected exception name.
-  #
-  # @return [#match?] An error matcher.
-  #
-  # @api public
-  def raise_exception(expected)
-    ::Matchi::RaiseException.new(expected)
-  end
-
-  # True matcher
-  #
-  # @example
-  #   matcher = be_true
-  #   matcher.match? { true } # => true
-  #   matcher.match? { false } # => false
-  #   matcher.match? { nil } # => false
-  #   matcher.match? { 4 } # => false
-  #
-  # @return [#match?] A `true` matcher.
-  #
-  # @api public
-  def be_true
-    be(true)
-  end
-
-  # False matcher
-  #
-  # @example
-  #   matcher = be_false
-  #   matcher.match? { false } # => true
-  #   matcher.match? { true } # => false
-  #   matcher.match? { nil } # => false
-  #   matcher.match? { 4 } # => false
-  #
-  # @return [#match?] A `false` matcher.
-  #
-  # @api public
-  def be_false
-    be(false)
-  end
-
-  # Nil matcher
-  #
-  # @example
-  #   matcher = be_nil
-  #   matcher.match? { nil } # => true
-  #   matcher.match? { false } # => false
-  #   matcher.match? { true } # => false
-  #   matcher.match? { 4 } # => false
-  #
-  # @return [#match?] A `nil` matcher.
-  #
-  # @api public
-  def be_nil
-    be(nil)
-  end
-
-  # Type/class matcher
-  #
-  # Verifies exact class matching (no inheritance).
-  #
-  # @example
-  #   matcher = be_an_instance_of(String)
-  #   matcher.match? { "foo" }  # => true
-  #   matcher.match? { 4 }      # => false
-  #
-  # @param expected [Class, #to_s] The expected class name.
-  #
-  # @return [#match?] A type/class matcher.
-  #
-  # @api public
-  def be_an_instance_of(expected)
-    ::Matchi::BeAnInstanceOf.new(expected)
-  end
-
-  # Type/class matcher
-  #
-  # Verifies class inheritance and module inclusion.
-  #
-  # @example
-  #   matcher = be_a_kind_of(Numeric)
-  #   matcher.match? { 42 }   # => true (Integer inherits from Numeric)
-  #   matcher.match? { 42.0 } # => true (Float inherits from Numeric)
-  #
-  # @param expected [Class, #to_s] The expected class name.
-  #
-  # @return [#match?] A type/class matcher.
-  #
-  # @api public
-  def be_a_kind_of(expected)
-    ::Matchi::BeAKindOf.new(expected)
-  end
-
-  # Change matcher
-  #
-  # @example
-  #   object = []
-  #   matcher = change(object, :length).by(1)
-  #   matcher.match? { object << 1 } # => true
-  #
-  #   object = []
-  #   matcher = change(object, :length).by_at_least(1)
-  #   matcher.match? { object << 1 } # => true
-  #
-  #   object = []
-  #   matcher = change(object, :length).by_at_most(1)
-  #   matcher.match? { object << 1 } # => true
-  #
-  #   object = "foo"
-  #   matcher = change(object, :to_s).from("foo").to("FOO")
-  #   matcher.match? { object.upcase! } # => true
-  #
-  #   object = "foo"
-  #   matcher = change(object, :to_s).to("FOO")
-  #   matcher.match? { object.upcase! } # => true
-  #
-  # @param object [#object_id]  An object.
-  # @param method [Symbol]      The name of a method.
-  #
-  # @return [#match?] A change matcher.
-  #
-  # @api public
-  def change(object, method, ...)
-    ::Matchi::Change.new(object, method, ...)
-  end
-
-  # Satisfy matcher
-  #
-  # @example
-  #   matcher = satisfy { |value| value == 42 }
-  #   matcher.match? { 42 } # => true
-  #
-  # @yield [value] A block that defines the satisfaction criteria
-  # @yieldparam value The value to test
-  # @yieldreturn [Boolean] true if the value satisfies the criteria
-  #
-  # @return [#match?] A satisfy matcher.
-  #
-  # @api public
-  def satisfy(&)
-    ::Matchi::Satisfy.new(&)
-  end
-
-  private
-
-  # Predicate matcher, or default method missing behavior.
-  #
-  # @example Empty predicate matcher
-  #   matcher = be_empty
-  #   matcher.match? { [] } # => true
-  #   matcher.match? { [4] } # => false
-  def method_missing(name, ...)
-    return super unless predicate_matcher_name?(name)
-
-    ::Matchi::Predicate.new(name, ...)
-  end
-
-  # :nocov:
-
-  # Hook method to return whether the obj can respond to id method or not.
-  def respond_to_missing?(name, include_private = false)
-    predicate_matcher_name?(name) || super
-  end
-
-  # :nocov:
-
-  # Predicate matcher name detector.
-  #
-  # @param name [Array, Symbol] The name of a potential predicate matcher.
-  #
-  # @return [Boolean] Indicates if it is a predicate matcher name or not.
-  def predicate_matcher_name?(name)
-    name.start_with?("be_", "have_") && !name.end_with?("!", "?")
-  end
 end
 
-Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].each do |fname|
-  require_relative fname
-end
+require "matchi/be"
+require "matchi/be_a_kind_of"
+require "matchi/be_an_instance_of"
+require "matchi/be_within"
+require "matchi/change"
+require "matchi/eq"
+require "matchi/match"
+require "matchi/predicate"
+require "matchi/raise_exception"
+require "matchi/satisfy"

metadata

@@ -1,16 +1,24 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 4.2.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-31 00:00:00.000000000 Z
+date: 2025-01-05 00:00:00.000000000 Z
 dependencies: []
-description: "Collection of expectation matchers for Rubyists \U0001F939"
+description: 'Matchi is a framework-agnostic Ruby library that provides a comprehensive
+  set of expectation matchers for elegant and secure testing. Its design focuses on
+  simplicity, security, and extensibility, making it easy to integrate with any testing
+  framework. The library offers a rich collection of built-in matchers for common
+  testing scenarios while maintaining a clear, consistent API that follows Ruby best
+  practices. With minimal setup required and support for custom matchers, Matchi enables
+  developers to write more reliable and maintainable tests.
+
+  '
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -23,7 +31,6 @@ files:
 - lib/matchi/be_a_kind_of.rb
 - lib/matchi/be_an_instance_of.rb
 - lib/matchi/be_within.rb
-- lib/matchi/be_within/of.rb
 - lib/matchi/change.rb
 - lib/matchi/change/by.rb
 - lib/matchi/change/by_at_least.rb
@@ -59,5 +66,5 @@ requirements: []
 rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
-summary: "Collection of expectation matchers for Rubyists \U0001F939"
+summary: "Framework-agnostic matchers for secure, elegant Ruby testing \U0001F939"
 test_files: []