matchi 3.3.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b329fa6d8f4acd083fa33dc5a875ab30d521ad598a9a98d87e2e9fa0f3a4ea9
-  data.tar.gz: 122df6c5b532ae6ce316108ac76b32b5528dde249318c45272793df55a6bf240
+  metadata.gz: e8454c54085d68ded31ba34e1ff0ab03cdc3dab452316ef82a15967f3de3ee4c
+  data.tar.gz: ac11c5ab16b7e93f16189b1fa62f0d0502e0d94e67627f81dfab40cd7db48d61
 SHA512:
-  metadata.gz: 61dc6797282ee0c2643e57a259b45d0f3b857cc0c725bd55adc1de4fddce61d7822bb25a6dc5bfac30b160c1130a7f76d6b0912a960d8ca930c7485fbfcb84bc
-  data.tar.gz: 40d1d11e0b104d82bd30198de0eb1dba07f0a4fcc725f6936f8ccbec47276e2cbf91e67f4f57065f79e43dcb46b623ea4c5a085c37ac0d70b7516baad3e0d5f7
+  metadata.gz: b984f3a46f4eb2f0743b4407518261ca0539efd780b28ab0b0f476a687925bedeec2d88249160d7c148617809080593d9472957dc8571bf92295007dfaf941b7
+  data.tar.gz: 96f609b1bc8af4ddf6a5b7b839ed0b981018d7aac53f1d26b5ea05c1629318f3cdbef64e9776dd2224c3fdd48b56e148e8e3a94df4de5d07e93164941da0fa25

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2022 Cyril Kato
+Copyright (c) 2015-2024 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,12 +1,13 @@
 # Matchi
 
-[![Version](https://img.shields.io/github/v/tag/fixrb/matchi?label=Version&logo=github)](https://github.com/fixrb/matchi/releases)
+[![Version](https://img.shields.io/github/v/tag/fixrb/matchi?label=Version&logo=github)](https://github.com/fixrb/matchi/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/matchi/main)
-[![CI](https://github.com/fixrb/matchi/workflows/CI/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Aci+branch%3Amain)
+[![Ruby](https://github.com/fixrb/matchi/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Aruby+branch%3Amain)
 [![RuboCop](https://github.com/fixrb/matchi/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/matchi?label=License&logo=github)](https://github.com/fixrb/matchi/raw/main/LICENSE.md)
 
-> Collection of expectation matchers for Rubyists 🤹
+This library provides a comprehensive set of matchers for testing different aspects of your code.
+Each matcher is designed to handle specific verification needs while maintaining a clear and expressive syntax.
 
 ![A Rubyist juggling between Matchi letters](https://github.com/fixrb/matchi/raw/main/img/matchi.png)
 
@@ -27,7 +28,7 @@ gem "matchi"
 And then execute:
 
 ```sh
-bundle
+bundle install
 ```
 
 Or install it yourself as:
@@ -52,148 +53,160 @@ All examples here assume that this has been done.
 
 ### Anatomy of a matcher
 
-A __Matchi__ matcher is an object that must respond to the `matches?` method with a block as argument, and return a boolean.
+A **Matchi** matcher is a simple Ruby object that follows these requirements:
 
-To facilitate the integration of the matchers in other tools, __Matchi__ matchers may expose expected values via the `expected` method.
+1. It must implement a `match?` method that:
+   - Accepts a block as its only parameter
+   - Executes that block to get the actual value
+   - Returns a boolean indicating if the actual value matches the expected criteria
+
+2. Optionally, it may implement:
+   - `to_s`: Returns a human-readable description of the match criteria
 
 ### Built-in matchers
 
-Here is the collection of useful generic matchers.
+Here is the collection of generic matchers.
 
-**Equivalence** matcher:
+#### Basic Comparison Matchers
 
+##### `Be`
+Checks for object identity using Ruby's `equal?` method.
 ```ruby
-matcher = Matchi::Eq.new("foo")
-
-matcher.expected           # => "foo"
-matcher.matches? { "foo" } # => true
+Matchi::Be.new(:foo).match? { :foo }  # => true (same object)
+Matchi::Be.new("test").match? { "test" }  # => false (different objects)
 ```
 
-**Identity** matcher:
-
+##### `Eq`
+Verifies object equivalence using Ruby's `eql?` method.
 ```ruby
-matcher = Matchi::Be.new(:foo)
-
-matcher.expected          # => :foo
-matcher.matches? { :foo } # => true
+Matchi::Eq.new("foo").match? { "foo" }  # => true (equivalent content)
+Matchi::Eq.new([1, 2]).match? { [1, 2] }  # => true (equivalent arrays)
 ```
 
-**Comparisons** matcher:
+#### Type and Class Matchers
 
+##### `BeAnInstanceOf`
+Verifies exact class matching (no inheritance).
 ```ruby
-matcher = Matchi::BeWithin.new(8).of(37)
-
-matcher.expected        # => 37
-matcher.matches? { 42 } # => true
+Matchi::BeAnInstanceOf.new(String).match? { "test" }  # => true
+Matchi::BeAnInstanceOf.new(Integer).match? { 42 }     # => true
+Matchi::BeAnInstanceOf.new(Numeric).match? { 42 }     # => false (Integer, not Numeric)
 ```
 
-**Regular expressions** matcher:
-
+##### `BeAKindOf`
+Verifies class inheritance and module inclusion.
 ```ruby
-matcher = Matchi::Match.new(/^foo$/)
-
-matcher.expected           # => /^foo$/
-matcher.matches? { "foo" } # => true
+Matchi::BeAKindOf.new(Numeric).match? { 42 }    # => true (Integer inherits from Numeric)
+Matchi::BeAKindOf.new(Numeric).match? { 42.0 }  # => true (Float inherits from Numeric)
 ```
 
-**Expecting errors** matcher:
+#### Pattern Matchers
 
+##### `Match`
+Tests string patterns against regular expressions.
 ```ruby
-matcher = Matchi::RaiseException.new(:NameError)
-
-matcher.expected          # => "NameError"
-matcher.matches? { Boom } # => true
+Matchi::Match.new(/^foo/).match? { "foobar" }  # => true
+Matchi::Match.new(/\d+/).match? { "abc123" }   # => true
+Matchi::Match.new(/^foo/).match? { "barfoo" }  # => false
 ```
 
-**Type/class** matcher:
-
+##### `Satisfy`
+Provides custom matching through a block.
 ```ruby
-matcher = Matchi::BeAnInstanceOf.new(:String)
-
-matcher.expected           # => "String"
-matcher.matches? { "foo" } # => true
+Matchi::Satisfy.new { |x| x > 0 && x < 10 }.match? { 5 }  # => true
+Matchi::Satisfy.new { |x| x.start_with?("test") }.match? { "test_file" }  # => true
 ```
 
-**Predicate** matcher:
-
-```ruby
-matcher = Matchi::Predicate.new(:be_empty)
+#### State Change Matchers
 
-matcher.expected        # => [:empty?, [], {}, nil]
-matcher.matches? { [] } # => true
+##### `Change`
+Verifies state changes in objects with multiple variation methods:
 
-matcher = Matchi::Predicate.new(:have_key, :foo)
-
-matcher.expected                 # => [:has_key?, [:foo], {}, nil]
-matcher.matches? { { foo: 42 } } # => true
+###### Basic Change
+```ruby
+array = []
+Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) }  # => true
 ```
 
-**Change** matcher:
-
+###### Minimum Change
 ```ruby
-object = []
-matcher = Matchi::Change.new(object, :length).by(1)
-
-matcher.expected                 # => 1
-matcher.matches? { object << 1 } # => true
-
-object = []
-matcher = Matchi::Change.new(object, :length).by_at_least(1)
+counter = 0
+Matchi::Change.new(counter, :to_i).by_at_least(2).match? { counter += 3 }  # => true
+```
 
-matcher.expected                 # => 1
-matcher.matches? { object << 1 } # => true
+###### Maximum Change
+```ruby
+value = 10
+Matchi::Change.new(value, :to_i).by_at_most(5).match? { value += 3 }  # => true
+```
 
-object = []
-matcher = Matchi::Change.new(object, :length).by_at_most(1)
+###### From-To Change
+```ruby
+string = "hello"
+Matchi::Change.new(string, :upcase).from("hello").to("HELLO").match? { string.upcase! }  # => true
+```
 
-matcher.expected                 # => 1
-matcher.matches? { object << 1 } # => true
+###### To-Only Change
+```ruby
+number = 1
+Matchi::Change.new(number, :to_i).to(5).match? { number = 5 }  # => true
+```
 
-object = "foo"
-matcher = Matchi::Change.new(object, :to_s).from("foo").to("FOO")
+#### Numeric Matchers
 
-matcher.expected                    # => "FOO"
-matcher.matches? { object.upcase! } # => true
+##### `BeWithin`
+Checks if a number is within a specified range of an expected value.
+```ruby
+Matchi::BeWithin.new(0.5).of(3.0).match? { 3.2 }  # => true
+Matchi::BeWithin.new(5).of(100).match? { 98 }     # => true
+```
 
-object = "foo"
-matcher = Matchi::Change.new(object, :to_s).to("FOO")
+#### Behavior Matchers
 
-matcher.expected                    # => "FOO"
-matcher.matches? { object.upcase! } # => true
+##### `RaiseException`
+Verifies that code raises specific exceptions.
+```ruby
+Matchi::RaiseException.new(ArgumentError).match? { raise ArgumentError }  # => true
+Matchi::RaiseException.new(NameError).match? { undefined_variable }      # => true
 ```
 
-**Satisfy** matcher:
+##### `Predicate`
+Creates matchers for methods ending in `?`.
 
+###### Using `be_` prefix
 ```ruby
-matcher = Matchi::Satisfy.new { |value| value == 42 }
+Matchi::Predicate.new(:be_empty).match? { [] }  # => true (calls empty?)
+Matchi::Predicate.new(:be_nil).match? { nil }   # => true (calls nil?)
+```
 
-matcher.expected        # => #<Proc:0x00007fbaafc65540>
-matcher.matches? { 42 } # => true
+###### Using `have_` prefix
+```ruby
+Matchi::Predicate.new(:have_key, :foo).match? { { foo: 42 } }  # => true (calls has_key?)
 ```
 
 ### Custom matchers
 
-Custom matchers can easily be added to express more specific expectations.
+Custom matchers could easily be added to `Matchi` module to express more specific expectations.
 
 A **Be the answer** matcher:
 
 ```ruby
 module Matchi
   class BeTheAnswer
-    def expected
-      42
+    def match?
+      expected.equal?(yield)
     end
 
-    def matches?
-      expected.equal?(yield)
+    private
+
+    def expected
+      42
     end
   end
 end
 
 matcher = Matchi::BeTheAnswer.new
-
-matcher.expected        # => 42
-matcher.matches? { 42 } # => true
+matcher.match? { 42 } # => true
 ```
 
 A **Be prime** matcher:
@@ -203,7 +216,7 @@ require "prime"
 
 module Matchi
   class BePrime
-    def matches?
+    def match?
       Prime.prime?(yield)
     end
   end
@@ -211,7 +224,7 @@ end
 
 matcher = Matchi::BePrime.new
 
-matcher.matches? { 42 } # => false
+matcher.match? { 42 } # => false
 ```
 
 A **Start with** matcher:
@@ -219,22 +232,64 @@ A **Start with** matcher:
 ```ruby
 module Matchi
   class StartWith
-    attr_reader :expected
-
     def initialize(expected)
       @expected = expected
     end
 
-    def matches?
-      Regexp.new(/\A#{expected}/).match?(yield)
+    def match?
+      /\A#{@expected}/.match?(yield)
     end
   end
 end
 
 matcher = Matchi::StartWith.new("foo")
+matcher.match? { "foobar" } # => true
+```
+
+## Best Practices
+
+### Proper Value Comparison Order
+
+One of the most critical aspects when implementing matchers is the order of comparison between expected and actual values. Always compare values in this order:
+
+```ruby
+# GOOD: Expected value controls the comparison
+expected_value.eql?(actual_value)
+
+# BAD: Actual value controls the comparison
+actual_value.eql?(expected_value)
+```
+
+#### Why This Matters
+
+The order is crucial because the object receiving the comparison method controls how the comparison is performed. When testing, the actual value might come from untrusted or malicious code that could override comparison methods:
+
+```ruby
+# Example of how comparison can be compromised
+class MaliciousString
+  def eql?(other)
+    true  # Always returns true regardless of actual equality
+  end
 
-matcher.expected              # => "foo"
-matcher.matches? { "foobar" } # => true
+  def ==(other)
+    true  # Always returns true regardless of actual equality
+  end
+end
+
+actual = MaliciousString.new
+expected = "expected string"
+
+actual.eql?(expected)      # => true (incorrect result!)
+expected.eql?(actual)      # => false (correct result)
+```
+
+This is why Matchi's built-in matchers are implemented with this security consideration in mind. For example, the `Eq` matcher:
+
+```ruby
+# Implementation in Matchi::Eq
+def match?
+  @expected.eql?(yield)  # Expected value controls the comparison
+end
 ```
 
 ## Contact
@@ -250,11 +305,6 @@ __Matchi__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 The [gem](https://rubygems.org/gems/matchi) is available as open source under the terms of the [MIT License](https://github.com/fixrb/matchi/raw/main/LICENSE.md).
 
-***
+## Sponsors
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/matchi/raw/main/img/sashite.png"
-    alt="Sashite" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/matchi/be.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Identity* matcher.
   class Be
-    # @return [#equal?] The expected identical object.
-    attr_reader :expected
-
     # Initialize the matcher with an object.
     #
     # @example
@@ -24,26 +21,23 @@ module Matchi
     #   require "matchi/be"
     #
     #   matcher = Matchi::Be.new(:foo)
-    #
-    #   matcher.expected          # => :foo
-    #   matcher.matches? { :foo } # => true
+    #   matcher.match? { :foo } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      expected.equal?(yield)
-    end
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected.inspect})"
+      @expected.equal?(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "be #{expected.inspect}"
+      "be #{@expected.inspect}"
     end
   end
 end

data/lib/matchi/be_a_kind_of.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Type/class* matcher for inheritance-aware type checking.
+  #
+  # This matcher provides a clear way to check if an object is an instance of a
+  # specific class or one of its subclasses. It leverages Ruby's native === operator
+  # which reliably handles class hierarchy relationships.
+  #
+  # @example Basic usage
+  #   require "matchi/be_a_kind_of"
+  #
+  #   matcher = Matchi::BeAKindOf.new(Numeric)
+  #   matcher.match? { 42 }     # => true
+  #   matcher.match? { 42.0 }   # => true
+  #   matcher.match? { "42" }   # => false
+  class BeAKindOf
+    # Initialize the matcher with (the name of) a class or module.
+    #
+    # @example
+    #   require "matchi/be_a_kind_of"
+    #
+    #   Matchi::BeAKindOf.new(String)
+    #   Matchi::BeAKindOf.new("String")
+    #   Matchi::BeAKindOf.new(:String)
+    #
+    # @param expected [Class, #to_s] The expected class name
+    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
+    def initialize(expected)
+      @expected = String(expected)
+      return if /\A[A-Z]/.match?(@expected)
+
+      raise ::ArgumentError,
+            "expected must start with an uppercase letter (got: #{@expected})"
+    end
+
+    # Checks if the yielded object is an instance of the expected class
+    # or one of its subclasses.
+    #
+    # This method uses the case equality operator (===) which provides a reliable
+    # way to check class hierarchy relationships in Ruby. When a class is the
+    # receiver of ===, it returns true if the argument is an instance of that
+    # class or one of its subclasses.
+    #
+    # @example Class hierarchy check
+    #   class Animal; end
+    #   class Dog < Animal; end
+    #
+    #   matcher = Matchi::BeAKindOf.new(Animal)
+    #   matcher.match? { Dog.new }    # => true
+    #   matcher.match? { Animal.new } # => true
+    #   matcher.match? { Object.new } # => false
+    #
+    # @yieldreturn [Object] the actual value to check
+    # @return [Boolean] true if the object is an instance of the expected class or one of its subclasses
+    # @raise [ArgumentError] if no block is provided
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
+      expected_class === yield # rubocop:disable Style/CaseEquality
+    end
+
+    # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
+    def to_s
+      "be a kind of #{@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.
+    #
+    # @return [Class] the resolved class
+    # @raise [NameError] if the class doesn't exist
+    def expected_class
+      ::Object.const_get(@expected)
+    end
+  end
+end

data/lib/matchi/be_an_instance_of.rb

@@ -1,49 +1,119 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Type/class* matcher.
+  # *Type/class* matcher with enhanced class checking.
+  #
+  # This matcher aims to provide a more reliable way to check if an object is an exact
+  # instance of a specific class (not a subclass). While not foolproof, it uses a more
+  # robust method to get the actual class of an object that helps resist common
+  # attempts at type checking manipulation.
+  #
+  # @example Basic usage
+  #   require "matchi/be_an_instance_of"
+  #
+  #   matcher = Matchi::BeAnInstanceOf.new(String)
+  #   matcher.match? { "foo" }  # => true
+  #   matcher.match? { :foo }   # => false
+  #
+  # @example Enhanced class checking in practice
+  #   # Consider a class that attempts to masquerade as String by overriding
+  #   # common type checking methods:
+  #   class MaliciousString
+  #     def class
+  #       ::String
+  #     end
+  #
+  #     def instance_of?(klass)
+  #       self.class == klass
+  #     end
+  #
+  #     def is_a?(klass)
+  #       "".is_a?(klass)  # Delegates to a real String
+  #     end
+  #
+  #     def kind_of?(klass)
+  #       is_a?(klass)     # Maintains Ruby's kind_of? alias for is_a?
+  #     end
+  #   end
+  #
+  #   obj = MaliciousString.new
+  #   obj.class                                             # => String
+  #   obj.is_a?(String)                                     # => true
+  #   obj.kind_of?(String)                                  # => true
+  #   obj.instance_of?(String)                              # => true
+  #
+  #   # Using our enhanced checking approach:
+  #   matcher = Matchi::BeAnInstanceOf.new(String)
+  #   matcher.match? { obj }                                # => false
   class BeAnInstanceOf
-    # @return [String] The expected class name.
-    attr_reader :expected
-
     # Initialize the matcher with (the name of) a class or module.
     #
     # @example
     #   require "matchi/be_an_instance_of"
     #
     #   Matchi::BeAnInstanceOf.new(String)
+    #   Matchi::BeAnInstanceOf.new("String")
+    #   Matchi::BeAnInstanceOf.new(:String)
     #
-    # @param expected [Class, #to_s] The expected class name.
+    # @param expected [Class, #to_s] The expected class name
+    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
     def initialize(expected)
       @expected = String(expected)
+      return if /\A[A-Z]/.match?(@expected)
+
+      raise ::ArgumentError,
+            "expected must start with an uppercase letter (got: #{@expected})"
     end
 
-    # Boolean comparison between the class of the actual value and the
-    # expected class.
+    # Securely checks if the yielded object is an instance of the expected class.
     #
-    # @example
-    #   require "matchi/be_an_instance_of"
+    # This method uses a specific Ruby reflection technique to get the true class of
+    # an object, bypassing potential method overrides:
     #
-    #   matcher = Matchi::BeAnInstanceOf.new(String)
+    # 1. ::Object.instance_method(:class) retrieves the original, unoverridden 'class'
+    #    method from the Object class
+    # 2. .bind_call(obj) binds this original method to our object and calls it,
+    #    ensuring we get the real class regardless of method overrides
     #
-    #   matcher.expected           # => "String"
-    #   matcher.matches? { "foo" } # => true
+    # This approach is more reliable than obj.class because it uses Ruby's method
+    # binding mechanism to call the original implementation directly. While not
+    # completely foolproof, it provides better protection against type check spoofing
+    # than using regular method calls which can be overridden.
     #
-    # @yieldreturn [#class] the actual value to compare to the expected one.
+    # @example Basic class check
+    #   matcher = Matchi::BeAnInstanceOf.new(String)
+    #   matcher.match? { "test" }        # => true
+    #   matcher.match? { StringIO.new }  # => false
     #
-    # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      self.class.const_get(expected).equal?(yield.class)
-    end
+    # @see https://ruby-doc.org/core/Method.html#method-i-bind_call
+    # @see https://ruby-doc.org/core/UnboundMethod.html
+    #
+    # @yieldreturn [Object] the actual value to check
+    # @return [Boolean] true if the object's actual class is exactly the expected class
+    # @raise [ArgumentError] if no block is provided
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected})"
+      actual_class = ::Object.instance_method(:class).bind_call(yield)
+      expected_class == actual_class
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "be an instance of #{expected}"
+      "be an instance of #{@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.
+    #
+    # @return [Class] the resolved class
+    # @raise [NameError] if the class doesn't exist
+    def expected_class
+      ::Object.const_get(@expected)
     end
   end
 end