matchi 4.1.1 → 5.0.0

data/lib/matchi/raise_exception.rb

@@ -1,66 +1,101 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # *Expecting errors* matcher.
+  # 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.
+  #
+  # Every `Exception` is caught, including `SystemExit` and `Interrupt`: a
+  # specification must be able to assert on any of them, so an unexpected
+  # `exit` or Ctrl-C inside the block is reported as a failure, not
+  # propagated. The expected class can be given directly, or by name; see
+  # {Matchi::Constant}.
+  #
+  # @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 a descendant of class Exception.
-    #
-    # @example
-    #   require "matchi/raise_exception"
-    #
-    #   Matchi::RaiseException.new(NameError)
-    #
-    # @param expected [Exception, #to_s] The expected exception name.
-    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
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/raise_exception"
-    #
-    #   matcher = Matchi::RaiseException.new(NameError)
-    #   matcher.match? { Boom } # => true
-    #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
-    #
-    # @return [Boolean] Comparison between actual and expected values.
+    # @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
 
       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
+        klass === e && message?(e)
       end
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @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 Class object.
-    # This method handles both string and symbol class names through constant resolution.
-    #
-    # @return [Class] the resolved class
-    # @raise [NameError] if the class doesn't exist
+    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 valid String. 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.valid_encoding?
+
+      ::String === @message ? @message.eql?(message) : @message.match?(message)
+    rescue ::Encoding::CompatibilityError
+      false
     end
   end
 end

data/lib/matchi/satisfy.rb

@@ -1,43 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # *Satisfy* matcher.
+  # 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
+  #   Matchi::Satisfy.new { |value| value > 41 }.match? { 42 } # => true
   class Satisfy
-    # Initialize the matcher with a block.
-    #
-    # @example
-    #   require "matchi/satisfy"
-    #
-    #   Matchi::Satisfy.new { |value| value == 42 }
-    #
-    # @param block [Proc] A block of code.
+    # @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
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/satisfy"
-    #
-    #   matcher = Matchi::Satisfy.new { |value| value == 42 }
-    #   matcher.match? { 42 } # => true
-    #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
-    #
-    # @return [Boolean] Comparison between actual and expected values.
+    # @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 string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     def to_s
       "satisfy &block"
     end

data/lib/matchi.rb

@@ -1,311 +1,27 @@
 # frozen_string_literal: true
 
-# A collection of damn simple expectation matchers.
-#
-# The Matchi module provides two ways to create and use matchers:
-#
-# 1. Direct instantiation through classes:
-#    ```ruby
-#    matcher = Matchi::Eq.new("foo")
-#    matcher.match? { "foo" } # => true
-#    ```
-#
-# 2. Helper methods by including/extending the Matchi module:
-#    ```ruby
-#    # Via include in a class
-#    class MyTestFramework
-#      include Matchi
-#
-#      def test_something
-#        # Helpers are now available as instance methods
-#        matcher = eq("foo")
-#        matcher.match? { "foo" } # => true
-#
-#        # Multiple helpers can be chained
-#        change(@array, :length).by(1).match? { @array << 1 }
-#      end
-#    end
-#
-#    # Or via extend for direct usage
-#    class MyOtherFramework
-#      extend Matchi
-#
-#      def self.assert_equals(expected, actual)
-#        eq(expected).match? { actual }
-#      end
-#    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.
-#
-# 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
+# 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
-  # 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_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,16 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 5.0.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-31 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies: []
-description: "Collection of expectation matchers for Rubyists \U0001F939"
+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
 executables: []
 extensions: []
@@ -25,22 +29,25 @@ files:
 - 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
+  documentation_uri: https://rubydoc.info/gems/matchi
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/fixrb/matchi
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -49,15 +56,15 @@ 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
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: "Collection of expectation matchers for Rubyists \U0001F939"
+summary: Framework-agnostic matchers for secure Ruby testing
 test_files: []

data/lib/matchi/change/by.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # *Change by* matcher.
-    class By
-      # Initialize the matcher with an object and a block.
-      #
-      # @example
-      #   require "matchi/change/by"
-      #
-      #   object = []
-      #
-      #   Matchi::Change::By.new(1) { object.length }
-      #
-      # @param expected [#object_id]  An expected delta.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
-      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
-
-      # Boolean comparison on the expected change by comparing the value
-      # before and after the code execution.
-      #
-      # @example
-      #   require "matchi/change/by"
-      #
-      #   object = []
-      #
-      #   matcher = Matchi::Change::By.new(1) { object.length }
-      #   matcher.match? { object << "foo" } # => true
-      #
-      # @yieldreturn [#object_id] The block of code to execute.
-      #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
-      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 string representing the matcher.
-      #
-      # @return [String] a human-readable description of the matcher
-      def to_s
-        "change by #{@expected.inspect}"
-      end
-    end
-  end
-end