matchi 4.1.0 → 4.2.0

data/lib/matchi/change/by_at_least.rb

@@ -2,20 +2,102 @@
 
 module Matchi
   class Change
-    # *Change by at least* matcher.
+    # Minimum delta matcher that verifies numeric changes meet or exceed a threshold.
+    #
+    # This matcher ensures that a numeric value changes by at least the specified amount
+    # after executing a block of code. It's particularly useful when testing operations
+    # where you want to ensure a minimum change occurs but larger changes are acceptable,
+    # such as performance improvements, resource allocation, or progressive counters.
+    #
+    # @example Testing collection growth
+    #   items = []
+    #   matcher = Matchi::Change::ByAtLeast.new(2) { items.size }
+    #   matcher.match? { items.push(1, 2) }          # => true   # Changed by exactly 2
+    #   matcher.match? { items.push(1, 2, 3) }       # => true   # Changed by more than 2
+    #   matcher.match? { items.push(1) }             # => false  # Changed by less than 2
+    #
+    # @example Verifying performance improvements
+    #   class Benchmark
+    #     def initialize
+    #       @score = 100
+    #     end
+    #
+    #     def optimize!
+    #       @score += rand(20..30)  # Improvement varies
+    #     end
+    #
+    #     def score
+    #       @score
+    #     end
+    #   end
+    #
+    #   benchmark = Benchmark.new
+    #   matcher = Matchi::Change::ByAtLeast.new(20) { benchmark.score }
+    #   matcher.match? { benchmark.optimize! }   # => true  # Any improvement >= 20 passes
+    #
+    # @example Resource allocation
+    #   class Pool
+    #     def initialize
+    #       @capacity = 1000
+    #     end
+    #
+    #     def allocate(minimum, maximum)
+    #       actual = rand(minimum..maximum)
+    #       @capacity -= actual
+    #       actual
+    #     end
+    #
+    #     def available
+    #       @capacity
+    #     end
+    #   end
+    #
+    #   pool = Pool.new
+    #   matcher = Matchi::Change::ByAtLeast.new(50) { -pool.available }
+    #   matcher.match? { pool.allocate(50, 100) }  # => true  # Allocates at least 50
+    #
+    # @example Price threshold monitoring
+    #   class Stock
+    #     attr_reader :price
+    #
+    #     def initialize(price)
+    #       @price = price
+    #     end
+    #
+    #     def fluctuate!
+    #       @price += rand(-10.0..20.0)
+    #     end
+    #   end
+    #
+    #   stock = Stock.new(100.0)
+    #   matcher = Matchi::Change::ByAtLeast.new(10.0) { stock.price }
+    #   matcher.match? { stock.fluctuate! }  # => true if price rises by 10.0 or more
+    #
+    # @note This matcher verifies minimum changes only. For exact changes, use By,
+    #   and for maximum changes, use ByAtMost.
+    #
+    # @see Matchi::Change::By For exact change validation
+    # @see Matchi::Change::ByAtMost For maximum change validation
+    # @see Matchi::Change::To For final value validation
     class ByAtLeast
-      # Initialize the matcher with an object and a block.
+      # Initialize the matcher with a minimum expected change and a state block.
       #
-      # @example
-      #   require "matchi/change/by_at_least"
+      # @api public
+      #
+      # @param expected [Numeric] The minimum 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 expected is negative
+      # @raise [ArgumentError] if no state block is provided
       #
-      #   object = []
+      # @return [ByAtLeast] a new instance of the matcher
       #
-      #   Matchi::Change::ByAtLeast.new(1) { object.length }
+      # @example With integer minimum
+      #   ByAtLeast.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 floating point minimum
+      #   ByAtLeast.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?
@@ -25,21 +107,30 @@ module Matchi
         @state    = state
       end
 
-      # Boolean comparison on the expected change by comparing the value
-      # before and after the code execution.
+      # Checks if the value changes by at least the expected amount.
       #
-      # @example
-      #   require "matchi/change/by_at_least"
+      # This method compares the value before and after executing the provided block,
+      # ensuring that the difference is greater than or equal to the expected minimum.
+      # This is useful when you want to verify that a change meets a minimum threshold.
+      #
+      # @api public
       #
-      #   object = []
+      # @yield [] Block that should cause the state change
+      # @yieldreturn [Object] The result of the block (not used)
       #
-      #   matcher = Matchi::Change::ByAtLeast.new(1) { object.length }
-      #   matcher.match? { object << "foo" } # => true
+      # @return [Boolean] true if the value changed by at least the expected amount
       #
-      # @yieldreturn [#object_id] The block of code to execute.
+      # @raise [ArgumentError] if no block is provided
       #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
+      # @example Basic usage
+      #   counter = 0
+      #   matcher = ByAtLeast.new(5) { counter }
+      #   matcher.match? { counter += 7 }  # => true   # Changed by more than minimum
+      #
+      # @example Edge case - exact minimum
+      #   items = []
+      #   matcher = ByAtLeast.new(2) { items.size }
+      #   matcher.match? { items.push(1, 2) }  # => true  # Changed by exactly minimum
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -50,9 +141,15 @@ 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
+      #   ByAtLeast.new(5).to_s    # => "change by at least 5"
+      #   ByAtLeast.new(2.5).to_s  # => "change by at least 2.5"
       def to_s
         "change by at least #{@expected.inspect}"
       end

data/lib/matchi/change/by_at_most.rb

@@ -2,44 +2,148 @@
 
 module Matchi
   class Change
-    # *Change by at most* matcher.
+    # Maximum delta matcher that verifies numeric changes don't exceed a limit.
+    #
+    # This matcher ensures that a numeric value changes by no more than the specified amount
+    # after executing a block of code. It's particularly useful when testing operations
+    # where you want to enforce an upper bound on changes, such as rate limiting,
+    # resource consumption, or controlled increments.
+    #
+    # @example Testing controlled collection growth
+    #   items = []
+    #   matcher = Matchi::Change::ByAtMost.new(2) { items.size }
+    #   matcher.match? { items.push(1) }             # => true   # Changed by less than limit
+    #   matcher.match? { items.push(1, 2) }          # => true   # Changed by exactly limit
+    #   matcher.match? { items.push(1, 2, 3) }       # => false  # Changed by more than limit
+    #
+    # @example Rate limiting
+    #   class RateLimiter
+    #     def initialize
+    #       @requests = 0
+    #     end
+    #
+    #     def process_batch(items)
+    #       items.each do |item|
+    #         break if @requests >= 3  # Rate limit
+    #         process_item(item)
+    #       end
+    #     end
+    #
+    #     private
+    #
+    #     def process_item(item)
+    #       @requests += 1
+    #       # Processing logic...
+    #     end
+    #
+    #     def requests
+    #       @requests
+    #     end
+    #   end
+    #
+    #   limiter = RateLimiter.new
+    #   matcher = Matchi::Change::ByAtMost.new(3) { limiter.requests }
+    #   matcher.match? { limiter.process_batch([1, 2, 3, 4, 5]) } # => true
+    #
+    # @example Resource consumption
+    #   class ResourcePool
+    #     attr_reader :used
+    #
+    #     def initialize
+    #       @used = 0
+    #     end
+    #
+    #     def allocate(requested)
+    #       available = 5 - @used  # Maximum pool size is 5
+    #       granted = [requested, available].min
+    #       @used += granted
+    #       granted
+    #     end
+    #   end
+    #
+    #   pool = ResourcePool.new
+    #   matcher = Matchi::Change::ByAtMost.new(2) { pool.used }
+    #   matcher.match? { pool.allocate(2) }  # => true
+    #   matcher.match? { pool.allocate(3) }  # => false
+    #
+    # @example Score adjustments
+    #   class GameScore
+    #     attr_reader :value
+    #
+    #     def initialize
+    #       @value = 100
+    #     end
+    #
+    #     def apply_penalty(amount)
+    #       max_penalty = 10
+    #       actual_penalty = [amount, max_penalty].min
+    #       @value -= actual_penalty
+    #     end
+    #   end
+    #
+    #   score = GameScore.new
+    #   matcher = Matchi::Change::ByAtMost.new(10) { -score.value }
+    #   matcher.match? { score.apply_penalty(5) }   # => true   # Small penalty
+    #   matcher.match? { score.apply_penalty(15) }  # => true   # Limited to max
+    #
+    # @note This matcher verifies maximum changes only. For exact changes, use By,
+    #   and for minimum changes, use ByAtLeast.
+    #
+    # @see Matchi::Change::By For exact change validation
+    # @see Matchi::Change::ByAtLeast For minimum change validation
+    # @see Matchi::Change::To For final value validation
     class ByAtMost
-      # Initialize the matcher with an object and a block.
+      # Initialize the matcher with a maximum allowed change and a state block.
       #
-      # @example
-      #   require "matchi/change/by_at_most"
+      # @api public
+      #
+      # @param expected [Numeric] The maximum 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 expected is negative
+      # @raise [ArgumentError] if no state block is provided
       #
-      #   object = []
+      # @return [ByAtMost] a new instance of the matcher
       #
-      #   Matchi::Change::ByAtMost.new(1) { object.length }
+      # @example With integer maximum
+      #   ByAtMost.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 floating point maximum
+      #   ByAtMost.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?
         raise ::ArgumentError, "expected must be non-negative" if expected.negative?
 
         @expected = expected
-        @state    = state
+        @state = state
       end
 
-      # Boolean comparison on the expected change by comparing the value
-      # before and after the code execution.
+      # Checks if the value changes by no more than the expected amount.
       #
-      # @example
-      #   require "matchi/change/by_at_most"
+      # This method compares the value before and after executing the provided block,
+      # ensuring that the absolute difference is less than or equal to the expected maximum.
+      # This is useful for enforcing upper bounds on state changes.
+      #
+      # @api public
       #
-      #   object = []
+      # @yield [] Block that should cause the state change
+      # @yieldreturn [Object] The result of the block (not used)
       #
-      #   matcher = Matchi::Change::ByAtMost.new(1) { object.length }
-      #   matcher.match? { object << "foo" } # => true
+      # @return [Boolean] true if the value changed by at most the expected amount
       #
-      # @yieldreturn [#object_id] The block of code to execute.
+      # @raise [ArgumentError] if no block is provided
       #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
+      # @example Basic usage with growth
+      #   users = []
+      #   matcher = ByAtMost.new(2) { users.size }
+      #   matcher.match? { users.push('alice') }  # => true
+      #
+      # @example With negative changes
+      #   stock = 10
+      #   matcher = ByAtMost.new(3) { stock }
+      #   matcher.match? { stock -= 2 }  # => true
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -50,9 +154,15 @@ 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
+      #   ByAtMost.new(5).to_s    # => "change by at most 5"
+      #   ByAtMost.new(2.5).to_s  # => "change by at most 2.5"
       def to_s
         "change by at most #{@expected.inspect}"
       end

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

@@ -3,44 +3,105 @@
 module Matchi
   class Change
     class From
-      # *Change from to* matcher.
+      # Value transition matcher that verifies both initial and final states of an operation.
+      #
+      # This matcher ensures that a value not only changes to an expected final state but also
+      # starts from a specific initial state. This is particularly useful when testing state
+      # transitions where both the starting and ending conditions are important, such as in
+      # workflow systems, state machines, or data transformations.
+      #
+      # @example Basic string transformation
+      #   text = "hello"
+      #   matcher = Matchi::Change::From::To.new("hello", "HELLO") { text.to_s }
+      #   matcher.match? { text.upcase! }   # => true
+      #   matcher.match? { text.reverse! }  # => false  # Wrong final state
+      #
+      #   text = "other"
+      #   matcher.match? { text.upcase! }   # => false  # Wrong initial state
+      #
+      # @example State machine transitions
+      #   class Order
+      #     attr_accessor :status
+      #     def initialize(status)
+      #       @status = status
+      #     end
+      #   end
+      #
+      #   order = Order.new(:pending)
+      #   matcher = Matchi::Change::From::To.new(:pending, :shipped) { order.status }
+      #   matcher.match? { order.status = :shipped }  # => true
+      #
+      # @example Complex object transformations
+      #   class User
+      #     attr_accessor :permissions
+      #     def initialize
+      #       @permissions = [:read]
+      #     end
+      #
+      #     def promote!
+      #       @permissions += [:write, :delete]
+      #     end
+      #   end
+      #
+      #   user = User.new
+      #   matcher = Matchi::Change::From::To.new(
+      #     [:read],
+      #     [:read, :write, :delete]
+      #   ) { user.permissions }
+      #   matcher.match? { user.promote! }  # => true
+      #
+      # @see Matchi::Change::To For checking only the final state
+      # @see Matchi::Change::By For checking numeric changes
       class To
-        # Initialize the matcher with two objects and a block.
+        # Initialize the matcher with expected initial and final values.
         #
-        # @example
-        #   require "matchi/change/from/to"
+        # @api public
+        #
+        # @param expected_init [#==] The expected initial value
+        # @param expected_new_value [#==] The expected final value
+        # @param state [Proc] Block that retrieves the current value
+        #
+        # @raise [ArgumentError] if no state block is provided
         #
-        #   object = "foo"
+        # @return [To] a new instance of the matcher
         #
-        #   Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
+        # @example With simple value
+        #   To.new("draft", "published") { document.status }
         #
-        # @param expected_init      [#object_id] An expected initial value.
-        # @param expected_new_value [#object_id] An expected new value.
-        # @param state              [Proc]       A block of code to execute to
-        #   get the state of the object.
+        # @example With complex state
+        #   To.new([:user], [:user, :admin]) { account.roles }
         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
+          @expected_init = expected_init
+          @expected = expected_new_value
+          @state = state
         end
 
-        # Boolean comparison on the expected change by comparing the value
-        # before and after the code execution.
+        # Verifies both initial and final states during a transition.
         #
-        # @example
-        #   require "matchi/change/from/to"
+        # This method first checks if the initial state matches the expected value,
+        # then executes the provided block and verifies the final state. The match
+        # fails if either the initial or final state doesn't match expectations.
+        #
+        # @api public
         #
-        #   object = "foo"
+        # @yield [] Block that should cause the state transition
+        # @yieldreturn [Object] The result of the block (not used)
         #
-        #   matcher = Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
-        #   matcher.match? { object.upcase! } # => true
+        # @return [Boolean] true if both initial and final states match expectations
         #
-        # @yieldreturn [#object_id] The block of code to execute.
+        # @raise [ArgumentError] if no block is provided
         #
-        # @return [Boolean] Comparison between the value before and after the
-        #   code execution.
+        # @example Basic usage
+        #   text = "hello"
+        #   matcher = To.new("hello", "HELLO") { text }
+        #   matcher.match? { text.upcase! }  # => true
+        #
+        # @example Failed initial state
+        #   text = "wrong"
+        #   matcher = To.new("hello", "HELLO") { text }
+        #   matcher.match? { text.upcase! }  # => false
         def match?
           raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -53,9 +114,15 @@ module Matchi
           @expected == value_after
         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
+        #   To.new("draft", "published").to_s
+        #   # => 'change from "draft" to "published"'
         def to_s
           "change from #{@expected_init.inspect} to #{@expected.inspect}"
         end

data/lib/matchi/change/from.rb

@@ -4,7 +4,32 @@ require_relative File.join("from", "to")
 
 module Matchi
   class Change
-    # *Change from to* wrapper.
+    # Initial state wrapper for building a value transition matcher.
+    #
+    # 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
     class From
       # Initialize the wrapper with an object and a block.
       #
@@ -27,6 +52,11 @@ module Matchi
 
       # 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"
       #

data/lib/matchi/change/to.rb

@@ -2,54 +2,103 @@
 
 module Matchi
   class Change
-    # *Change to* matcher.
+    # 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
+    #
+    # @see Matchi::Change::From::To For checking both initial and final states
+    # @see Matchi::Change::By For checking numeric changes
     class To
-      # Initialize the matcher with an object and a block.
+      # Initialize the matcher with an expected new value and a state block.
       #
-      # @example
-      #   require "matchi/change/to"
+      # @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
       #
-      #   object = "foo"
+      # @return [To] a new instance of the matcher
       #
-      #   Matchi::Change::To.new("FOO") { object.to_s }
+      # @example With simple value
+      #   To.new("test") { object.value }
       #
-      # @param expected [#object_id]  An expected new value.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
+      # @example With complex calculation
+      #   To.new(100) { object.items.count }
       def initialize(expected, &state)
         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.
+      # Checks if the state block returns the expected value after executing the provided block.
       #
-      # @example
-      #   require "matchi/change/to"
+      # 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
       #
-      #   object = "foo"
+      # @yield [] Block that should cause the state change
+      # @yieldreturn [Object] The result of the block (not used)
       #
-      #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
-      #   matcher.match? { object.upcase! } # => true
+      # @return [Boolean] true if the final state matches the expected value
       #
-      # @yieldreturn [#object_id] The block of code to execute.
+      # @raise [ArgumentError] if no block is provided
       #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
+      # @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
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
         yield
         value_after = @state.call
 
-        @expected == value_after
+        @expected.eql?(value_after)
       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
+      #   To.new("test").to_s # => 'change to "test"'
       def to_s
         "change to #{@expected.inspect}"
       end