state_machines 0.20.0 → 0.31.0

data/lib/state_machines/test_helper.rb

@@ -29,17 +29,30 @@ module StateMachines
     # Assert that an object is in a specific state for a given state machine
     #
     # @param object [Object] The object with state machines
-    # @param machine_name [Symbol] The name of the state machine
     # @param expected_state [Symbol] The expected state
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
     # @param message [String, nil] Custom failure message
     # @return [void]
     # @raise [AssertionError] If the state doesn't match
     #
     # @example
     #   user = User.new
-    #   assert_state(user, :status, :active)
-    def assert_state(object, machine_name, expected_state, message = nil)
-      actual = object.send("#{machine_name}_name")
+    #   assert_sm_state(user, :active)                              # Uses default :state machine
+    #   assert_sm_state(user, :active, machine_name: :status)       # Uses :status machine
+    def assert_sm_state(object, expected_state, machine_name: :state, message: nil)
+      name_method = "#{machine_name}_name"
+
+      # Handle the case where machine_name doesn't have a corresponding _name method
+      unless object.respond_to?(name_method)
+        available_machines = begin
+          object.class.state_machines.keys
+        rescue StandardError
+          []
+        end
+        raise ArgumentError, "No state machine '#{machine_name}' found. Available machines: #{available_machines.inspect}"
+      end
+
+      actual = object.send(name_method)
       default_message = "Expected #{object.class}##{machine_name} to be #{expected_state}, but was #{actual}"
 
       if defined?(::Minitest)
@@ -55,16 +68,30 @@ module StateMachines
     #
     # @param object [Object] The object with state machines
     # @param event [Symbol] The event name
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
     # @param message [String, nil] Custom failure message
     # @return [void]
     # @raise [AssertionError] If the transition is not available
     #
     # @example
     #   user = User.new
-    #   assert_can_transition(user, :activate)
-    def assert_can_transition(object, event, message = nil)
-      can_method = "can_#{event}?"
-      default_message = "Expected to be able to trigger event :#{event}, but #{can_method} returned false"
+    #   assert_sm_can_transition(user, :activate)                         # Uses default :state machine
+    #   assert_sm_can_transition(user, :activate, machine_name: :status)  # Uses :status machine
+    def assert_sm_can_transition(object, event, machine_name: :state, message: nil)
+      # Try different method naming patterns
+      possible_methods = [
+        "can_#{event}?",                    # Default state machine or non-namespaced
+        "can_#{event}_#{machine_name}?"     # Namespaced events
+      ]
+
+      can_method = possible_methods.find { |method| object.respond_to?(method) }
+
+      unless can_method
+        available_methods = object.methods.grep(/^can_.*\?$/).sort
+        raise ArgumentError, "No transition method found for event :#{event} on machine :#{machine_name}. Available methods: #{available_methods.first(10).inspect}"
+      end
+
+      default_message = "Expected to be able to trigger event :#{event} on #{machine_name}, but #{can_method} returned false"
 
       if defined?(::Minitest)
         assert object.send(can_method), message || default_message
@@ -79,16 +106,30 @@ module StateMachines
     #
     # @param object [Object] The object with state machines
     # @param event [Symbol] The event name
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
     # @param message [String, nil] Custom failure message
     # @return [void]
     # @raise [AssertionError] If the transition is available
     #
     # @example
     #   user = User.new
-    #   assert_cannot_transition(user, :delete)
-    def assert_cannot_transition(object, event, message = nil)
-      can_method = "can_#{event}?"
-      default_message = "Expected not to be able to trigger event :#{event}, but #{can_method} returned true"
+    #   assert_sm_cannot_transition(user, :delete)                         # Uses default :state machine
+    #   assert_sm_cannot_transition(user, :delete, machine_name: :status)  # Uses :status machine
+    def assert_sm_cannot_transition(object, event, machine_name: :state, message: nil)
+      # Try different method naming patterns
+      possible_methods = [
+        "can_#{event}?",                    # Default state machine or non-namespaced
+        "can_#{event}_#{machine_name}?"     # Namespaced events
+      ]
+
+      can_method = possible_methods.find { |method| object.respond_to?(method) }
+
+      unless can_method
+        available_methods = object.methods.grep(/^can_.*\?$/).sort
+        raise ArgumentError, "No transition method found for event :#{event} on machine :#{machine_name}. Available methods: #{available_methods.first(10).inspect}"
+      end
+
+      default_message = "Expected not to be able to trigger event :#{event} on #{machine_name}, but #{can_method} returned true"
 
       if defined?(::Minitest)
         refute object.send(can_method), message || default_message
@@ -103,18 +144,19 @@ module StateMachines
     #
     # @param object [Object] The object with state machines
     # @param event [Symbol] The event to trigger
-    # @param machine_name [Symbol] The name of the state machine
     # @param expected_state [Symbol] The expected state after transition
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
     # @param message [String, nil] Custom failure message
     # @return [void]
     # @raise [AssertionError] If the transition fails or results in wrong state
     #
     # @example
     #   user = User.new
-    #   assert_transition(user, :activate, :status, :active)
-    def assert_transition(object, event, machine_name, expected_state, message = nil)
+    #   assert_sm_transition(user, :activate, :active)                           # Uses default :state machine
+    #   assert_sm_transition(user, :activate, :active, machine_name: :status)    # Uses :status machine
+    def assert_sm_transition(object, event, expected_state, machine_name: :state, message: nil)
       object.send("#{event}!")
-      assert_state(object, machine_name, expected_state, message)
+      assert_sm_state(object, expected_state, machine_name: machine_name, message: message)
     end
 
     # === Extended State Machine Assertions ===
@@ -205,11 +247,11 @@ module StateMachines
     end
     alias assert_sm_transition_not_allowed refute_sm_transition_allowed
 
-    def assert_sm_event_triggers(object, event, message = nil)
-      initial_state = object.state
+    def assert_sm_event_triggers(object, event, machine_name = :state, message = nil)
+      initial_state = object.send(machine_name)
       object.send("#{event}!")
-      state_changed = initial_state != object.state
-      default_message = "Expected event #{event} to trigger state change"
+      state_changed = initial_state != object.send(machine_name)
+      default_message = "Expected event #{event} to trigger state change on #{machine_name}"
 
       if defined?(::Minitest)
         assert state_changed, message || default_message
@@ -220,12 +262,12 @@ module StateMachines
       end
     end
 
-    def refute_sm_event_triggers(object, event, message = nil)
-      initial_state = object.state
+    def refute_sm_event_triggers(object, event, machine_name = :state, message = nil)
+      initial_state = object.send(machine_name)
       begin
         object.send("#{event}!")
-        state_unchanged = initial_state == object.state
-        default_message = "Expected event #{event} to not trigger state change"
+        state_unchanged = initial_state == object.send(machine_name)
+        default_message = "Expected event #{event} to not trigger state change on #{machine_name}"
 
         if defined?(::Minitest)
           assert state_unchanged, message || default_message
@@ -288,10 +330,26 @@ module StateMachines
     end
     alias assert_sm_callback_not_executed refute_sm_callback_executed
 
-    def assert_sm_state_persisted(record, expected:, message: nil)
+    # Assert that a record's state is persisted correctly for a specific state machine
+    #
+    # @param record [Object] The record to check (should respond to reload)
+    # @param expected [String, Symbol] The expected persisted state
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the persisted state doesn't match
+    #
+    # @example
+    #   # Default state machine
+    #   assert_sm_state_persisted(user, "active")
+    #
+    #   # Specific state machine
+    #   assert_sm_state_persisted(ship, "up", :shields)
+    #   assert_sm_state_persisted(ship, "armed", :weapons)
+    def assert_sm_state_persisted(record, expected, machine_name = :state, message = nil)
       record.reload if record.respond_to?(:reload)
-      actual_state = record.state
-      default_message = "Expected persisted state #{expected} but got #{actual_state}"
+      actual_state = record.send(machine_name)
+      default_message = "Expected persisted state #{expected} for #{machine_name} but got #{actual_state}"
 
       if defined?(::Minitest)
         assert_equal expected, actual_state, message || default_message
@@ -301,5 +359,210 @@ module StateMachines
         raise default_message unless expected == actual_state
       end
     end
+
+    # Assert that executing a block triggers one or more expected events
+    #
+    # @param object [Object] The object with state machines
+    # @param expected_events [Symbol, Array<Symbol>] The event(s) expected to be triggered
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the expected events were not triggered
+    #
+    # @example
+    #   # Single event
+    #   assert_sm_triggers_event(vehicle, :crash) { vehicle.redline }
+    #
+    #   # Multiple events
+    #   assert_sm_triggers_event(vehicle, [:crash, :emergency]) { vehicle.emergency_stop }
+    #
+    #   # Specific machine
+    #   assert_sm_triggers_event(vehicle, :disable, machine_name: :alarm) { vehicle.turn_off_alarm }
+    def assert_sm_triggers_event(object, expected_events, machine_name: :state, message: nil)
+      expected_events = Array(expected_events)
+      triggered_events = []
+
+      # Get the state machine
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "No state machine found for #{machine_name}" unless machine
+
+      # Save original callbacks to restore later
+      machine.callbacks[:before].dup
+
+      # Add a temporary callback to track triggered events
+      temp_callback = machine.before_transition do |_obj, transition|
+        triggered_events << transition.event if transition.event
+      end
+
+      begin
+        # Execute the block
+        yield
+
+        # Check if expected events were triggered
+        missing_events = expected_events - triggered_events
+        extra_events = triggered_events - expected_events
+
+        unless missing_events.empty? && extra_events.empty?
+          default_message = "Expected events #{expected_events.inspect} to be triggered, but got #{triggered_events.inspect}"
+          default_message += ". Missing: #{missing_events.inspect}" if missing_events.any?
+          default_message += ". Extra: #{extra_events.inspect}" if extra_events.any?
+
+          if defined?(::Minitest)
+            assert false, message || default_message
+          elsif defined?(::RSpec)
+            raise message || default_message
+          else
+            raise default_message
+          end
+        end
+      ensure
+        # Restore original callbacks by removing the temporary one
+        machine.callbacks[:before].delete(temp_callback)
+      end
+    end
+
+    # Assert that a before_transition callback is defined with expected arguments
+    #
+    # @param machine_or_class [StateMachines::Machine, Class] The machine or class to check
+    # @param options [Hash] Expected callback options (on:, from:, to:, do:, if:, unless:)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the callback is not defined
+    #
+    # @example
+    #   # Check for specific transition callback
+    #   assert_before_transition(Vehicle, on: :crash, do: :emergency_stop)
+    #
+    #   # Check with from/to states
+    #   assert_before_transition(Vehicle.state_machine, from: :parked, to: :idling, do: :start_engine)
+    #
+    #   # Check with conditions
+    #   assert_before_transition(Vehicle, on: :ignite, if: :seatbelt_on?)
+    def assert_before_transition(machine_or_class, options = {}, message = nil)
+      _assert_transition_callback(:before, machine_or_class, options, message)
+    end
+
+    # Assert that an after_transition callback is defined with expected arguments
+    #
+    # @param machine_or_class [StateMachines::Machine, Class] The machine or class to check
+    # @param options [Hash] Expected callback options (on:, from:, to:, do:, if:, unless:)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the callback is not defined
+    #
+    # @example
+    #   # Check for specific transition callback
+    #   assert_after_transition(Vehicle, on: :crash, do: :tow)
+    #
+    #   # Check with from/to states
+    #   assert_after_transition(Vehicle.state_machine, from: :stalled, to: :parked, do: :log_repair)
+    def assert_after_transition(machine_or_class, options = {}, message = nil)
+      _assert_transition_callback(:after, machine_or_class, options, message)
+    end
+
+    # RSpec-style aliases for event triggering (for consistency with RSpec expectations)
+    alias expect_to_trigger_event assert_sm_triggers_event
+    alias have_triggered_event assert_sm_triggers_event
+
+    private
+
+    # Internal helper for checking transition callbacks
+    def _assert_transition_callback(callback_type, machine_or_class, options, message)
+      # Get the machine
+      machine = machine_or_class.is_a?(StateMachines::Machine) ? machine_or_class : machine_or_class.state_machine
+      raise ArgumentError, 'No state machine found' unless machine
+
+      callbacks = machine.callbacks[callback_type] || []
+
+      # Extract expected conditions
+      expected_event = options[:on]
+      expected_from = options[:from]
+      expected_to = options[:to]
+      expected_method = options[:do]
+      expected_if = options[:if]
+      expected_unless = options[:unless]
+
+      # Find matching callback
+      matching_callback = callbacks.find do |callback|
+        branch = callback.branch
+
+        # Check event requirement
+        if expected_event
+          event_requirement = branch.event_requirement
+          event_matches = if event_requirement && event_requirement.respond_to?(:values)
+                            event_requirement.values.include?(expected_event)
+                          else
+                            false
+                          end
+          next false unless event_matches
+        end
+
+        # Check state requirements (from/to)
+        if expected_from || expected_to
+          state_matches = false
+          branch.state_requirements.each do |req|
+            from_matches = !expected_from || (req[:from] && req[:from].respond_to?(:values) && req[:from].values.include?(expected_from))
+            to_matches = !expected_to || (req[:to] && req[:to].respond_to?(:values) && req[:to].values.include?(expected_to))
+
+            if from_matches && to_matches
+              state_matches = true
+              break
+            end
+          end
+          next false unless state_matches
+        end
+
+        # Check method requirement
+        if expected_method
+          methods = callback.instance_variable_get(:@methods) || []
+          method_matches = methods.any? do |method|
+            (method.is_a?(Symbol) && method == expected_method) ||
+              (method.is_a?(String) && method.to_sym == expected_method) ||
+              (method.respond_to?(:call) && method.respond_to?(:source_location))
+          end
+          next false unless method_matches
+        end
+
+        # Check if condition
+        if expected_if
+          if_condition = branch.if_condition
+          if_matches = (if_condition.is_a?(Symbol) && if_condition == expected_if) ||
+                       (if_condition.is_a?(String) && if_condition.to_sym == expected_if) ||
+                       if_condition.respond_to?(:call)
+          next false unless if_matches
+        end
+
+        # Check unless condition
+        if expected_unless
+          unless_condition = branch.unless_condition
+          unless_matches = (unless_condition.is_a?(Symbol) && unless_condition == expected_unless) ||
+                           (unless_condition.is_a?(String) && unless_condition.to_sym == expected_unless) ||
+                           unless_condition.respond_to?(:call)
+          next false unless unless_matches
+        end
+
+        true
+      end
+
+      return if matching_callback
+
+      expected_parts = []
+      expected_parts << "on: #{expected_event.inspect}" if expected_event
+      expected_parts << "from: #{expected_from.inspect}" if expected_from
+      expected_parts << "to: #{expected_to.inspect}" if expected_to
+      expected_parts << "do: #{expected_method.inspect}" if expected_method
+      expected_parts << "if: #{expected_if.inspect}" if expected_if
+      expected_parts << "unless: #{expected_unless.inspect}" if expected_unless
+
+      default_message = "Expected #{callback_type}_transition callback with #{expected_parts.join(', ')} to be defined, but it was not found"
+
+      if defined?(::Minitest)
+        assert false, message || default_message
+      elsif defined?(::RSpec)
+        raise message || default_message
+      else
+        raise default_message
+      end
+    end
   end
 end

data/lib/state_machines/transition.rb

@@ -33,11 +33,11 @@ module StateMachines
     # Determines whether the current ruby implementation supports pausing and
     # resuming transitions
     def self.pause_supported?
-      %w(ruby maglev).include?(RUBY_ENGINE)
+      %w[ruby maglev].include?(RUBY_ENGINE)
     end
 
     # Creates a new, specific transition
-    def initialize(object, machine, event, from_name, to_name, read_state = true) #:nodoc:
+    def initialize(object, machine, event, from_name, to_name, read_state = true) # :nodoc:
       @object = object
       @machine = machine
       @args = []
@@ -136,7 +136,7 @@ module StateMachines
     #   transition = StateMachines::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
     #   transition.attributes   # => {:object => #<Vehicle:0xb7d60ea4>, :attribute => :state, :event => :ignite, :from => 'parked', :to => 'idling'}
     def attributes
-      @attributes ||= {object: object, attribute: attribute, event: event, from: from, to: to}
+      @attributes ||= { object: object, attribute: attribute, event: event, from: from, to: to }
     end
 
     # Runs the actual transition and any before/after callbacks associated
@@ -153,25 +153,32 @@ module StateMachines
     #
     #   vehicle = Vehicle.new
     #   transition = StateMachines::Transition.new(vehicle, machine, :ignite, :parked, :idling)
-    #   transition.perform                  # => Runs the +save+ action after setting the state attribute
-    #   transition.perform(false)           # => Only sets the state attribute
-    #   transition.perform(Time.now)        # => Passes in additional arguments and runs the +save+ action
-    #   transition.perform(Time.now, false) # => Passes in additional arguments and only sets the state attribute
+    #   transition.perform                              # => Runs the +save+ action after setting the state attribute
+    #   transition.perform(false)                       # => Only sets the state attribute
+    #   transition.perform(run_action: false)           # => Only sets the state attribute
+    #   transition.perform(Time.now)                    # => Passes in additional arguments and runs the +save+ action
+    #   transition.perform(Time.now, false)             # => Passes in additional arguments and only sets the state attribute
+    #   transition.perform(Time.now, run_action: false) # => Passes in additional arguments and only sets the state attribute
     def perform(*args)
-      run_action = [true, false].include?(args.last) ? args.pop : true
+      run_action = true
+
+      if [true, false].include?(args.last)
+        run_action = args.pop
+      elsif args.last.is_a?(Hash) && args.last.key?(:run_action)
+        run_action = args.last.delete(:run_action)
+      end
+
       self.args = args
 
       # Run the transition
-      !!TransitionCollection.new([self], {use_transactions: machine.use_transactions, actions: run_action}).perform
+      !!TransitionCollection.new([self], { use_transactions: machine.use_transactions, actions: run_action }).perform
     end
 
     # Runs a block within a transaction for the object being transitioned.
     # By default, transactions are a no-op unless otherwise defined by the
     # machine's integration.
-    def within_transaction
-      machine.within_transaction(object) do
-        yield
-      end
+    def within_transaction(&)
+      machine.within_transaction(object, &)
     end
 
     # Runs the before / after callbacks for this transition.  If a block is
@@ -186,7 +193,7 @@ module StateMachines
     # This will return true if all before callbacks gets executed.  After
     # callbacks will not have an effect on the result.
     def run_callbacks(options = {}, &block)
-      options = {before: true, after: true}.merge(options)
+      options = { before: true, after: true }.merge(options)
       @success = false
 
       halted = pausable { before(options[:after], &block) } if options[:before]
@@ -219,10 +226,10 @@ module StateMachines
     #
     #   vehicle.state   # => 'idling'
     def persist
-      unless @persisted
-        machine.write(object, :state, to)
-        @persisted = true
-      end
+      return if @persisted
+
+      machine.write(object, :state, to)
+      @persisted = true
     end
 
     # Rolls back changes made to the object's state via this transition.  This
@@ -265,11 +272,11 @@ module StateMachines
     # and event involved in the transition are equal
     def ==(other)
       other.instance_of?(self.class) &&
-      other.object == object &&
-      other.machine == machine &&
-      other.from_name == from_name &&
-      other.to_name == to_name &&
-      other.event == event
+        other.object == object &&
+        other.machine == machine &&
+        other.from_name == from_name &&
+        other.to_name == to_name &&
+        other.event == event
     end
 
     # Generates a nicely formatted description of this transitions's contents.
@@ -279,10 +286,10 @@ module StateMachines
     #   transition = StateMachines::Transition.new(object, machine, :ignite, :parked, :idling)
     #   transition   # => #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
     def inspect
-      "#<#{self.class} #{%w(attribute event from from_name to to_name).map { |attr| "#{attr}=#{send(attr).inspect}" } * ' '}>"
+      "#<#{self.class} #{%w[attribute event from from_name to to_name].map { |attr| "#{attr}=#{send(attr).inspect}" } * ' '}>"
     end
 
-  private
+    private
 
     # Runs a block that may get paused.  If the block doesn't pause, then
     # execution will continue as normal.  If the block gets paused, then it
@@ -292,13 +299,16 @@ module StateMachines
     # getting paused.
     def pausable
       begin
-        halted = !catch(:halt) { yield; true }
-      rescue => error
+        halted = !catch(:halt) do
+          yield
+          true
+        end
+      rescue StandardError => e
         raise unless @resume_block
       end
 
       if @resume_block
-        @resume_block.call(halted, error)
+        @resume_block.call(halted, e)
       else
         halted
       end
@@ -310,12 +320,12 @@ module StateMachines
     def pause
       raise ArgumentError, 'around_transition callbacks cannot be called in multiple execution contexts in java implementations of Ruby. Use before/after_transitions instead.' unless self.class.pause_supported?
 
-      unless @resume_block
-        require 'continuation' unless defined?(callcc)
-        callcc do |block|
-          @paused_block = block
-          throw :halt, true
-        end
+      return if @resume_block
+
+      require 'continuation' unless defined?(callcc)
+      callcc do |block|
+        @paused_block = block
+        throw :halt, true
       end
     end
 
@@ -372,8 +382,9 @@ module StateMachines
         @before_run = true
       end
 
-      action = {success: true}.merge(block_given? ? yield : {})
-      @result, @success = action[:result], action[:success]
+      action = { success: true }.merge(block_given? ? yield : {})
+      @result = action[:result]
+      @success = action[:success]
     end
 
     # Runs the machine's +after+ callbacks for this transition.  Only
@@ -390,17 +401,17 @@ module StateMachines
     # exception will not bubble up to the caller since +after+ callbacks
     # should never halt the execution of a +perform+.
     def after
-      unless @after_run
-        # First resume previously paused callbacks
-        if resume
-          catch(:halt) do
-            type = @success ? :after : :failure
-            machine.callbacks[type].each { |callback| callback.call(object, context, self) }
-          end
-        end
+      return if @after_run
 
-        @after_run = true
+      # First resume previously paused callbacks
+      if resume
+        catch(:halt) do
+          type = @success ? :after : :failure
+          machine.callbacks[type].each { |callback| callback.call(object, context, self) }
+        end
       end
+
+      @after_run = true
     end
 
     # Gets a hash of the context defining this unique transition (including
@@ -412,7 +423,7 @@ module StateMachines
     #   transition = StateMachines::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
     #   transition.context    # => {:on => :ignite, :from => :parked, :to => :idling}
     def context
-      @context ||= {on: event, from: from_name, to: to_name}
+      @context ||= { on: event, from: from_name, to: to_name }
     end
   end
 end