matchi 4.1.1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b3579155f166f952bb90f1a6ea79c7fd99d7ec17c81782e36d0a7d79ed58596
-  data.tar.gz: acfda4f687384be25a015fa71a709c7101f69dbb7a0246d2c994eecadc959f11
+  metadata.gz: 66ca7f8e6eb1fb3e7fa80907957f37af41fd04b678258199c0f1abfe784aa839
+  data.tar.gz: b25bc8c4da4bb7db33478cf7fda77e7119bf0fce94fdfd8310ab8d7c79f8638c
 SHA512:
-  metadata.gz: 11593bee0850470dda340821820aba5cdf82b99752f01d4de54de0849ca935a520d1d44500abd1d4415809ea36b6a15b4603fd84d198797b4ab81e9af0185551
-  data.tar.gz: 8bb333121816652c5b3ca015df89edf962824453274fb89be666f21f313921de65d16b7901a52250076b66c47fe393e9335c31024c90a6465678ff537bf3846f
+  metadata.gz: 5c4b77eb03979138e162a7040380b9b74c31b16e1995e67e537eebd3d83074913fa39d377f29759e085f35a143a15f19407f77dcd6b2788fc5e2874b28f3591f
+  data.tar.gz: e570be50f7b9338a24489b791b0b118b0c892fcc6c8fdc7f375b6187cf63a430642d6a87c7b7016f28b9b6742e7a8c4c07cbcf94bf340a9d590dfbeb49ef0e87

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2025 Cyril Kato
+Copyright (c) 2015-2026 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

@@ -2,365 +2,158 @@
 
 [![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)
-[![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)
 
-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.
+Framework-agnostic matchers for Ruby. Small, explicit, and written so that the object under test cannot forge a match.
 
 ![A Rubyist juggling between Matchi letters](https://github.com/fixrb/matchi/raw/main/img/matchi.png)
 
-## Project goals
-
-* Adding matchers should be as simple as possible.
-* Being framework agnostic and easy to integrate.
-* Avoid false positives/negatives due to malicious actual values.
-
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
+# Gemfile
 gem "matchi"
 ```
 
-And then execute:
-
-```sh
-bundle install
-```
-
-Or install it yourself as:
-
-```sh
-gem install matchi
-```
-
-## Overview
-
-__Matchi__ provides a collection of damn simple expectation matchers.
+Matchi requires Ruby 3.3 or later and has no runtime dependency.
 
 ## Usage
 
-To make __Matchi__ available:
+A matcher is built with its expected value, then asked whether an actual value matches. The block yields the actual value once; `match?` answers `true` or `false`.
 
 ```ruby
 require "matchi"
-```
-
-All examples here assume that this has been done.
-
-### Anatomy of a matcher
-
-A **Matchi** matcher is a simple Ruby object that follows these requirements:
 
-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
-
-### Using Matchers
-
-There are two main ways to use Matchi matchers:
-
-#### 1. Direct Class Instantiation
-
-You can create matchers directly from their classes:
-
-```ruby
-matcher = Matchi::Eq.new("foo")
-matcher.match? { "foo" } # => true
-
-matcher = Matchi::BeWithin.new(0.5).of(3.0)
-matcher.match? { 3.2 } # => true
+matcher = Matchi::Eq.new(42)
+matcher.match? { 42 } # => true
+matcher.match? { 41 } # => false
+matcher.to_s          # => "eq 42"
 ```
 
-#### 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:
+Every `to_s` completes the sentence "expected ACTUAL to …", which is all a test framework needs:
 
 ```ruby
-# Including in a class for instance methods
-class MyTestFramework
-  include Matchi
-
-  def test_equality
-    # Helper methods available as instance methods
-    matcher = eq("foo")
-    assert(matcher.match? { "foo" })
-
-    # Method chaining works too
-    assert(change(@array, :length).by(1).match? { @array << 1 })
-  end
+# Minitest
+def assert_matches(matcher, actual)
+  assert matcher.match? { actual }, "expected #{actual.inspect} to #{matcher}"
 end
 
-# Extending a class for class methods
-class MyAssertions
-  extend Matchi
-
-  def self.assert_equals(expected, actual)
-    eq(expected).match? { actual }
-  end
-
-  def self.assert_within_range(expected, delta, actual)
-    be_within(delta).of(expected).match? { actual }
-  end
+def refute_matches(matcher, actual)
+  refute matcher.match? { actual }, "expected #{actual.inspect} not to #{matcher}"
 end
-```
-
-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_*`)
-
-### Built-in matchers
-
-Here is the collection of generic matchers.
-
-#### Basic Comparison Matchers
-
-##### `Be`
-Checks for object identity using Ruby's `equal?` method.
-```ruby
-Matchi::Be.new(:foo).match? { :foo } # => true (same object)
-Matchi::Be.new("test").match? { "test" } # => false (different objects)
-```
-
-##### `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 and Class Matchers
-
-##### `BeAnInstanceOf`
-Verifies exact class matching (no inheritance).
-```ruby
-Matchi::BeAnInstanceOf.new(String).match? { "test" }  # => true
-Matchi::BeAnInstanceOf.new(Integer).match? { 42 }     # => true
-Matchi::BeAnInstanceOf.new(Numeric).match? { 42 }     # => false (Integer, not Numeric)
+assert_matches Matchi::BeAKindOf.new(Numeric), 42
+refute_matches Matchi::Match.new(/^foo/), "bar"
 ```
 
-##### `BeAKindOf`
-Verifies class inheritance and module inclusion.
-```ruby
-Matchi::BeAKindOf.new(Numeric).match? { 42 }    # => true (Integer inherits from Numeric)
-Matchi::BeAKindOf.new(Numeric).match? { 42.0 }  # => true (Float inherits from Numeric)
-```
+Negation is the framework's job: Matchi has no `not_to`, it answers a boolean.
 
-#### Pattern Matchers
+## Matchers
 
-##### `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
-```
-
-##### `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
-```
-
-#### State Change Matchers
-
-##### `Change`
-Verifies state changes in objects with multiple variation methods:
-
-###### Basic Change
-```ruby
-array = []
-Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) } # => true
-```
-
-###### Minimum Change
-```ruby
-counter = 0
-Matchi::Change.new(counter, :to_i).by_at_least(2).match? { counter += 3 } # => true
-```
-
-###### Maximum Change
-```ruby
-value = 10
-Matchi::Change.new(value, :to_i).by_at_most(5).match? { value += 3 } # => true
-```
-
-###### From-To Change
-```ruby
-string = "hello"
-Matchi::Change.new(string, :upcase).from("hello").to("HELLO").match? { string.upcase! } # => true
-```
-
-###### To-Only Change
-```ruby
-number = 1
-Matchi::Change.new(number, :to_i).to(5).match? { number = 5 } # => true
-```
+require "matchi"
 
-#### Numeric Matchers
+# Identity (equal?) and equivalence (eql?)
+Matchi::Be.new(:foo).match? { :foo }            # => true
+Matchi::Eq.new("foo").match? { "foo" }          # => true
+Matchi::Eq.new(1).match? { 1.0 }                # => false
 
-##### `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
-```
+# Types: a module, or its name resolved when the matcher runs
+Matchi::BeAKindOf.new(Numeric).match? { 42 }       # => true
+Matchi::BeAnInstanceOf.new(:Integer).match? { 42 } # => true
+Matchi::BeAnInstanceOf.new(Numeric).match? { 42 }  # => false
 
-#### Behavior Matchers
+# Numeric proximity; a non-Numeric actual value fails
+Matchi::BeWithin.new(0.01).of(0.3).match? { 0.1 + 0.2 } # => 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
-```
+# Patterns and predicates
+Matchi::Match.new(/^foo/).match? { "foobar" }            # => true
+Matchi::Satisfy.new { |v| v > 41 }.match? { 42 }         # => true
+Matchi::Predicate.new(:be_empty).match? { [] }           # => true (calls empty?)
+Matchi::Predicate.new(:have_key, :a).match? { { a: 1 } } # => true (calls has_key?(:a))
 
-##### `Predicate`
-Creates matchers for methods ending in `?`.
+# Exceptions, by class or by name, optionally with a message (String or Regexp)
+Matchi::RaiseException.new(ZeroDivisionError).match? { 1 / 0 }               # => true
+Matchi::RaiseException.new("Errno::ENOENT").match? { File.read("/missing") } # => true
+Matchi::RaiseException.new(ZeroDivisionError, /by 0/).match? { 1 / 0 }       # => true
 
-###### Using `be_` prefix
-```ruby
-Matchi::Predicate.new(:be_empty).match? { [] }  # => true (calls empty?)
-Matchi::Predicate.new(:be_nil).match? { nil }   # => true (calls nil?)
-```
+# State changes, observed through a public method
+list = []
+Matchi::Change.new(list, :length).match? { list << 1 }                # => true
+Matchi::Change.new(list, :length).by(2).match? { list.push(1, 2) }    # => true
+Matchi::Change.new(list, :length).by_at_least(1).match? { list << 1 } # => true
+Matchi::Change.new(list, :length).by_at_most(1).match? { list << 1 }  # => true
 
-###### Using `have_` prefix
-```ruby
-Matchi::Predicate.new(:have_key, :foo).match? { { foo: 42 } } # => true (calls has_key?)
+list = []
+Matchi::Change.new(list, :length).to(1).match? { list << 1 }         # => true
+Matchi::Change.new(list, :length).from(1).to(2).match? { list << 1 } # => true
 ```
 
-### Custom matchers
-
-Custom matchers could easily be added to `Matchi` module to express more specific expectations.
+`BeWithin.new(delta)` and `Change#from(value)` are builders, not matchers: they do not respond to `match?` until `of` or `to` completes them.
 
-A **Be the answer** matcher:
+Arguments are validated when the matcher is built (`ArgumentError`); a name is resolved when the matcher runs (`NameError`, or `TypeError` when the constant is not a module). A block is always required by `match?`. Whatever the actual value or an observed method raises propagates; `RaiseException` catches what its block raises, not what its message filter or the resolution of its name raises.
 
-```ruby
-module Matchi
-  class BeTheAnswer
-    def match?
-      expected.equal?(yield)
-    end
-
-    private
+`RaiseException` catches every `Exception`, including `SystemExit` and `Interrupt`, so that a specification can assert on them; an unexpected `exit` inside the block is a failure, not the end of the process.
 
-    def expected
-      42
-    end
-  end
-end
+`Change` observes a value: when the observed method returns the same unfrozen object twice (an `attr_reader` on a mutated array, say), `match?` raises instead of reporting no change. Observe `items.length`, or use `to`.
 
-matcher = Matchi::BeTheAnswer.new
-matcher.match? { 42 } # => true
-```
+## Writing a matcher
 
-A **Be prime** matcher:
+Any object that responds to `match?` with a block and to `to_s` is a matcher:
 
 ```ruby
-require "prime"
-
-module Matchi
-  class BePrime
-    def match?
-      Prime.prime?(yield)
-    end
+class BePositive
+  def match?
+    yield.positive?
   end
-end
-
-matcher = Matchi::BePrime.new
 
-matcher.match? { 42 } # => false
-```
-
-A **Start with** matcher:
-
-```ruby
-module Matchi
-  class StartWith
-    def initialize(expected)
-      @expected = expected
-    end
-
-    def match?
-      /\A#{@expected}/.match?(yield)
-    end
+  def to_s
+    "be positive"
   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)
+BePositive.new.match? { 42 } # => true
 ```
 
-#### Why This Matters
+Every matcher in Matchi follows two rules, which are worth keeping in your own:
 
-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:
+- **The expected value receives the comparison.** `Matchi::Eq.new(a).match? { b }` evaluates `a.eql?(b)`, never `b.eql?(a)`, so an actual value that redefines `eql?` cannot pass; since `Hash#eql?` hands the comparison back to an operand of another class, `Eq` also requires the two values to be of the same class. Classes are compared with `Module#===`, the class of the actual value is read with `Kernel#class` bound to it, and `BeWithin` only subtracts core numbers, for the same reason.
+- **A predicate answers `true` or `false`.** `Satisfy` and `Predicate` raise a `TypeError` on any other value instead of treating it as truthy.
 
-```ruby
-# Example of how comparison can be compromised
-class MaliciousString
-  def eql?(other)
-    true  # Always returns true regardless of actual equality
-  end
+Two matchers depend on the honesty of the object under test, because they use values it produces: `Predicate` calls one of its methods, and `Change` (with `by`, `by_at_least`, `by_at_most`) compares two values returned by the observed method, including the subtraction between them. So does the message filter of `RaiseException`, which reads the exception's own message. `Change#to` and `from … to` compare with the expected value and do not.
 
-  def ==(other)
-    true  # Always returns true regardless of actual equality
-  end
-end
-
-actual = MaliciousString.new
-expected = "expected string"
+A class or an exception given by name (`:Duck`, `"Errno::ENOENT"`) is resolved from `Object` when the matcher runs, so a specification can be written before the class it describes is loaded. An `autoload` or an `Object.const_missing` defined by the code under test takes part in that resolution, so a name does not carry the guarantee a module does. Names are ASCII constant paths; `"::Integer"` is not accepted.
 
-actual.eql?(expected)      # => true (incorrect result!)
-expected.eql?(actual)      # => false (correct result)
-```
+## Differences from RSpec
 
-This is why Matchi's built-in matchers are implemented with this security consideration in mind. For example, the `Eq` matcher:
+If you come from RSpec or Minitest, these will surprise you:
 
-```ruby
-# Implementation in Matchi::Eq
-def match?
-  @expected.eql?(yield) # Expected value controls the comparison
-end
-```
+- `Eq` is RSpec's `eql`, not its `eq`: it compares with `eql?`, so `1` is not `1.0`, and a value object that only defines `==` never matches. Define `eql?` and `hash` on it, or use `Satisfy`. `Integer#==` hands the comparison to the other operand, which is why Matchi does not use it.
+- `Match` takes a `Regexp` only. For a literal substring, `Matchi::Match.new(Regexp.new(Regexp.escape("a.b")))`.
+- `RaiseException` is `raise_error`; it needs an exception class, or its name, and takes an optional message.
+- `Change#to` demands a change: a value already equal to the target does not pass. `Change` without a refinement needs the observed method to return a value, not the mutated object.
+- `Predicate` only calls a method of the actual value: `be_nil` calls `nil?`, but `be_truthy`, `be_falsey` and `be_a` are not predicates and do not exist. Use `Be.new(nil)`, `Satisfy`, `BeAKindOf`.
+- There is no `and`, `or`, `not_to` or `all`: compose in your framework, with plain booleans.
 
-## Contact
+## Changes in 5.0
 
-* Home page: https://github.com/fixrb/matchi
-* Bugs/issues: https://github.com/fixrb/matchi/issues
+- `BeAKindOf`, `BeAnInstanceOf` and `RaiseException` accept a module directly, so anonymous classes work. A name is still accepted; it must be a constant path (`"Foo::bar"` is rejected at construction) and resolve to a module, or a class for `BeAnInstanceOf` and an exception class for `RaiseException`. `BeAnInstanceOf` rejects a module that is not a class.
+- `RaiseException` compares with `Module#===` and always answers `true` or `false`; `Module#<=` could answer `nil` and let the exception control the comparison. A non-exception class is rejected at construction. An expected message, `String` or `Regexp`, can be given.
+- `Match` accepts a `Regexp` only, and fails on an actual value that is neither a `String` nor a `Symbol`, or whose encoding is invalid or incompatible. With a `String` pattern, the actual value would have become the regular expression.
+- `Eq`, `Change#to` and `from … to` require the actual value to be of the class of the expected value, so that `Hash#eql?` cannot hand the comparison to the object under test.
+- `Satisfy` requires a `true` or `false` answer (`TypeError`), as `Predicate` already did. The error names the class of the answer, never its `inspect`.
+- `Predicate` and `Change` reach the object under test through `Kernel#public_send`: a private or protected predicate is now a `NoMethodError`. `Change` accepts a `String` method name and no longer checks `respond_to?` at construction; a missing method is a `NoMethodError` when the matcher runs.
+- `BeWithin::Of` only subtracts an `Integer`, a `Float`, a `Rational` or a `BigDecimal`; any other actual value fails, including a user-defined `Numeric` that could control the subtraction through `coerce`. Deltas and expected values, there and in `by`, `by_at_least`, `by_at_most`, must be finite real numbers (`NaN`, infinities and `Complex` are rejected).
+- `BeWithin` without `of` and `Change#from` without `to` no longer respond to `match?`.
+- `from … to` compares with `eql?`, like `to` and `Eq` already did; `to` requires a change; both always evaluate the block. `Change` raises a `TypeError` when the observed method returns the same unfrozen object twice: in particular, asserting that an attribute holding an unfrozen object (a `Time`, an `Array`) did not change now raises instead of answering `false`. The three `by` refinements are one class, `Change::Delta`; `Change::From::To` is `Change::FromTo`.
+- Descriptions are stable: `Change#to_s` names the observed class and method (`change Array#length`), an anonymous class reads `an anonymous class`, and no `to_s` calls `inspect` on an object under test.
+- Error messages are rewritten and all read `X must be … (got: …)`; `Predicate::PREFIXES` is gone.
+- The `Matchi` helper module removed in 4.2 is not back: `Matchi` is a namespace. Frameworks define their own helpers.
+- Ruby 3.3 or later.
 
 ## Versioning
 
-__Matchi__ follows [Semantic Versioning 2.0](https://semver.org/).
+Matchi follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 

data/lib/matchi/be.rb

@@ -1,41 +1,28 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Identity* matcher.
+  # Identity matcher: passes when the actual value is the very same object as
+  # the expected one (`equal?`).
+  #
+  # @example
+  #   Matchi::Be.new(:foo).match? { :foo } # => true
+  #   Matchi::Be.new("a").match? { "a".dup } # => false (another object)
   class Be
-    # Initialize the matcher with an object.
-    #
-    # @example
-    #   require "matchi/be"
-    #
-    #   Matchi::Be.new(:foo)
-    #
-    # @param expected [#equal?] The expected identical object.
+    # @param expected [Object] the expected object
     def initialize(expected)
       @expected = expected
     end
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/be"
-    #
-    #   matcher = Matchi::Be.new(:foo)
-    #   matcher.match? { :foo } # => 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
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       @expected.equal?(yield)
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     def to_s
       "be #{@expected.inspect}"
     end

data/lib/matchi/be_a_kind_of.rb

@@ -1,81 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 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.
+  # Type matcher: passes when the actual value is an instance of the expected
+  # module or of one of its descendants (`Module#===`, so a `BasicObject` is
+  # handled and an object redefining `is_a?` cannot lie).
   #
-  # @example Basic usage
-  #   require "matchi/be_a_kind_of"
+  # The expected module can be given directly, or by name; see
+  # {Matchi::Constant}.
   #
-  #   matcher = Matchi::BeAKindOf.new(Numeric)
-  #   matcher.match? { 42 }     # => true
-  #   matcher.match? { 42.0 }   # => true
-  #   matcher.match? { "42" }   # => false
+  # @example
+  #   Matchi::BeAKindOf.new(Numeric).match? { 42 }    # => true
+  #   Matchi::BeAKindOf.new(:Numeric).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
+    # @param expected [Module, String, Symbol] the expected module, or its name
+    # @raise [ArgumentError] when expected is neither a Module nor a constant 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})"
+      @expected = Constant.normalize(expected, ::Module)
     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
+    # @yieldreturn [Object] the actual value
+    # @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 a Module
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      expected_class === yield # rubocop:disable Style/CaseEquality
+      Constant.resolve(@expected, ::Module) === yield
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     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)
+      "be a kind of #{Constant.label(@expected)}"
     end
   end
 end