matchi 3.3.1 → 4.0.0

data/lib/matchi/be_within/of.rb

@@ -4,9 +4,6 @@ module Matchi
   class BeWithin
     # *BeWithin of* matcher.
     class Of
-      # @return [Numeric] An expected value.
-      attr_reader :expected
-
       # Initialize the matcher with a delta and an expected value.
       #
       # @example
@@ -17,6 +14,10 @@ module Matchi
       # @param delta    [Numeric] The accepted variation of the actual value.
       # @param expected [Numeric] The expected value.
       def initialize(delta, expected)
+        raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
+        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
+        raise ::ArgumentError, "delta must be non-negative" if delta.negative?
+
         @delta    = delta
         @expected = expected
       end
@@ -28,25 +29,22 @@ module Matchi
       #   require "matchi/be_within/of"
       #
       #   matcher = Matchi::BeWithin::Of.new(1, 41)
-      #
-      #   matcher.expected        # => 41
-      #   matcher.matches? { 42 } # => true
+      #   matcher.match? { 42 } # => true
       #
       # @yieldreturn [Numeric] The block of code to execute.
       #
       # @return [Boolean] Comparison between the actual and the expected values.
-      def matches?
-        (expected - yield).abs <= @delta
-      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}(#{@delta}, #{expected})"
+        (@expected - yield).abs <= @delta
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "be within #{@delta} of #{expected}"
+        "be within #{@delta} of #{@expected}"
       end
     end
   end

data/lib/matchi/be_within.rb

@@ -14,6 +14,9 @@ module Matchi
     #
     # @param delta [Numeric] A numeric value.
     def initialize(delta)
+      raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
+      raise ::ArgumentError, "delta must be non-negative" if delta.negative?
+
       @delta = delta
     end
 
@@ -27,7 +30,7 @@ module Matchi
     #
     # @param expected [Numeric] The expected value.
     #
-    # @return [#matches?] A *be_within of* matcher.
+    # @return [#match?] A *be_within of* matcher.
     def of(expected)
       Of.new(@delta, expected)
     end

data/lib/matchi/change/by.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by* matcher.
     class By
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,9 @@ module Matchi
       # @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
@@ -33,30 +33,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::By.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   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 matches?
+      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
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @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}"
+        "change by #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_least.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by at least* matcher.
     class ByAtLeast
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,10 @@ module Matchi
       # @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?
+        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
+
         @expected = expected
         @state    = state
       end
@@ -33,30 +34,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtLeast.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   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 matches?
+      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
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @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 at least #{expected.inspect}"
+        "change by at least #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_most.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by at most* matcher.
     class ByAtMost
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,10 @@ module Matchi
       # @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?
+        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
+
         @expected = expected
         @state    = state
       end
@@ -33,30 +34,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtMost.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   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 matches?
+      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
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @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 at most #{expected.inspect}"
+        "change by at most #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/from/to.rb

@@ -5,9 +5,6 @@ module Matchi
     class From
       # *Change from to* matcher.
       class To
-        # @return [#object_id] An expected new value.
-        attr_reader :expected
-
         # Initialize the matcher with two objects and a block.
         #
         # @example
@@ -22,6 +19,8 @@ module Matchi
         # @param state              [Proc]       A block of code to execute to
         #   get the state of the object.
         def initialize(expected_init, expected_new_value, &state)
+          raise ::ArgumentError, "a block must be provided" unless block_given?
+
           @expected_init  = expected_init
           @expected       = expected_new_value
           @state          = state
@@ -36,32 +35,29 @@ module Matchi
         #   object = "foo"
         #
         #   matcher = Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
-        #
-        #   matcher.expected                    # => "FOO"
-        #   matcher.matches? { object.upcase! } # => true
+        #   matcher.match? { object.upcase! } # => true
         #
         # @yieldreturn [#object_id] The block of code to execute.
         #
         # @return [Boolean] Comparison between the value before and after the
         #   code execution.
-        def matches?
+        def match?
+          raise ::ArgumentError, "a block must be provided" unless block_given?
+
           value_before = @state.call
           return false unless @expected_init == value_before
 
           yield
           value_after = @state.call
 
-          expected == value_after
-        end
-
-        # A string containing a human-readable representation of the matcher.
-        def inspect
-          "#{self.class}(#{@expected_init.inspect}, #{expected.inspect})"
+          @expected == value_after
         end
 
         # Returns a string representing the matcher.
+        #
+        # @return [String] a human-readable description of the matcher
         def to_s
-          "change from #{@expected_init.inspect} to #{expected.inspect}"
+          "change from #{@expected_init.inspect} to #{@expected.inspect}"
         end
       end
     end

data/lib/matchi/change/from.rb

@@ -19,6 +19,8 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         @expected = expected
         @state    = state
       end
@@ -35,7 +37,7 @@ module Matchi
       #
       # @param expected_new_value [#object_id] The new value to expect.
       #
-      # @return [#matches?] A *change from to* matcher.
+      # @return [#match?] A *change from to* matcher.
       def to(expected_new_value)
         To.new(@expected, expected_new_value, &@state)
       end

data/lib/matchi/change/to.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change to* matcher.
     class To
-      # @return [#object_id] An expected new value.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,8 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         @expected = expected
         @state    = state
       end
@@ -33,29 +32,26 @@ module Matchi
       #   object = "foo"
       #
       #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
-      #
-      #   matcher.expected                    # => "FOO"
-      #   matcher.matches? { object.upcase! } # => true
+      #   matcher.match? { object.upcase! } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         yield
         value_after = @state.call
 
-        expected == value_after
-      end
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @expected == value_after
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "change to #{expected.inspect}"
+        "change to #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change.rb

@@ -19,10 +19,11 @@ module Matchi
     #
     # @param object [#object_id]  An object.
     # @param method [Symbol]      The name of a method.
-    # @param args   [Array]       A list of arguments.
-    # @param kwargs [Hash]        A list of keyword arguments.
-    def initialize(object, method, *args, **kwargs, &block)
-      @state = -> { object.send(method, *args, **kwargs, &block) }
+    def initialize(object, method, ...)
+      raise ::ArgumentError, "method must be a Symbol" unless method.is_a?(::Symbol)
+      raise ::ArgumentError, "object must respond to method" unless object.respond_to?(method)
+
+      @state = -> { object.send(method, ...) }
     end
 
     # Specifies a minimum delta of the expected change.
@@ -37,7 +38,7 @@ module Matchi
     #
     # @param minimum_delta [#object_id] The minimum delta of the expected change.
     #
-    # @return [#matches?] A *change by at least* matcher.
+    # @return [#match?] A *change by at least* matcher.
     def by_at_least(minimum_delta)
       ByAtLeast.new(minimum_delta, &@state)
     end
@@ -54,7 +55,7 @@ module Matchi
     #
     # @param maximum_delta [#object_id] The maximum delta of the expected change.
     #
-    # @return [#matches?] A *change by at most* matcher.
+    # @return [#match?] A *change by at most* matcher.
     def by_at_most(maximum_delta)
       ByAtMost.new(maximum_delta, &@state)
     end
@@ -71,7 +72,7 @@ module Matchi
     #
     # @param delta [#object_id] The delta of the expected change.
     #
-    # @return [#matches?] A *change by* matcher.
+    # @return [#match?] A *change by* matcher.
     def by(delta)
       By.new(delta, &@state)
     end
@@ -86,7 +87,7 @@ module Matchi
     #
     # @param old_value [#object_id] The original value.
     #
-    # @return [#matches?] A *change from* wrapper.
+    # @return [#match?] A *change from* wrapper.
     def from(old_value)
       From.new(old_value, &@state)
     end
@@ -101,7 +102,7 @@ module Matchi
     #
     # @param new_value [#object_id] The new value to expect.
     #
-    # @return [#matches?] A *change to* matcher.
+    # @return [#match?] A *change to* matcher.
     def to(new_value)
       To.new(new_value, &@state)
     end

data/lib/matchi/eq.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Equivalence* matcher.
   class Eq
-    # @return [#eql?] An expected equivalent object.
-    attr_reader :expected
-
     # Initialize the matcher with an object.
     #
     # @example
@@ -24,26 +21,23 @@ module Matchi
     #   require "matchi/eq"
     #
     #   matcher = Matchi::Eq.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.eql?(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.eql?(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "eq #{expected.inspect}"
+      "eq #{@expected.inspect}"
     end
   end
 end

data/lib/matchi/match.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Regular expressions* matcher.
   class Match
-    # @return [#match] A regular expression.
-    attr_reader :expected
-
     # Initialize the matcher with an instance of Regexp.
     #
     # @example
@@ -15,6 +12,8 @@ module Matchi
     #
     # @param expected [#match] A regular expression.
     def initialize(expected)
+      raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
+
       @expected = expected
     end
 
@@ -24,26 +23,23 @@ module Matchi
     #   require "matchi/match"
     #
     #   matcher = Matchi::Match.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.match?(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.match?(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "match #{expected.inspect}"
+      "match #{@expected.inspect}"
     end
   end
 end

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