matchi 4.2.0 → 6.0.0

data/lib/matchi/raise_exception.rb

@@ -1,133 +1,111 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # 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
+  # Exception matcher: passes when evaluating the block raises an exception
+  # of the expected class or of one of its descendants (`Module#===`, so the
+  # exception cannot lie about its class), optionally with an expected
+  # message: a String the message must be `eql?` to, or a Regexp it must
+  # match.
   #
-  # @example With custom exception hierarchies
-  #   module Api
-  #     class Error < StandardError; end
-  #     class AuthenticationError < Error; end
-  #   end
+  # The matcher rescues an exception of the expected class, and any
+  # `StandardError`, `ScriptError`, `SystemStackError` or `SystemExit`,
+  # which it then compares with the expected class. Anything else, an
+  # `Interrupt`, a signal, a `NoMemoryError`, the exception with which an
+  # enclosing `Timeout` ends its block, goes through as it would with any
+  # other matcher, unless that is the class expected. The expected class can
+  # be given directly, or by name; see {Matchi::Constant}.
   #
-  #   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
+  # @example
+  #   Matchi::RaiseException.new(ZeroDivisionError).match? { 1 / 0 }              # => true
+  #   Matchi::RaiseException.new(:StandardError).match? { 1 / 0 }                 # => true
+  #   Matchi::RaiseException.new(ZeroDivisionError, /by 0/).match? { 1 / 0 }      # => true
+  #   Matchi::RaiseException.new(ZeroDivisionError, "nope").match? { 1 / 0 }      # => false
+  #   Matchi::RaiseException.new(IOError).match? { 1 / 0 }                        # => false
   class RaiseException
-    # Initialize the matcher with an exception class.
-    #
-    # @api public
-    #
-    # @param expected [Exception, #to_s] The expected exception class or its name
-    #   Can be provided as a Class, String, or Symbol
-    #
-    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
-    #
-    # @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)
-
-      raise ::ArgumentError,
-            "expected must start with an uppercase letter (got: #{@expected})"
+    # @param expected [Class, String, Symbol] the expected exception class, or its name
+    # @param message [String, Regexp, nil] the expected message, exact or as a pattern
+    # @raise [ArgumentError] when expected is neither an Exception class nor a constant name,
+    #   or message is neither a String nor a Regexp
+    def initialize(expected, message = nil)
+      @expected = Constant.normalize(expected, ::Class)
+      @message = message
+      validate_class!
+      validate_message!
     end
 
-    # Checks if the yielded block raises the expected 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)
-    #
-    # @return [Boolean] true if the block raises the expected exception
-    #
-    # @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
-    #
-    # @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
+    # @yieldreturn [Object] ignored, the block is evaluated for its exception
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [NameError] when the name is not defined
+    # @raise [TypeError] when the name does not resolve to an Exception class
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
+      # Resolved before the block, so that a NameError from the name is not
+      # mistaken for an exception raised by the block.
       klass = expected_class
-      raise ::ArgumentError, "expected exception class must inherit from Exception" unless klass <= ::Exception
 
+      # The expected class first, whatever it is; then what a block raises
+      # on its own, the exceptions Defi keeps too.
       begin
         yield
         false
-      rescue ::Exception => e # rubocop:disable Lint/RescueException
-        e.class <= klass
+      rescue klass => e
+        message?(e)
+      rescue ::StandardError, ::ScriptError, ::SystemStackError, ::SystemExit
+        false
       end
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   RaiseException.new(ArgumentError).to_s  # => "raise exception ArgumentError"
+    # @return [String]
     def to_s
-      "raise exception #{@expected}"
+      return "raise exception #{Constant.label(@expected)}" if @message.nil?
+
+      "raise exception #{Constant.label(@expected)} with message #{@message.inspect}"
     end
 
     private
 
-    # 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
-    #
-    # @note This method handles both string and symbol class names through constant resolution
+    def validate_class!
+      return unless ::Class === @expected
+      return if @expected <= ::Exception
+
+      raise ::ArgumentError, "expected must inherit from Exception (got: #{@expected.inspect})"
+    end
+
+    def validate_message!
+      return if @message.nil? || ::String === @message || ::Regexp === @message
+
+      raise ::ArgumentError, "message must be a String or a Regexp (got: #{@message.inspect})"
+    end
+
     def expected_class
-      ::Object.const_get(@expected)
+      return @expected if ::Class === @expected
+
+      klass = Constant.resolve(@expected, ::Class)
+      raise ::TypeError, "#{@expected} is not an Exception class" unless klass <= ::Exception
+
+      klass
+    end
+
+    # The message is whatever the exception answers to `message`, which is
+    # its own data, as with any exception; it must be a String, copied so
+    # that a subclass has no say, and valid. The expected String or Regexp
+    # receives the comparison.
+    def message?(exception)
+      return true if @message.nil?
+
+      message = exception.message
+      return false unless ::String === message
+
+      message = ::String.new(message)
+      return false unless message.valid_encoding?
+
+      ::String === @message ? @message.eql?(message) : @message.match?(message)
+    rescue ::Encoding::CompatibilityError
+      false
     end
   end
 end

data/lib/matchi/satisfy.rb

@@ -1,114 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # 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
+  # Custom matcher: passes when the given block, called with the actual value,
+  # returns `true`. The block must return `true` or `false`; any other value
+  # is an error, not a truthy pass.
   #
-  # @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
+  # @example
+  #   Matchi::Satisfy.new { |value| value > 41 }.match? { 42 } # => true
   class Satisfy
-    # Initialize the matcher with a validation block.
-    #
-    # @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
-    #
-    # @return [Satisfy] a new instance of the matcher
-    #
-    # @example Simple numeric validation
-    #   Satisfy.new { |n| n > 0 }
-    #
-    # @example Complex condition
-    #   Satisfy.new { |obj|
-    #     obj.respond_to?(:length) && obj.length.between?(2, 10)
-    #   }
+    # @yieldparam actual [Object] the actual value
+    # @yieldreturn [Boolean]
+    # @raise [ArgumentError] when no block is given
     def initialize(&block)
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected = block
+      @predicate = block
     end
 
-    # Checks if the yielded value satisfies the validation block.
-    #
-    # 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
-    #
-    # @yield [] Block that returns the value to validate
-    # @yieldreturn [Object] The value to check against the condition
-    #
-    # @return [Boolean] true if the value satisfies the condition
-    #
-    # @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
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [TypeError] when the predicate returns something other than true or false
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected.call(yield)
+      result = @predicate.call(yield)
+      return result if true.equal?(result) || false.equal?(result)
+
+      klass = ::Kernel.instance_method(:class).bind_call(result)
+      raise ::TypeError, "the block must return true or false (got a #{Constant.label(klass)})"
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Satisfy.new { |n| n > 0 }.to_s  # => "satisfy &block"
+    # @return [String]
     def to_s
       "satisfy &block"
     end

data/lib/matchi.rb

@@ -1,65 +1,27 @@
 # frozen_string_literal: true
 
-# Main namespace for the Matchi gem, providing a collection of expectation 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.
-#
-# @example Basic usage with equality matcher
-#   Matchi::Eq.new("hello").match? { "hello" }     # => true
-#   Matchi::Eq.new("hello").match? { "world" }     # => false
-#
-# @example Type checking with inheritance awareness
-#   Matchi::BeAKindOf.new(Numeric).match? { 42 }   # => true
-#   Matchi::BeAKindOf.new(String).match? { 42 }    # => false
-#
-# @example Verifying state changes
-#   array = []
-#   Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) }  # => true
-#
-# @example Pattern matching with regular expressions
-#   Matchi::Match.new(/^test/).match? { "test_string" }  # => true
-#
-# 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
-#
-# @example Creating a custom matcher
-#   module Matchi
-#     class BePositive
-#       def match?
-#         raise ArgumentError, "a block must be provided" unless block_given?
-#         yield.positive?
-#       end
-#
-#       def to_s
-#         "be positive"
-#       end
-#     end
-#   end
-#
-# @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
+# Framework-agnostic matchers for Ruby.
+#
+# A matcher is any object that responds to `match?` with a block and to
+# `to_s`. The block is evaluated once and yields the actual value, or, for
+# `Change` and `RaiseException`, produces the effect to observe; the matcher
+# returns `true` or `false`. The expected value controls the comparison
+# wherever a comparison takes place, so a hostile actual value cannot forge
+# a match; `Predicate` and the `Change` refinements by delta, which use
+# values produced by the object under test, depend on its honesty.
+#
+# @example
+#   Matchi::Eq.new(42).match? { 42 } # => true
 module Matchi
 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"
+require_relative "matchi/be"
+require_relative "matchi/be_a_kind_of"
+require_relative "matchi/be_an_instance_of"
+require_relative "matchi/be_within"
+require_relative "matchi/change"
+require_relative "matchi/eq"
+require_relative "matchi/match"
+require_relative "matchi/predicate"
+require_relative "matchi/raise_exception"
+require_relative "matchi/satisfy"

metadata

@@ -1,22 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 6.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-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.
+description: 'Matchi provides small, explicit expectation matchers for any Ruby testing
+  framework. The expected value always controls the comparison, so the object under
+  test cannot forge a match.
 
   '
 email: contact@cyril.email
@@ -31,24 +26,28 @@ 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
-- lib/matchi/change/by_at_most.rb
+- lib/matchi/change/delta.rb
 - lib/matchi/change/from.rb
-- lib/matchi/change/from/to.rb
+- lib/matchi/change/from_to.rb
 - lib/matchi/change/to.rb
+- lib/matchi/constant.rb
 - lib/matchi/eq.rb
 - lib/matchi/match.rb
+- lib/matchi/number.rb
 - lib/matchi/predicate.rb
 - lib/matchi/raise_exception.rb
 - lib/matchi/satisfy.rb
-homepage: https://github.com/fixrb/matchi
+homepage: https://fixrb.dev/gems/matchi/
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/fixrb/matchi/issues
+  changelog_uri: https://github.com/fixrb/matchi#changes-in-60
+  documentation_uri: https://rubydoc.info/gems/matchi
   rubygems_mfa_required: 'true'
-post_install_message:
+  source_code_uri: https://github.com/fixrb/matchi
 rdoc_options: []
 require_paths:
 - lib
@@ -56,15 +55,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 4.0.23
 specification_version: 4
-summary: "Framework-agnostic matchers for secure, elegant Ruby testing \U0001F939"
+summary: Framework-agnostic matchers for secure Ruby testing
 test_files: []

data/lib/matchi/change/by.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # Exact delta matcher that verifies precise numeric changes in object state.
-    #
-    # This matcher ensures that a numeric value changes by exactly the specified amount
-    # after executing a block of code. It's particularly useful for testing operations
-    # that should produce precise, predictable changes in numeric attributes, such as
-    # counters, quantities, or calculated values.
-    #
-    # @example Testing collection size changes
-    #   array = []
-    #   matcher = Matchi::Change::By.new(2) { array.size }
-    #   matcher.match? { array.concat([1, 2]) }     # => true
-    #   matcher.match? { array.push(3) }            # => false  # Changed by 1
-    #   matcher.match? { array.push(3, 4, 5) }      # => false  # Changed by 3
-    #
-    # @example Verifying numeric calculations
-    #   counter = 100
-    #   matcher = Matchi::Change::By.new(-10) { counter }
-    #   matcher.match? { counter -= 10 }            # => true
-    #   matcher.match? { counter -= 15 }            # => false  # Changed too much
-    #
-    # @example Working with custom numeric attributes
-    #   class Account
-    #     attr_reader :balance
-    #
-    #     def initialize(initial_balance)
-    #       @balance = initial_balance
-    #     end
-    #
-    #     def deposit(amount)
-    #       @balance += amount
-    #     end
-    #
-    #     def withdraw(amount)
-    #       @balance -= amount
-    #     end
-    #   end
-    #
-    #   account = Account.new(1000)
-    #   matcher = Matchi::Change::By.new(50) { account.balance }
-    #   matcher.match? { account.deposit(50) }      # => true
-    #   matcher.match? { account.deposit(75) }      # => false  # Changed by 75
-    #
-    # @example Handling floating point values
-    #   temperature = 20.0
-    #   matcher = Matchi::Change::By.new(1.5) { temperature }
-    #   matcher.match? { temperature += 1.5 }       # => true
-    #   matcher.match? { temperature += 1.6 }       # => false  # Not exact match
-    #
-    # @note This matcher checks for exact changes, use ByAtLeast or ByAtMost for
-    #   more flexible delta comparisons
-    #
-    # @see Matchi::Change::ByAtLeast For minimum change validation
-    # @see Matchi::Change::ByAtMost For maximum change validation
-    # @see Matchi::Change::From::To For exact value transition validation
-    class By
-      # Initialize the matcher with an expected delta and a state block.
-      #
-      # @api public
-      #
-      # @param expected [Numeric] The exact amount by which the value should change
-      # @param state [Proc] Block that retrieves the current value
-      #
-      # @raise [ArgumentError] if expected is not a Numeric
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [By] a new instance of the matcher
-      #
-      # @example With positive delta
-      #   By.new(5) { counter.value }
-      #
-      # @example With negative delta
-      #   By.new(-3) { stock_level.quantity }
-      #
-      # @example With floating point delta
-      #   By.new(0.5) { temperature.celsius }
-      def initialize(expected, &state)
-        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        @expected = expected
-        @state = state
-      end
-
-      # Verifies that the value changes by exactly the expected amount.
-      #
-      # This method compares the value before and after executing the provided block,
-      # ensuring that the difference matches the expected delta exactly. It's useful
-      # for cases where precision is important and approximate changes are not acceptable.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by exactly the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage
-      #   counter = 0
-      #   matcher = By.new(5) { counter }
-      #   matcher.match? { counter += 5 }  # => true
-      #
-      # @example Failed match
-      #   items = []
-      #   matcher = By.new(2) { items.size }
-      #   matcher.match? { items.push(1) }  # => false  # Changed by 1
-      def match?
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected == (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   By.new(5).to_s    # => "change by 5"
-      #   By.new(-3).to_s   # => "change by -3"
-      #   By.new(2.5).to_s  # => "change by 2.5"
-      def to_s
-        "change by #{@expected.inspect}"
-      end
-    end
-  end
-end