matchi 3.3.2 → 4.1.0

data/lib/matchi/predicate.rb

@@ -16,53 +16,42 @@ module Matchi
     # @param block  [Proc]  A block of code.
     def initialize(name, *args, **kwargs, &block)
       @name = String(name)
-
-      raise ::ArgumentError unless valid_name?
+      raise ::ArgumentError, "invalid predicate name format" unless valid_name?
 
       @args   = args
       @kwargs = kwargs
       @block  = block
     end
 
-    # @return [Array] The method name with any arguments to send to the subject.
-    def expected
-      [method_name, @args, @kwargs, @block]
-    end
-
     # Boolean comparison between the actual value and the expected value.
     #
     # @example
     #   require "matchi/predicate"
     #
     #   matcher = Matchi::Predicate.new(:be_empty)
-    #
-    #   matcher.expected        # => [:empty?, [], {}, nil]
-    #   matcher.matches? { [] } # => true
+    #   matcher.match? { [] } # => true
     #
     # @example
     #   require "matchi/predicate"
     #
     #   matcher = Matchi::Predicate.new(:have_key, :foo)
-    #
-    #   matcher.expected                 # => [:has_key?, [:foo], {}, nil]
-    #   matcher.matches? { { foo: 42 } } # => true
+    #   matcher.match? { { foo: 42 } } # => true
     #
     # @yieldreturn [#object_id] The actual value to receive the method request.
     #
     # @return [Boolean] A boolean returned by the actual value being tested.
-    def matches?
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
       value = yield.send(method_name, *@args, **@kwargs, &@block)
       return value if [false, true].include?(value)
 
       raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
     end
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{@name}, *#{@args.inspect}, **#{@kwargs.inspect}, &#{@block.inspect})"
-    end
-
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
       (
         "#{@name.tr("_", " ")} " + [

data/lib/matchi/raise_exception.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Expecting errors* matcher.
   class RaiseException
-    # @return [String] The expected exception name.
-    attr_reader :expected
-
     # Initialize the matcher with a descendant of class Exception.
     #
     # @example
@@ -16,6 +13,10 @@ module Matchi
     # @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})"
     end
 
     # Boolean comparison between the actual value and the expected value.
@@ -24,30 +25,42 @@ module Matchi
     #   require "matchi/raise_exception"
     #
     #   matcher = Matchi::RaiseException.new(NameError)
-    #
-    #   matcher.expected          # => "NameError"
-    #   matcher.matches? { Boom } # => true
+    #   matcher.match? { Boom } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      yield
-    rescue self.class.const_get(expected) => _e
-      true
-    else
-      false
-    end
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
+      klass = expected_class
+      raise ::ArgumentError, "expected exception class must inherit from Exception" unless klass <= ::Exception
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected})"
+      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
+      end
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "raise exception #{expected}"
+      "raise exception #{@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/satisfy.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Satisfy* matcher.
   class Satisfy
-    # @return [Proc] A block of code.
-    attr_reader :expected
-
     # Initialize the matcher with a block.
     #
     # @example
@@ -15,6 +12,8 @@ module Matchi
     #
     # @param block [Proc] A block of code.
     def initialize(&block)
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
       @expected = block
     end
 
@@ -24,24 +23,21 @@ module Matchi
     #   require "matchi/satisfy"
     #
     #   matcher = Matchi::Satisfy.new { |value| value == 42 }
-    #
-    #   matcher.expected        # => #<Proc:0x00007fbaafc65540>
-    #   matcher.matches? { 42 } # => true
+    #   matcher.match? { 42 } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      expected.call(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}(&block)"
+      @expected.call(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
       "satisfy &block"
     end

data/lib/matchi.rb

@@ -2,8 +2,308 @@
 
 # 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
 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|

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 4.1.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-25 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies: []
 description: "Collection of expectation matchers for Rubyists \U0001F939"
 email: contact@cyril.email
@@ -20,6 +19,7 @@ files:
 - README.md
 - lib/matchi.rb
 - lib/matchi/be.rb
+- 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
@@ -40,7 +40,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -55,8 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: "Collection of expectation matchers for Rubyists \U0001F939"
 test_files: []