matchi 3.3.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5831db6ac7cfec32997d0683fb756c4442fa516702cdb410556fc9c790de1f03
-  data.tar.gz: 679942f7da92507e0cc4e944a3d9761cbb7d72083cb71ab7e5302a154fe889c0
+  metadata.gz: 730c0baf16a64842af123077150d70aee64e664ef6d5626dadf4730c1ee3425d
+  data.tar.gz: a934654b282119e28d4fb5c4079298770f86a834d58621240737f2473f067500
 SHA512:
-  metadata.gz: f75dea44631fe6a02dc2909e8d7ba1e1964e953a34268b021135436d45d49e9de25d439a7c4436c449c5366c57193bbf0d1e652fe8bf6439be1b17218c04ce82
-  data.tar.gz: 03acf53bf37c0f1397b8366dd2463faa174c2be364a234bb86b7a4c49cd540abf3e1749790822992a5420367260807a3de611840ccee74165e1bf204fbc4f571
+  metadata.gz: 75884ba2533b155d3f1e4490f9b8f6071a95aad0fca637dcdb0eee2bf60e1a3dc6bd7cab35ab93a3a7c18b680b9d789ee71bfbd7d524e6ca5ea8573520a3deec
+  data.tar.gz: d421e42619fc45d1f1aab95ccde2a24d6a1226f4163a4afbde02fc8e693343997fa5a9a0081d72734955b2b6a25b3f9f735766702860d2184c44f403e169f442

data/README.md

@@ -6,7 +6,8 @@
 [![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)
 
@@ -52,148 +53,221 @@ 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
 
-### Built-in matchers
+2. Optionally, it may implement:
+   - `to_s`: Returns a human-readable description of the match criteria
+
+### Using Matchers
+
+There are two main ways to use Matchi matchers:
 
-Here is the collection of useful generic matchers.
+#### 1. Direct Class Instantiation
 
-**Equivalence** matcher:
+You can create matchers directly from their classes:
 
 ```ruby
 matcher = Matchi::Eq.new("foo")
+matcher.match? { "foo" } # => true
 
-matcher.expected           # => "foo"
-matcher.matches? { "foo" } # => true
+matcher = Matchi::BeWithin.new(0.5).of(3.0)
+matcher.match? { 3.2 } # => true
 ```
 
-**Identity** matcher:
+#### 2. Helper Methods via Module Inclusion
+
+For a more expressive and readable syntax, you can include or extend the `Matchi` module to get access to helper methods:
 
 ```ruby
-matcher = Matchi::Be.new(:foo)
+# Including in a class for instance methods
+class MyTestFramework
+  include Matchi
 
-matcher.expected          # => :foo
-matcher.matches? { :foo } # => true
-```
+  def test_equality
+    # Helper methods available as instance methods
+    matcher = eq("foo")
+    assert(matcher.match? { "foo" })
 
-**Comparisons** matcher:
+    # Method chaining works too
+    assert(change(@array, :length).by(1).match? { @array << 1 })
+  end
+end
 
-```ruby
-matcher = Matchi::BeWithin.new(8).of(37)
+# Extending a class for class methods
+class MyAssertions
+  extend Matchi
+
+  def self.assert_equals(expected, actual)
+    eq(expected).match? { actual }
+  end
 
-matcher.expected        # => 37
-matcher.matches? { 42 } # => true
+  def self.assert_within_range(expected, delta, actual)
+    be_within(delta).of(expected).match? { actual }
+  end
+end
 ```
 
-**Regular expressions** matcher:
+Available helper methods correspond to the built-in matchers:
+- `eq` / `eql` - For equivalence matching
+- `be` / `equal` - For identity matching
+- `be_within` - For delta comparisons
+- `match` - For regular expression matching
+- `change` - For state changes
+- `be_true`, `be_false`, `be_nil` - For state verification
+- `be_an_instance_of` - For exact type matching
+- `be_a_kind_of` - For type hierarchy matching
+- `satisfy` - For custom block-based matching
+- Dynamic predicate matchers (`be_*` and `have_*`)
 
-```ruby
-matcher = Matchi::Match.new(/^foo$/)
+### Built-in matchers
 
-matcher.expected           # => /^foo$/
-matcher.matches? { "foo" } # => true
-```
+Here is the collection of generic matchers.
 
-**Expecting errors** matcher:
+#### Basic Comparison Matchers
 
+##### `Be`
+Checks for object identity using Ruby's `equal?` method.
 ```ruby
-matcher = Matchi::RaiseException.new(:NameError)
+Matchi::Be.new(:foo).match? { :foo } # => true (same object)
+Matchi::Be.new("test").match? { "test" } # => false (different objects)
+```
 
-matcher.expected          # => "NameError"
-matcher.matches? { Boom } # => true
+##### `Eq`
+Verifies object equivalence using Ruby's `eql?` method.
+```ruby
+Matchi::Eq.new("foo").match? { "foo" } # => true (equivalent content)
+Matchi::Eq.new([1, 2]).match? { [1, 2] } # => true (equivalent arrays)
 ```
 
-**Type/class** matcher:
+#### Type and Class Matchers
 
+##### `BeAnInstanceOf`
+Verifies exact class matching (no inheritance).
 ```ruby
-matcher = Matchi::BeAnInstanceOf.new(:String)
-
-matcher.expected           # => "String"
-matcher.matches? { "foo" } # => 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)
 ```
 
-**Predicate** matcher:
-
+##### `BeAKindOf`
+Verifies class inheritance and module inclusion.
 ```ruby
-matcher = Matchi::Predicate.new(:be_empty)
+Matchi::BeAKindOf.new(Numeric).match? { 42 }    # => true (Integer inherits from Numeric)
+Matchi::BeAKindOf.new(Numeric).match? { 42.0 }  # => true (Float inherits from Numeric)
+```
 
-matcher.expected        # => [:empty?, [], {}, nil]
-matcher.matches? { [] } # => true
+#### Pattern Matchers
 
-matcher = Matchi::Predicate.new(:have_key, :foo)
+##### `Match`
+Tests string patterns against regular expressions.
+```ruby
+Matchi::Match.new(/^foo/).match? { "foobar" }  # => true
+Matchi::Match.new(/\d+/).match? { "abc123" }   # => true
+Matchi::Match.new(/^foo/).match? { "barfoo" }  # => false
+```
 
-matcher.expected                 # => [:has_key?, [:foo], {}, nil]
-matcher.matches? { { foo: 42 } } # => true
+##### `Satisfy`
+Provides custom matching through a block.
+```ruby
+Matchi::Satisfy.new { |x| x.positive? && x < 10 }.match? { 5 } # => true
+Matchi::Satisfy.new { |x| x.start_with?("test") }.match? { "test_file" } # => true
 ```
 
-**Change** matcher:
+#### State Change Matchers
 
-```ruby
-object = []
-matcher = Matchi::Change.new(object, :length).by(1)
+##### `Change`
+Verifies state changes in objects with multiple variation methods:
 
-matcher.expected                 # => 1
-matcher.matches? { object << 1 } # => true
+###### Basic Change
+```ruby
+array = []
+Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) } # => true
+```
 
-object = []
-matcher = Matchi::Change.new(object, :length).by_at_least(1)
+###### Minimum Change
+```ruby
+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 +277,7 @@ require "prime"
 
 module Matchi
   class BePrime
-    def matches?
+    def match?
       Prime.prime?(yield)
     end
   end
@@ -211,7 +285,7 @@ end
 
 matcher = Matchi::BePrime.new
 
-matcher.matches? { 42 } # => false
+matcher.match? { 42 } # => false
 ```
 
 A **Start with** matcher:
@@ -219,22 +293,64 @@ A **Start with** matcher:
 ```ruby
 module Matchi
   class StartWith
-    attr_reader :expected
-
     def initialize(expected)
       @expected = expected
     end
 
-    def matches?
-      /\A#{expected}/.match?(yield)
+    def match?
+      /\A#{@expected}/.match?(yield)
     end
   end
 end
 
 matcher = Matchi::StartWith.new("foo")
+matcher.match? { "foobar" } # => true
+```
 
-matcher.expected              # => "foo"
-matcher.matches? { "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
+
+  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 +366,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="Sashité" /></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