matchi 4.1.1 → 5.0.0

data/lib/matchi/change.rb

@@ -1,110 +1,109 @@
 # frozen_string_literal: true
 
-require_relative File.join("change", "by_at_least")
-require_relative File.join("change", "by_at_most")
-require_relative File.join("change", "by")
-require_relative File.join("change", "from")
-require_relative File.join("change", "to")
+require_relative "change/delta"
+require_relative "change/from"
+require_relative "change/to"
+require_relative "constant"
 
 module Matchi
-  # Wraps the target of a change matcher.
+  # State change matcher: passes when evaluating the block changes the value
+  # returned by a public method of an object.
+  #
+  # The observed method is called with `public_send` before and after the
+  # block, and the two values are compared with `eql?`. The observed method
+  # must return a value, not the mutated object itself: when it returns the
+  # very same unfrozen object twice, the comparison cannot tell whether that
+  # object changed, and `match?` raises instead of answering `false`.
+  # `attr_reader :items` with `items << x` is that case; observe
+  # `items.length` or use {#to}, which compares with the expected value. A
+  # frozen object returned twice counts as an unchanged value.
+  #
+  # The refinements {#by}, {#by_at_least}, {#by_at_most}, {#from} and {#to}
+  # build more specific matchers. `Change`, `by`, `by_at_least` and
+  # `by_at_most` compare values produced by the observed object, so they
+  # depend on its honesty, like {Matchi::Predicate}. `to` and `from … to`
+  # compare with the expected value, like {Matchi::Eq}. Whatever the
+  # observed method raises propagates.
+  #
+  # @example
+  #   list = []
+  #   Matchi::Change.new(list, :length).match? { list << 1 }       # => true
+  #   Matchi::Change.new(list, :length).by(1).match? { list << 1 } # => true
   class Change
-    # Initialize a wrapper of the change matcher with an object and the name of
-    # one of its methods.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   Matchi::Change.new("foo", :to_s)
-    #
-    # @param object [#object_id]  An object.
-    # @param method [Symbol]      The name of a method.
-    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)
+    # @param object [Object] the object to observe
+    # @param method [Symbol, String] a public method of that object
+    # @param args [Array] positional arguments for the method
+    # @param kwargs [Hash] keyword arguments for the method
+    # @param block [Proc, nil] a block for the method
+    # @raise [ArgumentError] when method is neither a Symbol nor a String
+    def initialize(object, method, *args, **kwargs, &block)
+      raise ::ArgumentError, "method must be a Symbol or a String (got: #{method.inspect})" unless name?(method)
 
-      @state = -> { object.send(method, ...) }
+      @object = object
+      @method = method.to_sym
+      @state = -> { ::Kernel.instance_method(:public_send).bind_call(object, @method, *args, **kwargs, &block) }
     end
 
-    # Specifies a minimum delta of the expected change.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   object = []
-    #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by_at_least(1)
-    #
-    # @param minimum_delta [#object_id] The minimum delta of the expected change.
-    #
-    # @return [#match?] A *change by at least* matcher.
-    def by_at_least(minimum_delta)
-      ByAtLeast.new(minimum_delta, &@state)
+    # @yieldreturn [Object] ignored, the block is evaluated for its effect
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [NoMethodError] when the object has no such public method
+    # @raise [TypeError] when the observed method returns the same unfrozen object twice
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
+      value_before = @state.call
+      yield
+      value_after = @state.call
+
+      return !value_before.eql?(value_after) unless value_before.equal?(value_after)
+      return false if ::Kernel.instance_method(:frozen?).bind_call(value_before)
+
+      raise ::TypeError, "#{self} returned the same unfrozen object twice: observe a value, not the object"
     end
 
-    # Specifies a maximum delta of the expected change.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   object = []
-    #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by_at_most(1)
-    #
-    # @param maximum_delta [#object_id] The maximum delta of the expected change.
-    #
-    # @return [#match?] A *change by at most* matcher.
-    def by_at_most(maximum_delta)
-      ByAtMost.new(maximum_delta, &@state)
+    # @return [String] the observed class and method, such as `change Array#length`
+    def to_s
+      "change #{Constant.label(::Kernel.instance_method(:class).bind_call(@object))}##{@method}"
     end
 
-    # Specifies the delta of the expected change.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   object = []
-    #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by(1)
-    #
-    # @param delta [#object_id] The delta of the expected change.
-    #
-    # @return [#match?] A *change by* matcher.
+    # @param delta [Numeric] the exact expected difference, negative allowed
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real Numeric
     def by(delta)
-      By.new(delta, &@state)
+      Delta.new(:by, delta, &@state)
+    end
+
+    # @param delta [Numeric] the smallest acceptable increase, zero or positive
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real non-negative Numeric
+    def by_at_least(delta)
+      Delta.new(:by_at_least, delta, &@state)
     end
 
-    # Specifies the original value.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   change_wrapper = Matchi::Change.new("foo", :to_s)
-    #   change_wrapper.from("foo")
-    #
-    # @param old_value [#object_id] The original value.
-    #
-    # @return [#match?] A *change from* wrapper.
+    # @param delta [Numeric] the largest acceptable increase, zero or positive
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real non-negative Numeric
+    def by_at_most(delta)
+      Delta.new(:by_at_most, delta, &@state)
+    end
+
+    # @param old_value [#eql?] the expected value before the block
+    # @return [Matchi::Change::From] a builder; call `to` on it
     def from(old_value)
       From.new(old_value, &@state)
     end
 
-    # Specifies the new value to expect.
-    #
-    # @example
-    #   require "matchi/change"
-    #
-    #   change_wrapper = Matchi::Change.new("foo", :to_s)
-    #   change_wrapper.to("FOO")
-    #
-    # @param new_value [#object_id] The new value to expect.
-    #
-    # @return [#match?] A *change to* matcher.
+    # @param new_value [#eql?] the expected value after the block
+    # @return [Matchi::Change::To]
     def to(new_value)
       To.new(new_value, &@state)
     end
+
+    private
+
+    def name?(method)
+      ::Symbol === method || ::String === method
+    end
   end
 end

data/lib/matchi/constant.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Matchi
+  # Shared handling of an expected module given directly or by name.
+  #
+  # A name is a String or a Symbol holding a constant path such as
+  # `"Comparable"` or `:"Foo::Bar"`. It is validated when the matcher is built
+  # and resolved from `Object` when the matcher runs, which lets a
+  # specification be written before the class it describes is loaded. Since
+  # resolution goes through `Object.const_get`, an `autoload` or an
+  # `Object.const_missing` defined by the code under test takes part in it.
+  #
+  # @api private
+  module Constant
+    # A constant path: ASCII segments that start with a capital letter,
+    # joined by `::`, such as `"Comparable"` or `"File::Stat"`.
+    NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
+
+    # @param expected [Module, String, Symbol] a module, or its name
+    # @param kind [Class] `Module` or `Class`, what expected must be
+    # @return [Module, String] the module itself, or the validated name
+    # @raise [ArgumentError] when expected is neither
+    def self.normalize(expected, kind)
+      return expected if kind === expected
+      return String(expected) if (::String === expected || ::Symbol === expected) && NAME.match?(expected)
+
+      raise ::ArgumentError, "expected must be a #{kind} or a constant name (got: #{expected.inspect})"
+    end
+
+    # @param expected [Module, String] a module, or a validated name
+    # @return [String] the name, or a stable label for an anonymous module
+    #
+    # The name is read with `Module#name` bound to the module, so a class
+    # of the code under test that redefines `name` cannot break a report.
+    def self.label(expected)
+      return expected unless ::Module === expected
+
+      ::Module.instance_method(:name).bind_call(expected) || "an anonymous #{::Class === expected ? "class" : "module"}"
+    end
+
+    # @param expected [Module, String] a module, or a validated name
+    # @param kind [Class] `Module` or `Class`, what the name must resolve to
+    # @return [Module]
+    # @raise [NameError] when the name is not defined
+    # @raise [TypeError] when the name does not resolve to the expected kind
+    def self.resolve(expected, kind)
+      return expected if kind === expected
+
+      value = ::Object.const_get(expected)
+      raise ::TypeError, "#{expected} is not a #{kind}" unless kind === value
+
+      value
+    end
+  end
+end

data/lib/matchi/eq.rb

@@ -1,43 +1,44 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Equivalence* matcher.
+  # Equivalence matcher: passes when the actual value is of the same class as
+  # the expected value and `eql?` to it.
+  #
+  # The expected value receives the `eql?` call, so the actual value cannot
+  # lie. The class check comes first because a few core `eql?` methods, such
+  # as `Hash#eql?`, hand the comparison back to an operand of another class;
+  # it costs nothing, since `eql?` never holds across classes for core values.
+  #
+  # @example
+  #   Matchi::Eq.new("foo").match? { "foo" } # => true
+  #   Matchi::Eq.new(1).match? { 1.0 }       # => false (eql? is strict on type)
   class Eq
-    # Initialize the matcher with an object.
-    #
-    # @example
-    #   require "matchi/eq"
-    #
-    #   Matchi::Eq.new("foo")
-    #
-    # @param expected [#eql?] An expected equivalent object.
+    # @param expected [#eql?] the expected value
     def initialize(expected)
       @expected = expected
     end
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/eq"
-    #
-    #   matcher = Matchi::Eq.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.eql?(yield)
+      Eq.eql?(@expected, yield)
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     def to_s
       "eq #{@expected.inspect}"
     end
+
+    # @param expected [#eql?] the value that receives the comparison
+    # @param actual [Object] a value from the code under test
+    # @return [Boolean] whether actual is of the class of expected and `eql?` to it
+    def self.eql?(expected, actual)
+      return false unless ::Kernel.instance_method(:class).bind_call(actual).equal?(expected.class)
+
+      expected.eql?(actual) ? true : false
+    end
   end
 end

data/lib/matchi/match.rb

@@ -1,43 +1,47 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Regular expressions* matcher.
+  # Regular expression matcher: passes when the actual value is a String or a
+  # Symbol that the expected Regexp matches. Any other actual value fails, as
+  # does a string with an invalid or incompatible encoding.
+  #
+  # Only a `Regexp` is accepted as pattern: with a `String` pattern,
+  # `String#match?` would turn the actual value into the regular expression,
+  # handing the comparison to the code under test. Use {Matchi::Satisfy} for
+  # other predicates.
+  #
+  # @example
+  #   Matchi::Match.new(/^foo/).match? { "foobar" } # => true
+  #   Matchi::Match.new(/^foo/).match? { 42 }       # => false
   class Match
-    # Initialize the matcher with an instance of Regexp.
-    #
-    # @example
-    #   require "matchi/match"
-    #
-    #   Matchi::Match.new(/^foo$/)
-    #
-    # @param expected [#match] A regular expression.
+    # @param expected [Regexp] the pattern
+    # @raise [ArgumentError] when expected is not a Regexp
     def initialize(expected)
-      raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
+      raise ::ArgumentError, "expected must be a Regexp (got: #{expected.inspect})" unless ::Regexp === expected
 
       @expected = expected
     end
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/match"
-    #
-    #   matcher = Matchi::Match.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.match?(yield)
+      actual = yield
+      return false unless ::String === actual || ::Symbol === actual
+
+      string = ::Symbol === actual ? actual.name : actual
+      return false unless string.valid_encoding?
+
+      begin
+        @expected.match?(string)
+      rescue ::Encoding::CompatibilityError
+        false
+      end
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     def to_s
       "match #{@expected.inspect}"
     end

data/lib/matchi/number.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Matchi
+  # Validation of the numbers given to matchers: deltas and expected values
+  # must be finite and real, so that a `NaN`, an infinity or a `Complex`
+  # cannot build a matcher that never, or always, passes.
+  #
+  # @api private
+  module Number
+    # @param value [Object]
+    # @return [Boolean] whether value is a finite real Numeric
+    def self.finite_real?(value)
+      ::Numeric === value && value.real? && value.finite?
+    end
+
+    # @param value [Object]
+    # @param role [String] the argument name, for the error message
+    # @return [Numeric] value
+    # @raise [ArgumentError] when value is not a finite real Numeric
+    def self.finite_real!(value, role)
+      raise ::ArgumentError, "#{role} must be a finite real Numeric (got: #{value.inspect})" unless finite_real?(value)
+
+      value
+    end
+
+    # @param value [Object]
+    # @param role [String] the argument name, for the error message
+    # @return [Numeric] value
+    # @raise [ArgumentError] when value is not a finite real non-negative Numeric
+    def self.non_negative!(value, role)
+      finite_real!(value, role)
+      raise ::ArgumentError, "#{role} must be non-negative (got: #{value.inspect})" if value.negative?
+
+      value
+    end
+  end
+end

data/lib/matchi/predicate.rb

@@ -1,83 +1,73 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # *Predicate* matcher.
+  # Predicate matcher: passes when a predicate method of the actual value
+  # returns `true`. The matcher name `be_xxx` calls `xxx?`, and `have_xxx`
+  # calls `has_xxx?`, with `Kernel#public_send` bound to the actual value.
+  # The predicate must return `true` or `false`; any other value is an error,
+  # not a truthy pass.
+  #
+  # Since the actual value answers the call, this matcher depends on the
+  # honesty of the object under test. Use it for the object's own documented
+  # predicates.
+  #
+  # @example
+  #   Matchi::Predicate.new(:be_empty).match? { [] }           # => true
+  #   Matchi::Predicate.new(:have_key, :a).match? { { a: 1 } } # => true
   class Predicate
-    # Initialize the matcher with a name and arguments.
-    #
-    # @example
-    #   require "matchi/predicate"
-    #
-    #   Matchi::Predicate.new(:be_empty)
-    #
-    # @param name   [#to_s] A matcher name.
-    # @param args   [Array] A list of parameters.
-    # @param kwargs [Hash]  A list of keyword parameters.
-    # @param block  [Proc]  A block of code.
+    # A matcher name: `be_` or `have_`, then a letter, then letters, digits
+    # or underscores, in any script. It never ends with `?` or `!`.
+    NAME = /\A(be|have)_\p{Alpha}[\p{Alnum}_]*\z/
+
+    # @param name [Symbol, String] `be_xxx` or `have_xxx`
+    # @param args [Array] positional arguments for the predicate
+    # @param kwargs [Hash] keyword arguments for the predicate
+    # @param block [Proc, nil] a block for the predicate
+    # @raise [ArgumentError] when the name does not start with be_ or have_
     def initialize(name, *args, **kwargs, &block)
       @name = String(name)
-      raise ::ArgumentError, "invalid predicate name format" unless valid_name?
+      raise ::ArgumentError, "name must match #{NAME.inspect} (got: #{name.inspect})" unless NAME.match?(@name)
 
-      @args   = args
+      @method_name = method_name
+      @args = args
       @kwargs = kwargs
-      @block  = block
+      @block = block
     end
 
-    # Boolean comparison between the actual value and the expected value.
-    #
-    # @example
-    #   require "matchi/predicate"
-    #
-    #   matcher = Matchi::Predicate.new(:be_empty)
-    #   matcher.match? { [] } # => true
-    #
-    # @example
-    #   require "matchi/predicate"
-    #
-    #   matcher = Matchi::Predicate.new(:have_key, :foo)
-    #   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.
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [TypeError] when the predicate returns something other than true or false
+    # @raise [NoMethodError] when the actual value has no such public predicate
     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)
+      result = ::Kernel.instance_method(:public_send).bind_call(yield, @method_name, *@args, **@kwargs, &@block)
+      return result if true.equal?(result) || false.equal?(result)
 
-      raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
+      raise ::TypeError, "#{@method_name} must return true or false (got a #{Constant.label(result_class(result))})"
     end
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
+    # @return [String]
     def to_s
-      (
-        "#{@name.tr("_", " ")} " + [
-          @args.map(&:inspect).join(", "),
-          @kwargs.map { |k, v| "#{k}: #{v.inspect}" }.join(", "),
-          (@block.nil? ? "" : "&block")
-        ].reject { |i| i.eql?("") }.join(", ")
-      ).strip
+      arguments = @args.map(&:inspect) + @kwargs.map { |key, value| "#{key}: #{value.inspect}" }
+      arguments << "&block" if @block
+
+      [@name.tr("_", " "), arguments.join(", ")].reject(&:empty?).join(" ")
     end
 
     private
 
-    # The name of the method to send to the object.
     def method_name
-      if @name.start_with?("be_")
-        :"#{@name.gsub("be_", "")}?"
-      else
-        :"#{@name.gsub("have_", "has_")}?"
-      end
-    end
+      return "#{@name.delete_prefix("be_")}?" if @name.start_with?("be_")
 
-    # Verify the matcher name structure.
-    def valid_name?
-      return false if @name.end_with?("?", "!")
+      "has_#{@name.delete_prefix("have_")}?"
+    end
 
-      @name.start_with?("be_", "have_")
+    def result_class(result)
+      ::Kernel.instance_method(:class).bind_call(result)
     end
   end
 end