matchi 4.2.0 → 6.0.0

data/lib/matchi/change/from.rb

@@ -1,75 +1,35 @@
 # frozen_string_literal: true
 
-require_relative File.join("from", "to")
+require_relative "from_to"
 
 module Matchi
   class Change
-    # Initial state wrapper for building a value transition matcher.
+    # Builder for the `change from OLD to NEW` matcher. It is not a matcher
+    # itself: it does not respond to `match?`, so a forgotten `to` is rejected
+    # by any framework that checks the matcher interface.
     #
-    # This class acts as a wrapper that captures the expected initial state and
-    # provides methods to build a complete transition matcher. When combined with
-    # the 'to' method, it creates a matcher that verifies both the starting and
-    # ending values of a change operation. This is useful when you need to ensure
-    # not only the final state but also the initial state of a value.
-    #
-    # @example Basic string transformation
-    #   text = "hello"
-    #   Change.new(text, :to_s).from("hello").to("HELLO").match? { text.upcase! }  # => true
-    #
-    # @example Object state transition
-    #   class User
-    #     attr_accessor :status
-    #     def initialize
-    #       @status = "pending"
-    #     end
-    #   end
-    #
-    #   user = User.new
-    #   Change.new(user, :status).from("pending").to("active").match? {
-    #     user.status = "active"
-    #   }  # => true
-    #
-    # @see Matchi::Change::From::To For the complete transition matcher
+    # @example
+    #   Matchi::Change.new(s, :to_s).from("a").to("b")
     class From
-      # Initialize the wrapper with an object and a block.
-      #
-      # @example
-      #   require "matchi/change/from"
-      #
-      #   object = "foo"
-      #
-      #   Matchi::Change::From.new("foo") { object.to_s }
-      #
-      # @param expected [#object_id]  An expected initial value.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
-      def initialize(expected, &state)
+      # @param old_value [#eql?] the expected value before the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
+      def initialize(old_value, &state)
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
-        @expected = expected
-        @state    = state
+        @old_value = old_value
+        @state = state
+      end
+
+      # @param new_value [#eql?] the expected value after the block
+      # @return [Matchi::Change::FromTo]
+      def to(new_value)
+        FromTo.new(@old_value, new_value, &@state)
       end
 
-      # Specifies the new value to expect.
-      #
-      # Creates a complete transition matcher that verifies both the initial
-      # and final states of a value. The matcher will succeed only if the
-      # value starts at the expected initial state and changes to the specified
-      # new value after executing the test block.
-      #
-      # @example
-      #   require "matchi/change/from"
-      #
-      #   object = "foo"
-      #
-      #   change_from_wrapper = Matchi::Change::From.new("foo") { object.to_s }
-      #   change_from_wrapper.to("FOO")
-      #
-      # @param expected_new_value [#object_id] The new value to expect.
-      #
-      # @return [#match?] A *change from to* matcher.
-      def to(expected_new_value)
-        To.new(@expected, expected_new_value, &@state)
+      # @return [String]
+      def to_s
+        "change from #{@old_value.inspect}"
       end
     end
   end

data/lib/matchi/change/from_to.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../eq"
+
+module Matchi
+  class Change
+    # Passes when the observed value is the old value before the block and
+    # the new value after it, both compared like {Matchi::Eq}. The block is
+    # always evaluated; a wrong initial value is a failure of the
+    # expectation, like a wrong final value.
+    #
+    # @example
+    #   s = +"a"
+    #   Matchi::Change.new(s, :to_s).from("a").to("b").match? { s.replace("b") } # => true
+    class FromTo
+      # @param old_value [#eql?] the expected value before the block
+      # @param new_value [#eql?] the expected value after the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
+      def initialize(old_value, new_value, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        @old_value = old_value
+        @new_value = new_value
+        @state = state
+      end
+
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        initial = Eq.eql?(@old_value, @state.call)
+        yield
+
+        initial && Eq.eql?(@new_value, @state.call)
+      end
+
+      # @return [String]
+      def to_s
+        "change from #{@old_value.inspect} to #{@new_value.inspect}"
+      end
+    end
+  end
+end

data/lib/matchi/change/to.rb

@@ -1,56 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "../eq"
+
 module Matchi
   class Change
-    # Final state matcher that verifies if a method returns an expected value after a change.
-    #
-    # This matcher focuses on the final state of an object, verifying that a method call
-    # returns an expected value after executing a block of code. Unlike the full from/to
-    # matcher, it only cares about the end result, not the initial state.
-    #
-    # @example Basic string transformation
-    #   text = "hello"
-    #   matcher = Matchi::Change::To.new("HELLO") { text.to_s }
-    #   matcher.match? { text.upcase! }   # => true
-    #   matcher.match? { text.reverse! }  # => false
-    #
-    # @example Number calculations
-    #   counter = 0
-    #   matcher = Matchi::Change::To.new(5) { counter }
-    #   matcher.match? { counter = 5 }    # => true
-    #   matcher.match? { counter += 1 }   # => false
-    #
-    # @example With object attributes
-    #   class User
-    #     attr_accessor :status
-    #     def initialize(status)
-    #       @status = status
-    #     end
-    #   end
-    #
-    #   user = User.new(:pending)
-    #   matcher = Matchi::Change::To.new(:active) { user.status }
-    #   matcher.match? { user.status = :active }  # => true
+    # Passes when the observed value is not the expected value before the
+    # block and is the expected value after it: the value must change to it.
+    # The block is always evaluated.
     #
-    # @see Matchi::Change::From::To For checking both initial and final states
-    # @see Matchi::Change::By For checking numeric changes
+    # @example
+    #   s = +"a"
+    #   Matchi::Change.new(s, :to_s).to("b").match? { s.replace("b") } # => true
     class To
-      # Initialize the matcher with an expected new value and a state block.
-      #
-      # @api public
-      #
-      # @param expected [#eql?] The expected final value
-      # @param state [Proc] Block that retrieves the value to check
-      #
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [To] a new instance of the matcher
-      #
-      # @example With simple value
-      #   To.new("test") { object.value }
-      #
-      # @example With complex calculation
-      #   To.new(100) { object.items.count }
+      # @param expected [#eql?] the expected value after the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
       def initialize(expected, &state)
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -58,47 +22,19 @@ module Matchi
         @state = state
       end
 
-      # Checks if the state block returns the expected value after executing the provided block.
-      #
-      # This method executes the provided block and then checks if the state block
-      # returns the expected value. It only cares about the final state, not any
-      # intermediate values or the initial state.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the final state matches the expected value
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage
-      #   text = "hello"
-      #   matcher = To.new("HELLO") { text.to_s }
-      #   matcher.match? { text.upcase! }  # => true
-      #
-      # @example With method chaining
-      #   array = [1, 2, 3]
-      #   matcher = To.new(6) { array.sum }
-      #   matcher.match? { array.map! { |x| x * 2 } }  # => false
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
+        already = Eq.eql?(@expected, @state.call)
         yield
-        value_after = @state.call
 
-        @expected.eql?(value_after)
+        !already && Eq.eql?(@expected, @state.call)
       end
 
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   To.new("test").to_s # => 'change to "test"'
+      # @return [String]
       def to_s
         "change to #{@expected.inspect}"
       end

data/lib/matchi/change.rb

@@ -1,85 +1,54 @@
 # 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.
-    #
-    # @api public
-    #
-    # @param object [#object_id] The object whose state will be monitored
-    # @param method [Symbol] The name of the method to track
-    # @param args [Array] Additional positional arguments to pass to the method
-    # @param kwargs [Hash] Additional keyword arguments to pass to the method
-    # @param block [Proc] Optional block to pass to the method
-    #
-    # @raise [ArgumentError] if method is not a Symbol
-    # @raise [ArgumentError] if object doesn't respond to method
-    #
-    # @return [Change] a new instance of the change wrapper
-    #
-    # @example Basic initialization
-    #   array = []
-    #   Change.new(array, :length)              # Track array length changes
-    #
-    # @example With positional arguments
-    #   hash = { key: "value" }
-    #   Change.new(hash, :fetch, :key)          # Track specific key value
-    #
-    # @example With keyword arguments
-    #   hash = { a: 1, b: 2 }
-    #   Change.new(hash, :fetch, default: 0)    # Track with default value
-    #
-    # @example With block
-    #   hash = { a: 1 }
-    #   Change.new(hash, :fetch, :b) { |k| k.to_s }  # Track with block default
+    # @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" unless method.is_a?(::Symbol)
-      raise ::ArgumentError, "object must respond to method" unless object.respond_to?(method)
+      raise ::ArgumentError, "method must be a Symbol or a String (got: #{method.inspect})" unless name?(method)
 
-      @state = -> { object.send(method, *args, **kwargs, &block) }
+      @object = object
+      @method = method.to_sym
+      @state = -> { ::Kernel.instance_method(:public_send).bind_call(object, @method, *args, **kwargs, &block) }
     end
 
-    # Checks if the tracked method's return value changes when executing the block.
-    #
-    # This method verifies that the value changes in any way between the start and end
-    # of the block execution. It doesn't care about the type or magnitude of the change,
-    # only that it's different.
-    #
-    # @api public
-    #
-    # @yield [] Block during which the change should occur
-    # @yieldreturn [Object] Result of the block execution (not used)
-    #
-    # @return [Boolean] true if the value changed, false otherwise
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example Basic usage with array length
-    #   array = []
-    #   matcher = Change.new(array, :length)
-    #   matcher.match? { array << "item" }    # => true
-    #   matcher.match? { array.clear }        # => true (from 1 to 0)
-    #   matcher.match? { array.dup }          # => false (no change)
-    #
-    # @example With method parameters
-    #   hash = { key: "old" }
-    #   matcher = Change.new(hash, :fetch, :key)
-    #   matcher.match? { hash[:key] = "new" }  # => true
-    #   matcher.match? { hash[:key] = "new" }  # => false (same value)
-    #
-    # @example With computed values
-    #   text = "hello"
-    #   matcher = Change.new(text, :upcase)
-    #   matcher.match? { text.upcase! }        # => true
-    #   matcher.match? { text.upcase! }        # => false (already uppercase)
+    # @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?
 
@@ -87,98 +56,54 @@ module Matchi
       yield
       value_after = @state.call
 
-      !value_before.eql?(value_after)
+      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
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Change.new("test", :upcase).to_s # => 'eq "test"'
+    # @return [String] the observed class and method, such as `change Array#length`
     def to_s
-      "change #{@state.inspect}"
+      "change #{Constant.label(::Kernel.instance_method(:class).bind_call(@object))}##{@method}"
     end
 
-    # Specifies a minimum delta of the expected change.
-    #
-    # @api public
-    #
-    # @param minimum_delta [#object_id] The minimum expected change amount
-    #
-    # @return [#match?] A matcher that verifies the minimum change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by_at_least(5)
-    #   matcher.match? { counter += 6 }  # => true
-    def by_at_least(minimum_delta)
-      ByAtLeast.new(minimum_delta, &@state)
+    # @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)
+      Delta.new(:by, delta, &@state)
     end
 
-    # Specifies a maximum delta of the expected change.
-    #
-    # @api public
-    #
-    # @param maximum_delta [#object_id] The maximum allowed change amount
-    #
-    # @return [#match?] A matcher that verifies the maximum change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by_at_most(5)
-    #   matcher.match? { counter += 3 }  # => true
-    def by_at_most(maximum_delta)
-      ByAtMost.new(maximum_delta, &@state)
+    # @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 exact delta of the expected change.
-    #
-    # @api public
-    #
-    # @param delta [#object_id] The exact expected change amount
-    #
-    # @return [#match?] A matcher that verifies the exact change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by(5)
-    #   matcher.match? { counter += 5 }  # => true
-    def by(delta)
-      By.new(delta, &@state)
+    # @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
 
-    # Specifies the original value in a value transition check.
-    #
-    # @api public
-    #
-    # @param old_value [#object_id] The expected initial value
-    #
-    # @return [#to] A wrapper for creating a from/to matcher
-    #
-    # @example
-    #   string = "foo"
-    #   Change.new(string, :to_s).from("foo").to("FOO")
+    # @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 final value to expect.
-    #
-    # @api public
-    #
-    # @param new_value [#object_id] The expected final value
-    #
-    # @return [#match?] A matcher that verifies the final state
-    #
-    # @example
-    #   string = "foo"
-    #   matcher = Change.new(string, :to_s).to("FOO")
-    #   matcher.match? { string.upcase! }  # => true
+    # @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