matchi 4.1.0 → 4.2.0

data/lib/matchi/be_a_kind_of.rb

@@ -1,68 +1,118 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Type/class* matcher for inheritance-aware type checking.
+  # Type matcher that checks if an object is an instance of a class or one of its subclasses.
   #
-  # 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.
-  #
-  # @example Basic usage
-  #   require "matchi/be_a_kind_of"
+  # This matcher provides a reliable way to verify object types while respecting Ruby's
+  # inheritance hierarchy. It uses the case equality operator (===) which is Ruby's
+  # built-in mechanism for type checking, ensuring consistent behavior with Ruby's
+  # own type system.
   #
+  # @example Basic usage with simple types
   #   matcher = Matchi::BeAKindOf.new(Numeric)
   #   matcher.match? { 42 }     # => true
   #   matcher.match? { 42.0 }   # => true
   #   matcher.match? { "42" }   # => false
+  #
+  # @example Working with inheritance hierarchies
+  #   class Animal; end
+  #   class Dog < Animal; end
+  #   class GermanShepherd < Dog; end
+  #
+  #   matcher = Matchi::BeAKindOf.new(Animal)
+  #   matcher.match? { Dog.new }             # => true
+  #   matcher.match? { GermanShepherd.new }  # => true
+  #   matcher.match? { Object.new }          # => false
+  #
+  # @example Using with modules and interfaces
+  #   module Swimmable
+  #     def swim; end
+  #   end
+  #
+  #   class Duck
+  #     include Swimmable
+  #   end
+  #
+  #   matcher = Matchi::BeAKindOf.new(Swimmable)
+  #   matcher.match? { Duck.new }     # => true
+  #   matcher.match? { Object.new }   # => false
+  #
+  # @example Different ways to specify the class
+  #   # Using class directly
+  #   Matchi::BeAKindOf.new(String)
+  #
+  #   # Using class name as string
+  #   Matchi::BeAKindOf.new("String")
+  #
+  #   # Using class name as symbol
+  #   Matchi::BeAKindOf.new(:String)
+  #
+  #   # Using namespaced class
+  #   Matchi::BeAKindOf.new("MyModule::MyClass")
+  #
+  # @see Matchi::BeAnInstanceOf
+  # @see https://ruby-doc.org/core/Module.html#method-i-3D-3D-3D
   class BeAKindOf
-    # Initialize the matcher with (the name of) a class or module.
+    # Creates a new type matcher for the specified class.
     #
-    # @example
-    #   require "matchi/be_a_kind_of"
+    # @api public
     #
-    #   Matchi::BeAKindOf.new(String)
-    #   Matchi::BeAKindOf.new("String")
-    #   Matchi::BeAKindOf.new(:String)
+    # @param expected [Class, #to_s] The expected class or its name
+    #   Can be provided as a Class object, String, or Symbol
     #
-    # @param expected [Class, #to_s] The expected class name
     # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
+    #
+    # @return [BeAKindOf] a new instance of the matcher
+    #
+    # @example
+    #   BeAKindOf.new(String)          # Using class
+    #   BeAKindOf.new("String")        # Using string
+    #   BeAKindOf.new(:String)         # Using symbol
     def initialize(expected)
       @expected = String(expected)
       return if /\A[A-Z]/.match?(@expected)
 
-      raise ::ArgumentError,
+      raise ArgumentError,
             "expected must start with an uppercase letter (got: #{@expected})"
     end
 
-    # Checks if the yielded object is an instance of the expected class
-    # or one of its subclasses.
+    # Checks if the yielded object is an instance of the expected class or 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.
+    # This method leverages Ruby's case equality operator (===) which provides a reliable
+    # way to check class hierarchy relationships. 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
+    # @api public
     #
-    #   matcher = Matchi::BeAKindOf.new(Animal)
-    #   matcher.match? { Dog.new }    # => true
-    #   matcher.match? { Animal.new } # => true
-    #   matcher.match? { Object.new } # => false
+    # @yield [] Block that returns the object to check
+    # @yieldreturn [Object] The object to verify the type of
     #
-    # @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
+    # @raise [NameError] if the expected class cannot be found
+    #
+    # @example Simple type check
+    #   matcher = BeAKindOf.new(Numeric)
+    #   matcher.match? { 42 }      # => true
+    #
+    # @example With inheritance
+    #   matcher = BeAKindOf.new(Animal)
+    #   matcher.match? { Dog.new } # => true
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       expected_class === yield # rubocop:disable Style/CaseEquality
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
     #
-    # @return [String] a human-readable description of the matcher
+    # @api public
+    #
+    # @return [String] A string describing what this matcher verifies
+    #
+    # @example
+    #   BeAKindOf.new(String).to_s # => "be a kind of String"
     def to_s
       "be a kind of #{@expected}"
     end
@@ -70,10 +120,13 @@ module Matchi
     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
+    # @api private
+    #
+    # @return [Class] The resolved class object
+    # @raise [NameError] If the class name cannot be resolved to an actual class
+    #
+    # @note This method handles both string and symbol class names through constant resolution
     def expected_class
       ::Object.const_get(@expected)
     end

data/lib/matchi/be_an_instance_of.rb

@@ -1,62 +1,71 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Type/class* matcher with enhanced class checking.
+  # Type matcher that checks if an object is an exact instance of a specific class.
   #
-  # This matcher aims to provide a more reliable way to check if an object is an exact
-  # instance of a specific class (not a subclass). While not foolproof, it uses a more
-  # robust method to get the actual class of an object that helps resist common
-  # attempts at type checking manipulation.
+  # This matcher provides a secure way to verify an object's exact type, ensuring it
+  # matches a specific class without including subclasses. It uses Ruby's method binding
+  # mechanism to bypass potential method overrides, providing better protection against
+  # type check spoofing than standard instance_of? checks.
   #
   # @example Basic usage
-  #   require "matchi/be_an_instance_of"
-  #
   #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { "foo" }  # => true
-  #   matcher.match? { :foo }   # => false
-  #
-  # @example Enhanced class checking in practice
-  #   # Consider a class that attempts to masquerade as String by overriding
-  #   # common type checking methods:
-  #   class MaliciousString
-  #     def class
-  #       ::String
-  #     end
+  #   matcher.match? { "test" }      # => true
+  #   matcher.match? { :test }       # => false
   #
-  #     def instance_of?(klass)
-  #       self.class == klass
-  #     end
+  # @example Inheritance behavior
+  #   class Animal; end
+  #   class Dog < Animal; end
   #
-  #     def is_a?(klass)
-  #       "".is_a?(klass)  # Delegates to a real String
-  #     end
+  #   matcher = Matchi::BeAnInstanceOf.new(Animal)
+  #   matcher.match? { Animal.new }  # => true
+  #   matcher.match? { Dog.new }     # => false  # Subclass doesn't match
   #
-  #     def kind_of?(klass)
-  #       is_a?(klass)     # Maintains Ruby's kind_of? alias for is_a?
-  #     end
+  # @example Secure type checking
+  #   # Consider a class that attempts to masquerade as String:
+  #   class MaliciousString
+  #     def class; String; end
+  #     def instance_of?(klass); true; end
   #   end
   #
   #   obj = MaliciousString.new
-  #   obj.class                                             # => String
-  #   obj.is_a?(String)                                     # => true
-  #   obj.kind_of?(String)                                  # => true
-  #   obj.instance_of?(String)                              # => true
+  #   obj.instance_of?(String)                           # => true (spoofed)
   #
-  #   # Using our enhanced checking approach:
   #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { obj }                                # => false
+  #   matcher.match? { obj }                             # => false (secure)
+  #
+  # @example Different ways to specify the class
+  #   # Using class directly
+  #   Matchi::BeAnInstanceOf.new(String)
+  #
+  #   # Using class name as string
+  #   Matchi::BeAnInstanceOf.new("String")
+  #
+  #   # Using class name as symbol
+  #   Matchi::BeAnInstanceOf.new(:String)
+  #
+  #   # Using namespaced class
+  #   Matchi::BeAnInstanceOf.new("MyModule::MyClass")
+  #
+  # @see Matchi::BeAKindOf
+  # @see https://ruby-doc.org/core/Object.html#method-i-instance_of-3F
+  # @see https://ruby-doc.org/core/Module.html#method-i-bind_call
   class BeAnInstanceOf
     # Initialize the matcher with (the name of) a class or module.
     #
-    # @example
-    #   require "matchi/be_an_instance_of"
+    # @api public
     #
-    #   Matchi::BeAnInstanceOf.new(String)
-    #   Matchi::BeAnInstanceOf.new("String")
-    #   Matchi::BeAnInstanceOf.new(:String)
+    # @param expected [Class, #to_s] The expected class or its name
+    #   Can be provided as a Class object, String, or Symbol
     #
-    # @param expected [Class, #to_s] The expected class name
     # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
+    #
+    # @return [BeAnInstanceOf] a new instance of the matcher
+    #
+    # @example
+    #   BeAnInstanceOf.new(String)          # Using class
+    #   BeAnInstanceOf.new("String")        # Using string
+    #   BeAnInstanceOf.new(:String)         # Using symbol
     def initialize(expected)
       @expected = String(expected)
       return if /\A[A-Z]/.match?(@expected)
@@ -67,30 +76,25 @@ module Matchi
 
     # Securely checks if the yielded object is an instance of the expected class.
     #
-    # This method uses a specific Ruby reflection technique to get the true class of
-    # an object, bypassing potential method overrides:
+    # This method uses Ruby's method binding mechanism to get the true class of an object,
+    # bypassing potential method overrides. While not completely foolproof, it provides
+    # better protection against type check spoofing than using regular method calls which
+    # can be overridden.
     #
-    # 1. ::Object.instance_method(:class) retrieves the original, unoverridden 'class'
-    #    method from the Object class
-    # 2. .bind_call(obj) binds this original method to our object and calls it,
-    #    ensuring we get the real class regardless of method overrides
+    # @api public
     #
-    # This approach is more reliable than obj.class because it uses Ruby's method
-    # binding mechanism to call the original implementation directly. While not
-    # completely foolproof, it provides better protection against type check spoofing
-    # than using regular method calls which can be overridden.
+    # @yield [] Block that returns the object to check
+    # @yieldreturn [Object] The object to verify the type of
     #
-    # @example Basic class check
-    #   matcher = Matchi::BeAnInstanceOf.new(String)
-    #   matcher.match? { "test" }        # => true
-    #   matcher.match? { StringIO.new }  # => false
-    #
-    # @see https://ruby-doc.org/core/Method.html#method-i-bind_call
-    # @see https://ruby-doc.org/core/UnboundMethod.html
-    #
-    # @yieldreturn [Object] the actual value to check
     # @return [Boolean] true if the object's actual class is exactly the expected class
+    #
     # @raise [ArgumentError] if no block is provided
+    # @raise [NameError] if the expected class cannot be found
+    #
+    # @example Simple type check
+    #   matcher = BeAnInstanceOf.new(String)
+    #   matcher.match? { "test" }        # => true
+    #   matcher.match? { StringIO.new }  # => false
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -98,9 +102,14 @@ module Matchi
       expected_class == actual_class
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
+    #
+    # @return [String] A string describing what this matcher verifies
     #
-    # @return [String] a human-readable description of the matcher
+    # @example
+    #   BeAnInstanceOf.new(String).to_s # => "be an instance of String"
     def to_s
       "be an instance of #{@expected}"
     end
@@ -108,10 +117,13 @@ module Matchi
     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
+    # @api private
+    #
+    # @return [Class] The resolved class object
+    # @raise [NameError] If the class name cannot be resolved to an actual class
+    #
+    # @note This method handles both string and symbol class names through constant resolution
     def expected_class
       ::Object.const_get(@expected)
     end

data/lib/matchi/be_within.rb

@@ -1,18 +1,47 @@
 # frozen_string_literal: true
 
-require_relative File.join("be_within", "of")
-
 module Matchi
-  # Wraps the target of a be_within matcher.
+  # Delta comparison matcher that checks if a numeric value is within a specified range.
+  #
+  # This matcher verifies that a numeric value falls within a certain distance (delta)
+  # of an expected value. It's particularly useful for floating-point comparisons or
+  # when checking if a value is approximately equal to another within a given tolerance.
+  #
+  # @example Basic usage with integers
+  #   matcher = Matchi::BeWithin.new(1).of(10)
+  #   matcher.match? { 9 }    # => true
+  #   matcher.match? { 10 }   # => true
+  #   matcher.match? { 11 }   # => true
+  #   matcher.match? { 12 }   # => false
+  #
+  # @example Floating point comparisons
+  #   matcher = Matchi::BeWithin.new(0.1).of(3.14)
+  #   matcher.match? { 3.1 }   # => true
+  #   matcher.match? { 3.2 }   # => true
+  #   matcher.match? { 3.0 }   # => false
+  #
+  # @example Working with percentages
+  #   matcher = Matchi::BeWithin.new(5).of(100)  # 5% margin
+  #   matcher.match? { 95 }    # => true
+  #   matcher.match? { 105 }   # => true
+  #   matcher.match? { 110 }   # => false
+  #
+  # @see https://ruby-doc.org/core/Numeric.html#method-i-abs
   class BeWithin
-    # Initialize a wrapper of the be_within matcher with a numeric value.
+    # Initialize the matcher with a delta value.
     #
-    # @example
-    #   require "matchi/be_within"
+    # @api public
+    #
+    # @param delta [Numeric] The maximum allowed difference from the expected value
     #
-    #   Matchi::BeWithin.new(1)
+    # @raise [ArgumentError] if delta is not a Numeric
+    # @raise [ArgumentError] if delta is negative
     #
-    # @param delta [Numeric] A numeric value.
+    # @return [BeWithin] a new instance of the matcher
+    #
+    # @example
+    #   BeWithin.new(0.5)           # Using float
+    #   BeWithin.new(2)             # Using integer
     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?
@@ -20,19 +49,101 @@ module Matchi
       @delta = delta
     end
 
-    # Specifies an expected numeric value.
+    # Raises NotImplementedError as this is not a complete matcher.
+    #
+    # This class acts as a builder for the actual matcher, which is created
+    # by calling the #of method. Direct use of #match? is not supported.
+    #
+    # @api public
+    #
+    # @raise [NotImplementedError] always, as this method should not be used
     #
     # @example
-    #   require "matchi/be_within"
+    #   # Don't do this:
+    #   BeWithin.new(0.5).match? { 42 }  # Raises NotImplementedError
+    #
+    #   # Do this instead:
+    #   BeWithin.new(0.5).of(42).match? { 41.8 }  # Works correctly
+    def match?
+      raise ::NotImplementedError, "BeWithin is not a complete matcher. Use BeWithin#of to create a valid matcher."
+    end
+
+    # Specifies the expected reference value.
     #
-    #   be_within_wrapper = Matchi::BeWithin.new(1)
-    #   be_within_wrapper.of(41)
+    # @api public
     #
-    # @param expected [Numeric] The expected value.
+    # @param expected [Numeric] The reference value to compare against
     #
-    # @return [#match?] A *be_within of* matcher.
+    # @raise [ArgumentError] if expected is not a Numeric
+    #
+    # @return [#match?] A matcher that checks if a value is within the specified range
+    #
+    # @example
+    #   be_within_wrapper = BeWithin.new(0.5)
+    #   be_within_wrapper.of(3.14)  # Creates matcher for values in range 2.64..3.64
     def of(expected)
       Of.new(@delta, expected)
     end
+
+    # Nested class that performs the actual comparison.
+    #
+    # This class implements the actual matching logic, comparing the provided value
+    # against the expected value using the specified delta.
+    class Of
+      # Initialize the matcher with a delta and an expected value.
+      #
+      # @api private
+      #
+      # @param delta [Numeric] The maximum allowed difference from the expected value
+      # @param expected [Numeric] The reference value to compare against
+      #
+      # @raise [ArgumentError] if delta is not a Numeric
+      # @raise [ArgumentError] if expected is not a Numeric
+      # @raise [ArgumentError] if delta is negative
+      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
+
+      # Checks if the yielded value is within the accepted range.
+      #
+      # The value is considered within range if its absolute difference from the
+      # expected value is less than or equal to the specified delta.
+      #
+      # @api public
+      #
+      # @yield [] Block that returns the value to check
+      # @yieldreturn [Numeric] The value to verify
+      #
+      # @return [Boolean] true if the value is within the accepted range
+      #
+      # @raise [ArgumentError] if no block is provided
+      #
+      # @example
+      #   matcher = BeWithin.new(0.5).of(3.14)
+      #   matcher.match? { 3.0 }   # => true
+      #   matcher.match? { 4.0 }   # => false
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        (@expected - yield).abs <= @delta
+      end
+
+      # Returns a human-readable description of the matcher.
+      #
+      # @api public
+      #
+      # @return [String] A string describing what this matcher verifies
+      #
+      # @example
+      #   BeWithin.new(0.5).of(3.14).to_s # => "be within 0.5 of 3.14"
+      def to_s
+        "be within #{@delta} of #{@expected}"
+      end
+    end
   end
 end

data/lib/matchi/change/by.rb

@@ -2,43 +2,113 @@
 
 module Matchi
   class Change
-    # *Change by* matcher.
+    # Exact delta matcher that verifies precise numeric changes in object state.
+    #
+    # This matcher ensures that a numeric value changes by exactly the specified amount
+    # after executing a block of code. It's particularly useful for testing operations
+    # that should produce precise, predictable changes in numeric attributes, such as
+    # counters, quantities, or calculated values.
+    #
+    # @example Testing collection size changes
+    #   array = []
+    #   matcher = Matchi::Change::By.new(2) { array.size }
+    #   matcher.match? { array.concat([1, 2]) }     # => true
+    #   matcher.match? { array.push(3) }            # => false  # Changed by 1
+    #   matcher.match? { array.push(3, 4, 5) }      # => false  # Changed by 3
+    #
+    # @example Verifying numeric calculations
+    #   counter = 100
+    #   matcher = Matchi::Change::By.new(-10) { counter }
+    #   matcher.match? { counter -= 10 }            # => true
+    #   matcher.match? { counter -= 15 }            # => false  # Changed too much
+    #
+    # @example Working with custom numeric attributes
+    #   class Account
+    #     attr_reader :balance
+    #
+    #     def initialize(initial_balance)
+    #       @balance = initial_balance
+    #     end
+    #
+    #     def deposit(amount)
+    #       @balance += amount
+    #     end
+    #
+    #     def withdraw(amount)
+    #       @balance -= amount
+    #     end
+    #   end
+    #
+    #   account = Account.new(1000)
+    #   matcher = Matchi::Change::By.new(50) { account.balance }
+    #   matcher.match? { account.deposit(50) }      # => true
+    #   matcher.match? { account.deposit(75) }      # => false  # Changed by 75
+    #
+    # @example Handling floating point values
+    #   temperature = 20.0
+    #   matcher = Matchi::Change::By.new(1.5) { temperature }
+    #   matcher.match? { temperature += 1.5 }       # => true
+    #   matcher.match? { temperature += 1.6 }       # => false  # Not exact match
+    #
+    # @note This matcher checks for exact changes, use ByAtLeast or ByAtMost for
+    #   more flexible delta comparisons
+    #
+    # @see Matchi::Change::ByAtLeast For minimum change validation
+    # @see Matchi::Change::ByAtMost For maximum change validation
+    # @see Matchi::Change::From::To For exact value transition validation
     class By
-      # Initialize the matcher with an object and a block.
+      # Initialize the matcher with an expected delta and a state block.
       #
-      # @example
-      #   require "matchi/change/by"
+      # @api public
+      #
+      # @param expected [Numeric] The exact amount by which the value should change
+      # @param state [Proc] Block that retrieves the current value
+      #
+      # @raise [ArgumentError] if expected is not a Numeric
+      # @raise [ArgumentError] if no state block is provided
       #
-      #   object = []
+      # @return [By] a new instance of the matcher
       #
-      #   Matchi::Change::By.new(1) { object.length }
+      # @example With positive delta
+      #   By.new(5) { counter.value }
       #
-      # @param expected [#object_id]  An expected delta.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
+      # @example With negative delta
+      #   By.new(-3) { stock_level.quantity }
+      #
+      # @example With floating point delta
+      #   By.new(0.5) { temperature.celsius }
       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
+        @state = state
       end
 
-      # Boolean comparison on the expected change by comparing the value
-      # before and after the code execution.
+      # Verifies that the value changes by exactly the expected amount.
       #
-      # @example
-      #   require "matchi/change/by"
+      # This method compares the value before and after executing the provided block,
+      # ensuring that the difference matches the expected delta exactly. It's useful
+      # for cases where precision is important and approximate changes are not acceptable.
       #
-      #   object = []
+      # @api public
       #
-      #   matcher = Matchi::Change::By.new(1) { object.length }
-      #   matcher.match? { object << "foo" } # => true
+      # @yield [] Block that should cause the state change
+      # @yieldreturn [Object] The result of the block (not used)
       #
-      # @yieldreturn [#object_id] The block of code to execute.
+      # @return [Boolean] true if the value changed by exactly the expected amount
       #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
+      # @raise [ArgumentError] if no block is provided
+      #
+      # @example Basic usage
+      #   counter = 0
+      #   matcher = By.new(5) { counter }
+      #   matcher.match? { counter += 5 }  # => true
+      #
+      # @example Failed match
+      #   items = []
+      #   matcher = By.new(2) { items.size }
+      #   matcher.match? { items.push(1) }  # => false  # Changed by 1
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -49,9 +119,16 @@ module Matchi
         @expected == (value_after - value_before)
       end
 
-      # Returns a string representing the matcher.
+      # Returns a human-readable description of the matcher.
+      #
+      # @api public
       #
-      # @return [String] a human-readable description of the matcher
+      # @return [String] A string describing what this matcher verifies
+      #
+      # @example
+      #   By.new(5).to_s    # => "change by 5"
+      #   By.new(-3).to_s   # => "change by -3"
+      #   By.new(2.5).to_s  # => "change by 2.5"
       def to_s
         "change by #{@expected.inspect}"
       end