state_machines 0.6.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d22dcf0b70eca7cbf9a6894d592609874cfdef01474b70a2226018c0e8966b7
-  data.tar.gz: 9a9bed680181f45bc613649bf4f3b90a4ea1e198e8fb19f734d264c7652e5051
+  metadata.gz: 5c732f34387da18f4dc1c3d78cad1fbb111cc88d06d9fe3edcda912adc5e655a
+  data.tar.gz: ef0079a89a1b0e4ddea45dd4a79e11de12740d4eb0c2aa98ad95b5ca7ae3eab8
 SHA512:
-  metadata.gz: d1446488cbb427e407611d2cba2e571401931a4a20f9f8655e14ebf896990468d24a94a02ba708627db8beb3a3821ac481b220551f0d0c02e366ba3d78112da4
-  data.tar.gz: 4949561813ac58b6442611d37083091b6c4532f41227f3f9f0999bbecc18c18aacc458f9aa6d6570b5855b6a30a24394d421e6b6012dfa4ebed638a642da82f3
+  metadata.gz: d71a5bd20b0de0b19e4684b4251954d0cf648e5454b57af96555372bbdee59a9ac855bb27d182e018f87ffa0525b5cd3daff5c3ce53c483f3dec4954d076a331
+  data.tar.gz: 179e0cb6c2a31d14c4078820d254ce35e26d9b5aaa2646e4766b842127411cf49e5ad697d0a764ba79a0036bce5dc288ef113b8bef57c3cac64de8816a23f49b

data/README.md

@@ -1,5 +1,4 @@
 ![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
-[![Code Climate](https://codeclimate.com/github/state-machines/state_machines.svg)](https://codeclimate.com/github/state-machines/state_machines)
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -43,7 +42,7 @@ class Vehicle
 
   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|
@@ -255,6 +254,182 @@ vehicle.state_name              # => :parked
 # vehicle.state = :parked
 ```
 
+## Testing
+
+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
+
+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_sm_state vehicle, :parked
+  end
+end
+
+# For RSpec
+require 'state_machines/test_helper'
+
+RSpec.describe Vehicle do
+  include StateMachines::TestHelper
+
+  it "starts in parked state" do
+    vehicle = Vehicle.new
+    assert_sm_state vehicle, :parked
+  end
+end
+```
+
+### Available Assertions
+
+The TestHelper provides both basic assertions and comprehensive state machine-specific assertions with `sm_` prefixes:
+
+#### Basic Assertions
+
+```ruby
+vehicle = Vehicle.new
+
+# 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
+
+```ruby
+machine = Vehicle.state_machine(:state)
+vehicle = Vehicle.new
+
+# State configuration
+assert_sm_states_list machine, [:parked, :idling, :stalled]
+assert_sm_initial_state machine, :parked
+
+# 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
+
+# Persistence (with ActiveRecord integration)
+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
@@ -428,7 +603,7 @@ easily migrate from a different library, you can do so as shown below:
 ```ruby
 class Vehicle
   state_machine initial: :parked do
-    ...
+    # ...
 
     state :parked do
       transition to: :idling, :on => [:ignite, :shift_up], if: :seatbelt_on?
@@ -464,7 +639,7 @@ example below:
 ```ruby
 class Vehicle
   state_machine initial: :parked do
-    ...
+    # ...
 
     transition parked: :idling, :on => [:ignite, :shift_up]
     transition first_gear: :second_gear, second_gear: :third_gear, on: :shift_up
@@ -496,12 +671,31 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
-    ...
+    # ...
   end
 end
 ```
 
-However, there may be cases where the definition of a state machine is **dynamic**.
+#### Draw state machines
+
+State machines includes a default STDIORenderer for debugging state machines without external dependencies.
+This renderer can be used to visualize the state machine in the console.
+
+To use the renderer, simply call the `draw` method on the state machine:
+
+```ruby
+Vehicle.state_machine.draw # Outputs the state machine diagram to the console
+```
+
+You can customize the output by passing in options to the `draw` method, such as the output stream:
+
+```ruby
+Vehicle.state_machine.draw(io: $stderr) # Outputs the state machine diagram to stderr
+```
+
+#### Dynamic definitions
+
+There may be cases where the definition of a state machine is **dynamic**.
 This means that you don't know the possible states or events for a machine until
 runtime.  For example, you may allow users in your application to manage the
 state machine of a project or task in your system.  This means that the list of
@@ -580,22 +774,19 @@ transitions.
 
 Ruby versions officially supported and tested:
 
-* Ruby (MRI) 2.6.0+
-* JRuby
-* Rubinius
+* Ruby (MRI) 3.0.0+
 
 For graphing state machine:
 
-* [state_machines-graphviz](http://github.com/state-machines/state_machines-graphviz)
+* [state_machines-graphviz](https://github.com/state-machines/state_machines-graphviz)
 
 For documenting state machines:
 
-* [state_machines-yard](http://github.com/state-machines/state_machines-yard)
-
+* [state_machines-yard](https://github.com/state-machines/state_machines-yard)
 
-## TODO
+For RSpec testing, use the custom RSpec matchers:
 
-* Add matchers/assertions for rspec and minitest
+* [state_machines-rspec](https://github.com/state-machines/state_machines-rspec)
 
 ## Contributing
 

data/lib/state_machines/branch.rb

@@ -1,10 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a set of requirements that must be met in order for a transition
   # or callback to occur.  Branches verify that the event, from state, and to
   # 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
@@ -27,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)
@@ -35,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)
@@ -47,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
 
@@ -55,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
 
@@ -112,24 +115,24 @@ module StateMachines
     #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
     #   branch.match(object, :on => :park)    # => nil
     def match(object, query = {})
-      query.assert_valid_keys(:from, :to, :on, :guard)
+      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)
+
+      match
     end
 
-    def draw(graph, event, valid_states)
-     fail NotImplementedError
+    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
     # built.
     def build_matcher(options, whitelist_option, blacklist_option)
-      options.assert_exclusive_keys(whitelist_option, blacklist_option)
+      StateMachines::OptionsValidator.assert_exclusive_keys!(options, whitelist_option, blacklist_option)
 
       if options.include?(whitelist_option)
         value = options[whitelist_option]
@@ -164,7 +167,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
 
@@ -178,8 +181,8 @@ module StateMachines
     # 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) }
+        (Array(if_condition).all? { |condition| evaluate_method(object, condition) } &&
+          !Array(unless_condition).any? { |condition| evaluate_method(object, condition) })
     end
   end
 end

data/lib/state_machines/callback.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'state_machines/branch'
 require 'state_machines/eval_helpers'
 
@@ -122,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
@@ -130,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)
@@ -154,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.
     #
@@ -177,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
@@ -185,8 +187,8 @@ module StateMachines
           end
 
           throw :halt unless yielded
-        else
-          yield if block_given?
+        elsif block_given?
+          yield
         end
       else
         @methods.each do |method|
@@ -204,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

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 # Load all of the core implementation required to use state_machine.  This
 # includes:
 # * StateMachines::MacroMethods which adds the state_machine DSL to your class
 # * A set of initializers for setting state_machine defaults based on the current
 #   running environment (such as within Rails)
-require 'state_machines/assertions'
 require 'state_machines/error'
 
 require 'state_machines/extensions'
@@ -23,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'
 
@@ -40,4 +40,4 @@ require 'state_machines/path_collection'
 require 'state_machines/machine'
 require 'state_machines/machine_collection'
 
-require 'state_machines/macro_methods'
+require 'state_machines/macro_methods'

data/lib/state_machines/core_ext/class/state_machine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Class.class_eval do
   include StateMachines::MacroMethods
 end

data/lib/state_machines/core_ext.rb

@@ -1,2 +1,4 @@
+# frozen_string_literal: true
+
 # Loads all of the extensions to be made to Ruby core classes
 require 'state_machines/core_ext/class/state_machine'

data/lib/state_machines/error.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module StateMachines
   # An error occurred during a state machine invocation
   class Error < StandardError
     # The object that failed
     attr_reader :object
 
-    def initialize(object, message = nil) #:nodoc:
+    def initialize(object, message = nil) # :nodoc:
       @object = object
 
       super(message)
@@ -47,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
@@ -61,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)
@@ -99,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 * ', '}")