state_machines 0.10.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39c8073bdf33aff2e34bfc3403db686c7d6e4344f158e144cb881230b10d9597
-  data.tar.gz: 150e14164e42addded79421e90456de2f60b4c451c743ee31a8eb2227d91896b
+  metadata.gz: 5c732f34387da18f4dc1c3d78cad1fbb111cc88d06d9fe3edcda912adc5e655a
+  data.tar.gz: ef0079a89a1b0e4ddea45dd4a79e11de12740d4eb0c2aa98ad95b5ca7ae3eab8
 SHA512:
-  metadata.gz: 34af008f9378c058a199dd05d3204df5d995466f7db126589a8614d540bb636ce08c42f38796504753be8414431623e02b30c10d772fc2d524d4a2f9f4ba58e2
-  data.tar.gz: a64f178f0f5ce8e13139b871c3cd351570df7c665f43338201225ff27d2482fe3cb3e1619f79e01544d4f9b3341bb9e589db7a659717e4975312684b6fd0ee82
+  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

data/lib/state_machines/branch.rb

@@ -1,12 +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
@@ -29,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)
@@ -37,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)
@@ -49,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
 
@@ -57,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
 
@@ -114,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, 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]
@@ -166,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
 
@@ -180,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

@@ -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,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|
@@ -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

@@ -5,7 +5,6 @@
 # * 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'
@@ -25,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'
 
@@ -42,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/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 * ', '}")

data/lib/state_machines/eval_helpers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'syntax_validator'
+
 module StateMachines
   # Provides a set of helper methods for evaluating methods within the context
   # of an object.
@@ -52,64 +54,100 @@ module StateMachines
     #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
-    def evaluate_method(object, method, *args, **kwargs, &block)
+    def evaluate_method(object, method, *args, **, &block)
       case method
-        when Symbol
-          klass = (class << object; self; end)
-          args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
-          object.send(method, *args, **kwargs, &block)
-        when Proc
-          args.unshift(object)
-          arity = method.arity
-          # Handle blocks for Procs
-          if block_given? && arity != 0
-            if [1, 2].include?(arity)
-              # Force the block to be either the only argument or the 2nd one
-              # after the object (may mean additional arguments get discarded)
-              args = args[0, arity - 1] + [block]
-            else
-              # Tack the block to the end of the args
-              args << block
-            end
+      when Symbol
+        klass = (class << object; self; end)
+        args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
+        object.send(method, *args, **, &block)
+      when Proc
+        args.unshift(object)
+        arity = method.arity
+        # Handle blocks for Procs
+        if block_given? && arity != 0
+          if [1, 2].include?(arity)
+            # Force the block to be either the only argument or the second one
+            # after the object (may mean additional arguments get discarded)
+            args = args[0, arity - 1] + [block]
           else
-            # These method types are only called with 0, 1, or n arguments
-            args = args[0, arity] if [0, 1].include?(arity)
+            # insert the block to the end of the args
+            args << block
           end
+        elsif [0, 1].include?(arity)
+          # These method types are only called with 0, 1, or n arguments
+          args = args[0, arity]
+        end
 
         # Call the Proc with the arguments
-        method.call(*args, **kwargs)
+        method.call(*args, **)
+
+      when Method
+        args.unshift(object)
+        arity = method.arity
 
-        when Method
-          args.unshift(object)
-          arity = method.arity
+        # Methods handle blocks via &block, not as arguments
+        # Only limit arguments if necessary based on arity
+        args = args[0, arity] if [0, 1].include?(arity)
 
-          # Methods handle blocks via &block, not as arguments
-          # Only limit arguments if necessary based on arity
-          args = args[0, arity] if [0, 1].include?(arity)
+        # Call the Method with the arguments and pass the block
+        method.call(*args, **, &block)
+      when String
+        # Input validation for string evaluation
+        validate_eval_string(method)
 
-          # Call the Method with the arguments and pass the block
-          method.call(*args, **kwargs, &block)
-        when String
-          if block_given?
-            if StateMachines::Transition.pause_supported?
-              eval(method, object.instance_eval { binding }, &block)
-            else
-              # Support for JRuby and Truffle Ruby, which don't support binding blocks
-              eigen = class << object; self; end
-              eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        if block_given?
+          if StateMachines::Transition.pause_supported?
+            eval(method, object.instance_eval { binding }, &block)
+          else
+            # Support for JRuby and Truffle Ruby, which don't support binding blocks
+            # Need to check with @headius, if jruby 10 does now.
+            eigen = class << object; self; end
+            eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
                   def __temp_eval_method__(*args, &b)
                     #{method}
                   end
-                RUBY
-              result = object.__temp_eval_method__(*args, &block)
-              eigen.send(:remove_method, :__temp_eval_method__)
-              result
-            end
-          else
-            eval(method, object.instance_eval { binding })
+            RUBY
+            result = object.__temp_eval_method__(*args, &block)
+            eigen.send(:remove_method, :__temp_eval_method__)
+            result
           end
         else
-          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
+          eval(method, object.instance_eval { binding })
+        end
+      else
+        raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
+      end
+    end
+
+    private
+
+    # Validates string input before eval to prevent code injection
+    # This is a basic safety check - not foolproof security
+    def validate_eval_string(method_string)
+      # Check for obviously dangerous patterns
+      dangerous_patterns = [
+        /`.*`/,           # Backticks (shell execution)
+        /system\s*\(/,    # System calls
+        /exec\s*\(/,      # Exec calls
+        /eval\s*\(/,      # Nested eval
+        /require\s+['"]/, # Require statements
+        /load\s+['"]/, # Load statements
+        /File\./,         # File operations
+        /IO\./,           # IO operations
+        /Dir\./,          # Directory operations
+        /Kernel\./        # Kernel operations
+      ]
+
+      dangerous_patterns.each do |pattern|
+        raise SecurityError, "Potentially dangerous code detected in eval string: #{method_string.inspect}" if method_string.match?(pattern)
+      end
+
+      # Basic syntax validation - but allow yield since it's valid in block context
+      begin
+        test_code = method_string.include?('yield') ? "def dummy_method; #{method_string}; end" : method_string
+        SyntaxValidator.validate!(test_code, '(eval)')
+      rescue SyntaxError => e
+        raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
       end
     end
   end