matchi 4.2.0 → 6.0.0

data/lib/matchi/change/by_at_least.rb

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # 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 a minimum expected change and a state block.
-      #
-      # @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
-      #
-      # @return [ByAtLeast] a new instance of the matcher
-      #
-      # @example With integer minimum
-      #   ByAtLeast.new(5) { counter.value }
-      #
-      # @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?
-        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
-
-        @expected = expected
-        @state    = state
-      end
-
-      # Checks if the value changes by at least the expected amount.
-      #
-      # 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
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by at least the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @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?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected <= (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @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
-    end
-  end
-end

data/lib/matchi/change/by_at_most.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # 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 a maximum allowed change and a state block.
-      #
-      # @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
-      #
-      # @return [ByAtMost] a new instance of the matcher
-      #
-      # @example With integer maximum
-      #   ByAtMost.new(5) { counter.value }
-      #
-      # @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
-      end
-
-      # Checks if the value changes by no more than the expected amount.
-      #
-      # 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
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by at most the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @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?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected >= (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @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
-    end
-  end
-end

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

@@ -1,132 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    class From
-      # 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 expected initial and final values.
-        #
-        # @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
-        #
-        # @return [To] a new instance of the matcher
-        #
-        # @example With simple value
-        #   To.new("draft", "published") { document.status }
-        #
-        # @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
-        end
-
-        # Verifies both initial and final states during a transition.
-        #
-        # 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
-        #
-        # @yield [] Block that should cause the state transition
-        # @yieldreturn [Object] The result of the block (not used)
-        #
-        # @return [Boolean] true if both initial and final states match expectations
-        #
-        # @raise [ArgumentError] if no block is provided
-        #
-        # @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?
-
-          value_before = @state.call
-          return false unless @expected_init == value_before
-
-          yield
-          value_after = @state.call
-
-          @expected == value_after
-        end
-
-        # Returns a human-readable description of the matcher.
-        #
-        # @api public
-        #
-        # @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
-      end
-    end
-  end
-end