state_machines 0.20.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa5d105c78cb53f15f42e8662dd7f8e0d0d5f8807b88dcbd8b4201f13718384
-  data.tar.gz: d761cedbe052c5c8829626e0875f54dce064f7156162119b4a040594b439068c
+  metadata.gz: fcd04394640ccea1429d2e121a46e2c705f8c16b2987b142858ad2f151c9c287
+  data.tar.gz: 58cfb25ff972b1b2802730d9084d3c3b27c59a82e694646ce676e38fc661cbb9
 SHA512:
-  metadata.gz: 37398c9ca5f2de7413dfb7a8a467984d0fc4d47f8367ea0747fec6d9c1eaca5a7c3439f37988c02dd8ce27622a9a9e54cf5cc0b2d84404f00f92a862c168bb23
-  data.tar.gz: 159022534eb3c308bc2f2c8e960f111053631d3e10adafc9ae8156c95a26165f48690c682229a577bdfecf918b335ebe5b6d57e82e095c924585ad8d11b9d1ee
+  metadata.gz: c9328eea4f9d8d9e57124571de54bb8f5160a044ef913d3e515bcaac933b7355ccf987c10699c71e94145f44bc1e2387342f350dcbff0100d76a5c1c06645321
+  data.tar.gz: 07c7bfad14f7ce103eec5d6dfa48a9117bc0a73cb5433447c4bf7b6cdea1b87b894a12ad6b85b5a0cb05d63dd68e291f980eeca40e60754c13d5b5c44a7fcf29

data/README.md

@@ -1,4 +1,5 @@
 ![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
+
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -9,15 +10,21 @@ State Machines adds support for creating state machines for attributes on any Ru
 
 Add this line to your application's Gemfile:
 
-    gem 'state_machines'
+```ruby
+gem 'state_machines'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install state_machines
+```sh
+gem install state_machines
+```
 
 ## Usage
 
@@ -38,11 +45,11 @@ Class definition:
 
 ```ruby
 class Vehicle
-  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
+  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy, :parking_meter_number
 
   state_machine :state, initial: :parked do
     before_transition parked: any - :parked, do: :put_on_seatbelt
-    
+
     after_transition on: :crash, do: :tow
     after_transition on: :repair, do: :fix
     after_transition any => :parked do |vehicle, transition|
@@ -61,6 +68,18 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
+    before_transition on: :park do |vehicle, transition|
+      # If using Rails:
+      # options = transition.args.extract_options!
+
+      options = transition.args.last.is_a?(Hash) ? transition.args.pop : {}
+      meter_number = options[:meter_number]
+
+      unless meter_number.nil?
+        vehicle.parking_meter_number = meter_number
+      end
+    end
+
     event :ignite do
       transition stalled: same, parked: :idling
     end
@@ -130,6 +149,7 @@ class Vehicle
     @seatbelt_on = false
     @time_used = 0
     @auto_shop_busy = true
+    @parking_meter_number = nil
     super() # NOTE: This *must* be called, otherwise states won't get initialized
   end
 
@@ -200,6 +220,11 @@ vehicle.park!                   # => StateMachines:InvalidTransition: Cannot tra
 vehicle.state?(:parked)         # => false
 vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
 
+# Transition callbacks can receive arguments
+vehicle.park(meter_number: '12345') # => true
+vehicle.parked?                     # => true
+vehicle.parking_meter_number        # => "12345"
+
 # Namespaced machines have uniquely-generated methods
 vehicle.alarm_state             # => 1
 vehicle.alarm_state_name        # => :active
@@ -256,30 +281,36 @@ vehicle.state_name              # => :parked
 
 ## Testing
 
-State Machines provides a `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+State Machines provides an optional `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+
+**Note: TestHelper is not required by default** - you must explicitly require it in your test files.
 
 ### Setup
 
-Include the test helper in your test class:
+First, require the test helper module, then include it in your test class:
 
 ```ruby
 # For Minitest
+require 'state_machines/test_helper'
+
 class VehicleTest < Minitest::Test
   include StateMachines::TestHelper
-  
+
   def test_initial_state
     vehicle = Vehicle.new
-    assert_state vehicle, :state, :parked
+    assert_sm_state vehicle, :parked
   end
 end
 
-# For RSpec  
+# For RSpec
+require 'state_machines/test_helper'
+
 RSpec.describe Vehicle do
   include StateMachines::TestHelper
-  
+
   it "starts in parked state" do
     vehicle = Vehicle.new
-    assert_state vehicle, :state, :parked
+    assert_sm_state vehicle, :parked
   end
 end
 ```
@@ -292,10 +323,17 @@ The TestHelper provides both basic assertions and comprehensive state machine-sp
 
 ```ruby
 vehicle = Vehicle.new
-assert_state vehicle, :state, :parked
-assert_can_transition vehicle, :ignite
-assert_cannot_transition vehicle, :shift_up
-assert_transition vehicle, :ignite, :state, :idling
+
+# New standardized API (all methods prefixed with assert_sm_)
+assert_sm_state(vehicle, :parked)                                    # Uses default :state machine
+assert_sm_state(vehicle, :parked, machine_name: :status)             # Specify machine explicitly
+assert_sm_can_transition(vehicle, :ignite)                           # Test transition capability
+assert_sm_cannot_transition(vehicle, :shift_up)                      # Test transition restriction
+assert_sm_transition(vehicle, :ignite, :idling)                      # Test actual transition
+
+# Multi-FSM examples
+assert_sm_state(vehicle, :inactive, machine_name: :insurance_state)  # Test insurance state
+assert_sm_can_transition(vehicle, :buy_insurance, machine_name: :insurance_state)
 ```
 
 #### Extended State Machine Assertions
@@ -308,7 +346,7 @@ vehicle = Vehicle.new
 assert_sm_states_list machine, [:parked, :idling, :stalled]
 assert_sm_initial_state machine, :parked
 
-# Event behavior  
+# Event behavior
 assert_sm_event_triggers vehicle, :ignite
 refute_sm_event_triggers vehicle, :shift_up
 assert_sm_event_raises_error vehicle, :invalid_event, StateMachines::InvalidTransition
@@ -317,8 +355,106 @@ assert_sm_event_raises_error vehicle, :invalid_event, StateMachines::InvalidTran
 assert_sm_state_persisted record, expected: :active
 ```
 
+#### Indirect Event Testing
+
+Test that methods trigger state machine events indirectly:
+
+```ruby
+# Minitest style
+vehicle = Vehicle.new
+vehicle.ignite  # Put in idling state
+
+# Test that a custom method triggers a specific event
+assert_sm_triggers_event(vehicle, :crash) do
+  vehicle.redline  # Custom method that calls crash! internally
+end
+
+# Test multiple events
+assert_sm_triggers_event(vehicle, [:crash, :emergency]) do
+  vehicle.emergency_stop
+end
+
+# Test on specific state machine (multi-FSM support)
+assert_sm_triggers_event(vehicle, :disable, machine_name: :alarm) do
+  vehicle.turn_off_alarm
+end
+```
+
+```ruby
+# RSpec style (coming soon with proper matcher support)
+RSpec.describe Vehicle do
+  include StateMachines::TestHelper
+
+  it "triggers crash when redlining" do
+    vehicle = Vehicle.new
+    vehicle.ignite
+
+    expect_to_trigger_event(vehicle, :crash) do
+      vehicle.redline
+    end
+  end
+end
+```
+
+#### Callback Definition Testing (TDD Support)
+
+Verify that callbacks are properly defined in your state machine:
+
+```ruby
+# Test after_transition callbacks
+assert_after_transition(Vehicle, on: :crash, do: :tow)
+assert_after_transition(Vehicle, from: :stalled, to: :parked, do: :log_repair)
+
+# Test before_transition callbacks
+assert_before_transition(Vehicle, from: :parked, do: :put_on_seatbelt)
+assert_before_transition(Vehicle, on: :ignite, if: :seatbelt_on?)
+
+# Works with machine instances too
+machine = Vehicle.state_machine(:state)
+assert_after_transition(machine, on: :crash, do: :tow)
+```
+
+#### Multiple State Machine Support
+
+The TestHelper fully supports objects with multiple state machines:
+
+```ruby
+# Example: StarfleetShip with 3 state machines
+ship = StarfleetShip.new
+
+# Test states on different machines
+assert_sm_state(ship, :docked, machine_name: :status)       # Main ship status
+assert_sm_state(ship, :down, machine_name: :shields)        # Shield system
+assert_sm_state(ship, :standby, machine_name: :weapons)     # Weapons system
+
+# Test transitions on specific machines
+assert_sm_transition(ship, :undock, :impulse, machine_name: :status)
+assert_sm_transition(ship, :raise_shields, :up, machine_name: :shields)
+assert_sm_transition(ship, :arm_weapons, :armed, machine_name: :weapons)
+
+# Test event triggering across multiple machines
+assert_sm_triggers_event(ship, :red_alert, machine_name: :status) do
+  ship.engage_combat_mode  # Custom method affecting multiple systems
+end
+
+assert_sm_triggers_event(ship, :raise_shields, machine_name: :shields) do
+  ship.engage_combat_mode
+end
+
+# Test callback definitions on specific machines
+shields_machine = StarfleetShip.state_machine(:shields)
+assert_before_transition(shields_machine, from: :down, to: :up, do: :power_up_shields)
+
+# Test persistence across multiple machines
+assert_sm_state_persisted(ship, "impulse", :status)
+assert_sm_state_persisted(ship, "up", :shields)
+assert_sm_state_persisted(ship, "armed", :weapons)
+```
+
 The test helper works with both Minitest and RSpec, automatically detecting your testing framework.
 
+**Note:** All methods use consistent keyword arguments with `machine_name:` as the last parameter, making the API intuitive and Grep-friendly.
+
 ## Additional Topics
 
 ### Explicit vs. Implicit Event Transitions
@@ -679,7 +815,7 @@ For RSpec testing, use the custom RSpec matchers:
 
 ## Contributing
 
-1. Fork it ( https://github.com/state-machines/state_machines/fork )
+1. Fork it ( <https://github.com/state-machines/state_machines/fork> )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/state_machines/branch.rb

@@ -8,7 +8,6 @@ module StateMachines
   # state of the transition match, in addition to if/unless conditionals for
   # an object's state.
   class Branch
-
     include EvalHelpers
 
     # The condition that must be met on an object
@@ -31,7 +30,7 @@ module StateMachines
     attr_reader :known_states
 
     # Creates a new branch
-    def initialize(options = {}) #:nodoc:
+    def initialize(options = {}) # :nodoc:
       # Build conditionals
       @if_condition = options.delete(:if)
       @unless_condition = options.delete(:unless)
@@ -39,9 +38,9 @@ module StateMachines
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
 
-      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
+      if (options.keys - %i[from to on except_from except_to except_on]).empty?
         # Explicit from/to requirements specified
-        @state_requirements = [{from: build_matcher(options, :from, :except_from), to: build_matcher(options, :to, :except_to)}]
+        @state_requirements = [{ from: build_matcher(options, :from, :except_from), to: build_matcher(options, :to, :except_to) }]
       else
         # Separate out the event requirement
         options.delete(:on)
@@ -51,7 +50,7 @@ module StateMachines
         @state_requirements = options.collect do |from, to|
           from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
           to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
-          {from: from, to: to}
+          { from: from, to: to }
         end
       end
 
@@ -59,7 +58,7 @@ module StateMachines
       # on the priority in which tracked states should be added.
       @known_states = []
       @state_requirements.each do |state_requirement|
-        [:from, :to].each { |option| @known_states |= state_requirement[option].values }
+        %i[from to].each { |option| @known_states |= state_requirement[option].values }
       end
     end
 
@@ -109,25 +108,27 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard matches with the if/unless
     #   conditionals defined for this branch.  Default is true.
     #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    #
     # == Examples
     #
     #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
     #
     #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
     #   branch.match(object, :on => :park)    # => nil
-    def match(object, query = {})
+    def match(object, query = {}, event_args = [])
       StateMachines::OptionsValidator.assert_valid_keys!(query, :from, :to, :on, :guard)
 
-      if (match = match_query(query)) && matches_conditions?(object, query)
-        match
-      end
+      return unless (match = match_query(query)) && matches_conditions?(object, query, event_args)
+
+      match
     end
 
     def draw(graph, event, valid_states, io = $stdout)
       machine.renderer.draw_branch(self, graph, event, valid_states, io)
     end
 
-  protected
+    protected
 
     # Builds a matcher strategy to use for the given options.  If neither a
     # whitelist nor a blacklist option is specified, then an AllMatcher is
@@ -168,7 +169,7 @@ module StateMachines
     # matching requirement is found, then it is returned.
     def match_states(query)
       state_requirements.detect do |state_requirement|
-        [:from, :to].all? { |option| matches_requirement?(query, option, state_requirement[option]) }
+        %i[from to].all? { |option| matches_requirement?(query, option, state_requirement[option]) }
       end
     end
 
@@ -179,11 +180,23 @@ module StateMachines
     end
 
     # Verifies that the conditionals for this branch evaluate to true for the
-    # given object
-    def matches_conditions?(object, query)
-      query[:guard] == false ||
-      Array(if_condition).all? { |condition| evaluate_method(object, condition) } &&
-      !Array(unless_condition).any? { |condition| evaluate_method(object, condition) }
+    # given object. Event arguments are passed to guards that accept multiple parameters.
+    def matches_conditions?(object, query, event_args = [])
+      case [query[:guard], if_condition, unless_condition]
+      in [false, _, _]
+        true
+      in [_, nil, nil]
+        true
+      in [_, if_conds, nil] if if_conds
+        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      in [_, nil, unless_conds] if unless_conds
+        Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      in [_, if_conds, unless_conds] if if_conds || unless_conds
+        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) } &&
+          Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      else
+        true
+      end
     end
   end
 end

data/lib/state_machines/callback.rb

@@ -124,7 +124,7 @@ module StateMachines
     # callback can be found in their attribute definitions.
     def initialize(type, *args, &block)
       @type = type
-      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless [:before, :after, :around, :failure].include?(type)
+      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless %i[before after around failure].include?(type)
 
       options = args.last.is_a?(Hash) ? args.pop : {}
       @methods = args
@@ -132,7 +132,7 @@ module StateMachines
       @methods << block if block_given?
       raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
 
-      options = {bind_to_object: self.class.bind_to_object, terminator: self.class.terminator}.merge(options)
+      options = { bind_to_object: self.class.bind_to_object, terminator: self.class.terminator }.merge(options)
 
       # Proxy lambda blocks so that they're bound to the object
       bind_to_object = options.delete(:bind_to_object)
@@ -156,16 +156,16 @@ module StateMachines
     #
     # If a terminator has been configured and it matches the result from the
     # evaluated method, then the callback chain should be halted.
-    def call(object, context = {}, *args, &block)
+    def call(object, context = {}, *, &)
       if @branch.matches?(object, context)
-        run_methods(object, context, 0, *args, &block)
+        run_methods(object, context, 0, *, &)
         true
       else
         false
       end
     end
 
-  private
+    private
 
     # Runs all of the methods configured for this callback.
     #
@@ -179,7 +179,7 @@ module StateMachines
     def run_methods(object, context = {}, index = 0, *args, &block)
       if type == :around
         current_method = @methods[index]
-        if  current_method
+        if current_method
           yielded = false
           evaluate_method(object, current_method, *args) do
             yielded = true
@@ -187,13 +187,13 @@ module StateMachines
           end
 
           throw :halt unless yielded
-        else
-          yield if block_given?
+        elsif block_given?
+          yield
         end
       else
         @methods.each do |method|
           result = evaluate_method(object, method, *args)
-          throw :halt if @terminator && @terminator.call(result)
+          throw :halt if @terminator&.call(result)
         end
       end
     end
@@ -206,13 +206,12 @@ module StateMachines
       arity += 1 if arity >= 0 # Make sure the object gets passed
       arity += 1 if arity == 1 && type == :around # Make sure the block gets passed
 
-      method = lambda { |object, *args| object.instance_exec(*args, &block) }
-
+      method = ->(object, *args) { object.instance_exec(*args, &block) }
 
       # Proxy arity to the original block
       (
-      class << method;
-        self;
+      class << method
+        self
       end).class_eval do
         define_method(:arity) { arity }
       end

data/lib/state_machines/core.rb

@@ -24,7 +24,6 @@ require 'state_machines/transition_collection'
 require 'state_machines/branch'
 
 require 'state_machines/helper_module'
-require 'state_machines/state'
 require 'state_machines/callback'
 require 'state_machines/node_collection'
 

data/lib/state_machines/error.rb

@@ -6,7 +6,7 @@ module StateMachines
     # The object that failed
     attr_reader :object
 
-    def initialize(object, message = nil) #:nodoc:
+    def initialize(object, message = nil) # :nodoc:
       @object = object
 
       super(message)
@@ -49,12 +49,13 @@ module StateMachines
     # The event that was attempted to be run
     attr_reader :event
 
-    def initialize(object, event_name) #:nodoc:
+    def initialize(object, event_name) # :nodoc:
       @event = event_name
 
       super(object, "#{event.inspect} is an unknown state machine event")
     end
   end
+
   # An invalid transition was attempted
   class InvalidTransition < Error
     # The machine attempting to be transitioned
@@ -63,7 +64,7 @@ module StateMachines
     # The current state value for the machine
     attr_reader :from
 
-    def initialize(object, machine, event) #:nodoc:
+    def initialize(object, machine, event) # :nodoc:
       @machine = machine
       @from_state = machine.states.match!(object)
       @from = machine.read(object, :state)
@@ -101,7 +102,7 @@ module StateMachines
     # The set of events that failed the transition(s)
     attr_reader :events
 
-    def initialize(object, events) #:nodoc:
+    def initialize(object, events) # :nodoc:
       @events = events
 
       super(object, "Cannot run events in parallel: #{events * ', '}")