state_machines 0.10.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39c8073bdf33aff2e34bfc3403db686c7d6e4344f158e144cb881230b10d9597
-  data.tar.gz: 150e14164e42addded79421e90456de2f60b4c451c743ee31a8eb2227d91896b
+  metadata.gz: 5aa5d105c78cb53f15f42e8662dd7f8e0d0d5f8807b88dcbd8b4201f13718384
+  data.tar.gz: d761cedbe052c5c8829626e0875f54dce064f7156162119b4a040594b439068c
 SHA512:
-  metadata.gz: 34af008f9378c058a199dd05d3204df5d995466f7db126589a8614d540bb636ce08c42f38796504753be8414431623e02b30c10d772fc2d524d4a2f9f4ba58e2
-  data.tar.gz: a64f178f0f5ce8e13139b871c3cd351570df7c665f43338201225ff27d2482fe3cb3e1619f79e01544d4f9b3341bb9e589db7a659717e4975312684b6fd0ee82
+  metadata.gz: 37398c9ca5f2de7413dfb7a8a467984d0fc4d47f8367ea0747fec6d9c1eaca5a7c3439f37988c02dd8ce27622a9a9e54cf5cc0b2d84404f00f92a862c168bb23
+  data.tar.gz: 159022534eb3c308bc2f2c8e960f111053631d3e10adafc9ae8156c95a26165f48690c682229a577bdfecf918b335ebe5b6d57e82e095c924585ad8d11b9d1ee

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.
@@ -255,6 +254,71 @@ vehicle.state_name              # => :parked
 # vehicle.state = :parked
 ```
 
+## Testing
+
+State Machines provides a `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+
+### Setup
+
+Include the test helper in your test class:
+
+```ruby
+# For Minitest
+class VehicleTest < Minitest::Test
+  include StateMachines::TestHelper
+  
+  def test_initial_state
+    vehicle = Vehicle.new
+    assert_state vehicle, :state, :parked
+  end
+end
+
+# For RSpec  
+RSpec.describe Vehicle do
+  include StateMachines::TestHelper
+  
+  it "starts in parked state" do
+    vehicle = Vehicle.new
+    assert_state vehicle, :state, :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
+assert_state vehicle, :state, :parked
+assert_can_transition vehicle, :ignite
+assert_cannot_transition vehicle, :shift_up
+assert_transition vehicle, :ignite, :state, :idling
+```
+
+#### 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
+```
+
+The test helper works with both Minitest and RSpec, automatically detecting your testing framework.
+
 ## Additional Topics
 
 ### Explicit vs. Implicit Event Transitions

data/lib/state_machines/branch.rb

@@ -1,5 +1,7 @@
 # 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
@@ -114,7 +116,7 @@ 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
@@ -131,7 +133,7 @@ module StateMachines
     # 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]

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'
@@ -42,4 +41,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/event.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # An event defines an action that transitions an attribute from one state to
   # another.  The state that an attribute is transitioned to depends on the
@@ -32,13 +34,22 @@ module StateMachines
     #
     # Configuration options:
     # * <tt>:human_name</tt> - The human-readable version of this event's name
-    def initialize(machine, name, options = {}) #:nodoc:
-      options.assert_valid_keys(:human_name)
+    def initialize(machine, name, options = nil, human_name: nil, **extra_options) #:nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      if options.is_a?(Hash)
+        # Old style: initialize(machine, name, {human_name: 'Custom Name'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+        human_name = options[:human_name]
+      else
+        # New style: initialize(machine, name, human_name: 'Custom Name')
+        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      end
 
       @machine = machine
       @name = name
       @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
-      @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
+      @human_name = human_name || @name.to_s.tr('_', ' ')
       reset
 
       # Output a warning if another event has a conflicting qualified name
@@ -91,7 +102,9 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      options.assert_valid_keys(:from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless)
+      end
 
       branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states
@@ -121,7 +134,7 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
     def transition_for(object, requirements = {})
-      requirements.assert_valid_keys(:from, :to, :guard)
+      StateMachines::OptionsValidator.assert_valid_keys!(requirements, :from, :to, :guard)
       requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|

data/lib/state_machines/machine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'machine/class_methods' 
+require_relative 'options_validator'
+require_relative 'machine/class_methods'
 
 module StateMachines
   # Represents a state machine for a particular attribute.  State machines
@@ -451,7 +452,7 @@ module StateMachines
     # Creates a new state machine for the given attribute
     def initialize(owner_class, *args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
-      options.assert_valid_keys(:attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions)
 
       # Find an integration that matches this machine's owner class
       if options.include?(:integration)
@@ -953,7 +954,7 @@ module StateMachines
     # options hash which contains at least <tt>:if</tt> condition support.
     def state(*names, &block)
       options = names.last.is_a?(Hash) ? names.pop : {}
-      options.assert_valid_keys(:value, :cache, :if, :human_name)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :value, :cache, :if, :human_name)
 
       # Store the context so that it can be used for / matched against any state
       # that gets added
@@ -1256,7 +1257,7 @@ module StateMachines
     #   end
     def event(*names, &block)
       options = names.last.is_a?(Hash) ? names.pop : {}
-      options.assert_valid_keys(:human_name)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
 
       # Store the context so that it can be used for / matched against any event
       # that gets added
@@ -1698,7 +1699,7 @@ module StateMachines
     def after_failure(*args, &block)
       options = (args.last.is_a?(Hash) ? args.pop : {})
       options[:do] = args if args.any?
-      options.assert_valid_keys(:on, :do, :if, :unless)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :on, :do, :if, :unless)
 
       add_callback(:failure, options, &block)
     end

data/lib/state_machines/machine_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of state machines for a class
   class MachineCollection < Hash
@@ -22,7 +24,7 @@ module StateMachines
     # * <tt>:to</tt> - A hash to write the initialized state to instead of
     #   writing to the object.  Default is to write directly to the object.
     def initialize_states(object, options = {}, attributes = {})
-      options.assert_valid_keys( :static, :dynamic, :to)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :static, :dynamic, :to)
       options = {static: true, dynamic: true}.merge(options)
 
       result = yield if block_given?

data/lib/state_machines/node_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of nodes in a state machine, be it events or states.
   # Nodes will not differentiate between the String and Symbol versions of the
@@ -18,7 +20,7 @@ module StateMachines
     #   hashed indices for in order to perform quick lookups.  Default is to
     #   index by the :name attribute
     def initialize(machine, options = {})
-      options.assert_valid_keys(:index)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :index)
       options = { index: :name }.merge(options)
 
       @machine = machine

data/lib/state_machines/options_validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Define the module if it doesn't exist yet
+  # Module for validating options without monkey-patching Hash
+  # Provides the same functionality as the Hash monkey patch but in a cleaner way
+  module OptionsValidator
+    class << self
+      # Validates that all keys in the options hash are in the list of valid keys
+      #
+      # @param options [Hash] The options hash to validate
+      # @param valid_keys [Array<Symbol>] List of valid key names
+      # @param caller_info [String] Information about the calling method for better error messages
+      # @raise [ArgumentError] If any invalid keys are found
+      def assert_valid_keys!(options, *valid_keys, caller_info: nil)
+        return if options.empty?
+
+        valid_keys.flatten!
+        invalid_keys = options.keys - valid_keys
+
+        return if invalid_keys.empty?
+
+        caller_context = caller_info ? " in #{caller_info}" : ''
+        raise ArgumentError, "Unknown key#{'s' if invalid_keys.length > 1}: #{invalid_keys.map(&:inspect).join(', ')}. Valid keys are: #{valid_keys.map(&:inspect).join(', ')}#{caller_context}"
+      end
+
+      # Validates that at most one of the exclusive keys is present in the options hash
+      #
+      # @param options [Hash] The options hash to validate
+      # @param exclusive_keys [Array<Symbol>] List of mutually exclusive keys
+      # @param caller_info [String] Information about the calling method for better error messages
+      # @raise [ArgumentError] If more than one exclusive key is found
+      def assert_exclusive_keys!(options, *exclusive_keys, caller_info: nil)
+        return if options.empty?
+
+        conflicting_keys = exclusive_keys & options.keys
+        return if conflicting_keys.length <= 1
+
+        caller_context = caller_info ? " in #{caller_info}" : ''
+        raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}#{caller_context}"
+      end
+
+      # Validates options using a more convenient interface that works with both
+      # hash-style and kwargs-style method definitions
+      #
+      # @param valid_keys [Array<Symbol>] List of valid key names
+      # @param exclusive_key_groups [Array<Array<Symbol>>] Groups of mutually exclusive keys
+      # @param caller_info [String] Information about the calling method
+      # @return [Proc] A validation proc that can be called with options
+      def validator(valid_keys: [], exclusive_key_groups: [], caller_info: nil)
+        proc do |options|
+          assert_valid_keys!(options, *valid_keys, caller_info: caller_info) unless valid_keys.empty?
+
+          exclusive_key_groups.each do |group|
+            assert_exclusive_keys!(options, *group, caller_info: caller_info)
+          end
+        end
+      end
+
+      # Helper method for backwards compatibility - allows gradual migration
+      # from Hash monkey patch to this module
+      #
+      # @param options [Hash] The options to validate
+      # @param valid_keys [Array<Symbol>] Valid keys
+      # @return [Hash] The same options hash (for chaining)
+      def validate_and_return(options, *valid_keys)
+        assert_valid_keys!(options, *valid_keys)
+        options
+      end
+    end
+  end
+end

data/lib/state_machines/path.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # A path represents a sequence of transitions that can be run for a particular
   # object.  Paths can walk to new transitions, revealing all of the possible
@@ -22,7 +24,7 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one
     def initialize(object, machine, options = {})
-      options.assert_valid_keys(:target, :guard)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :target, :guard)
 
       @object = object
       @machine = machine

data/lib/state_machines/path_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of paths that are generated based on a set of
   # requirements regarding what states to start and end on
@@ -27,7 +29,7 @@ module StateMachines
     #   conditionals defined for each one
     def initialize(object, machine, options = {})
       options = {deep: false, from: machine.states.match!(object).name}.merge(options)
-      options.assert_valid_keys( :from, :to, :deep, :guard)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :deep, :guard)
 
       @object = object
       @machine = machine

data/lib/state_machines/state.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # A state defines a value that an attribute can be in after being transitioned
   # 0 or more times.  States can represent a value of any type in Ruby, though
@@ -51,17 +53,32 @@ module StateMachines
     #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
     #   By default, the configured value is matched.
     # * <tt>:human_name</tt> - The human-readable version of this state's name
-    def initialize(machine, name, options = {}) # :nodoc:
-      options.assert_valid_keys(:initial, :value, :cache, :if, :human_name)
+    def initialize(machine, name, options = nil, initial: false, value: :__not_provided__, cache: nil, if: nil, human_name: nil, **extra_options) # :nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      if options.is_a?(Hash)
+        # Old style: initialize(machine, name, {initial: true, value: 'foo'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :initial, :value, :cache, :if, :human_name)
+        initial = options.fetch(:initial, false)
+        value = options.include?(:value) ? options[:value] : :__not_provided__
+        cache = options[:cache]
+        if_condition = options[:if]
+        human_name = options[:human_name]
+      else
+        # New style: initialize(machine, name, initial: true, value: 'foo')
+        # options parameter should be nil in this case
+        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :initial, :value, :cache, :if, :human_name) unless extra_options.empty?
+        if_condition = binding.local_variable_get(:if)  # 'if' is a keyword, need special handling
+      end
 
       @machine = machine
       @name = name
       @qualified_name = name && machine.namespace ? :"#{machine.namespace}_#{name}" : name
-      @human_name = options[:human_name] || (@name ? @name.to_s.tr('_', ' ') : 'nil')
-      @value = options.include?(:value) ? options[:value] : name&.to_s
-      @cache = options[:cache]
-      @matcher = options[:if]
-      @initial = options[:initial] == true
+      @human_name = human_name || (@name ? @name.to_s.tr('_', ' ') : 'nil')
+      @value = value == :__not_provided__ ? name&.to_s : value
+      @cache = cache
+      @matcher = if_condition
+      @initial = initial == true
       @context = StateContext.new(self)
 
       return unless name

data/lib/state_machines/state_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a module which will get evaluated within the context of a state.
   #
@@ -88,7 +90,7 @@ module StateMachines
     # See StateMachines::Machine#transition for a description of the possible
     # configurations for defining transitions.
     def transition(options)
-      options.assert_valid_keys(:from, :to, :on, :if, :unless)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :on, :if, :unless)
       raise ArgumentError, 'Must specify :on event' unless options[:on]
       raise ArgumentError, 'Must specify either :to or :from state' unless !options[:to] ^ !options[:from]
 

data/lib/state_machines/test_helper.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Test helper module providing assertion methods for state machine testing
+  # Designed to work with Minitest, RSpec, and future testing frameworks
+  #
+  # @example Basic usage with Minitest
+  #   class MyModelTest < Minitest::Test
+  #     include StateMachines::TestHelper
+  #
+  #     def test_initial_state
+  #       model = MyModel.new
+  #       assert_state(model, :state_machine_name, :initial_state)
+  #     end
+  #   end
+  #
+  # @example Usage with RSpec
+  #   RSpec.describe MyModel do
+  #     include StateMachines::TestHelper
+  #
+  #     it "starts in initial state" do
+  #       model = MyModel.new
+  #       assert_state(model, :state_machine_name, :initial_state)
+  #     end
+  #   end
+  #
+  # @since 0.10.0
+  module TestHelper
+    # 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 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")
+      default_message = "Expected #{object.class}##{machine_name} to be #{expected_state}, but was #{actual}"
+
+      if defined?(::Minitest)
+        assert_equal expected_state.to_s, actual.to_s, message || default_message
+      elsif defined?(::RSpec)
+        expect(actual.to_s).to eq(expected_state.to_s), message || default_message
+      else
+        raise "Expected #{expected_state}, but got #{actual}" unless expected_state.to_s == actual.to_s
+      end
+    end
+
+    # Assert that an object can transition via a specific event
+    #
+    # @param object [Object] The object with state machines
+    # @param event [Symbol] The event name
+    # @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"
+
+      if defined?(::Minitest)
+        assert object.send(can_method), message || default_message
+      elsif defined?(::RSpec)
+        expect(object.send(can_method)).to be_truthy, message || default_message
+      else
+        raise default_message unless object.send(can_method)
+      end
+    end
+
+    # Assert that an object cannot transition via a specific event
+    #
+    # @param object [Object] The object with state machines
+    # @param event [Symbol] The event name
+    # @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"
+
+      if defined?(::Minitest)
+        refute object.send(can_method), message || default_message
+      elsif defined?(::RSpec)
+        expect(object.send(can_method)).to be_falsy, message || default_message
+      elsif object.send(can_method)
+        raise default_message
+      end
+    end
+
+    # Assert that triggering an event changes the object to the expected state
+    #
+    # @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 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)
+      object.send("#{event}!")
+      assert_state(object, machine_name, expected_state, message)
+    end
+
+    # === Extended State Machine Assertions ===
+
+    def assert_sm_states_list(machine, expected_states, message = nil)
+      actual_states = machine.states.map(&:name).compact
+      default_message = "Expected states #{expected_states} but got #{actual_states}"
+
+      if defined?(::Minitest)
+        assert_equal expected_states.sort, actual_states.sort, message || default_message
+      elsif defined?(::RSpec)
+        expect(actual_states.sort).to eq(expected_states.sort), message || default_message
+      else
+        raise default_message unless expected_states.sort == actual_states.sort
+      end
+    end
+
+    def refute_sm_state_defined(machine, state, message = nil)
+      state_exists = machine.states.any? { |s| s.name == state }
+      default_message = "Expected state #{state} to not be defined in machine"
+
+      if defined?(::Minitest)
+        refute state_exists, message || default_message
+      elsif defined?(::RSpec)
+        expect(state_exists).to be_falsy, message || default_message
+      elsif state_exists
+        raise default_message
+      end
+    end
+    alias assert_sm_state_not_defined refute_sm_state_defined
+
+    def assert_sm_initial_state(machine, expected_state, message = nil)
+      state_obj = machine.state(expected_state)
+      is_initial = state_obj&.initial?
+      default_message = "Expected state #{expected_state} to be the initial state"
+
+      if defined?(::Minitest)
+        assert is_initial, message || default_message
+      elsif defined?(::RSpec)
+        expect(is_initial).to be_truthy, message || default_message
+      else
+        raise default_message unless is_initial
+      end
+    end
+
+    def assert_sm_final_state(machine, state, message = nil)
+      state_obj = machine.states[state]
+      is_final = state_obj&.final?
+      default_message = "Expected state #{state} to be final"
+
+      if defined?(::Minitest)
+        assert is_final, message || default_message
+      elsif defined?(::RSpec)
+        expect(is_final).to be_truthy, message || default_message
+      else
+        raise default_message unless is_final
+      end
+    end
+
+    def assert_sm_possible_transitions(machine, from:, expected_to_states:, message: nil)
+      actual_transitions = machine.events.flat_map do |event|
+        event.branches.select { |branch| branch.known_states.include?(from) }
+             .map(&:to)
+      end.uniq
+      default_message = "Expected transitions from #{from} to #{expected_to_states} but got #{actual_transitions}"
+
+      if defined?(::Minitest)
+        assert_equal expected_to_states.sort, actual_transitions.sort, message || default_message
+      elsif defined?(::RSpec)
+        expect(actual_transitions.sort).to eq(expected_to_states.sort), message || default_message
+      else
+        raise default_message unless expected_to_states.sort == actual_transitions.sort
+      end
+    end
+
+    def refute_sm_transition_allowed(machine, from:, to:, on:, message: nil)
+      event = machine.events[on]
+      is_allowed = event&.branches&.any? { |branch| branch.known_states.include?(from) && branch.to == to }
+      default_message = "Expected transition from #{from} to #{to} on #{on} to not be allowed"
+
+      if defined?(::Minitest)
+        refute is_allowed, message || default_message
+      elsif defined?(::RSpec)
+        expect(is_allowed).to be_falsy, message || default_message
+      elsif is_allowed
+        raise default_message
+      end
+    end
+    alias assert_sm_transition_not_allowed refute_sm_transition_allowed
+
+    def assert_sm_event_triggers(object, event, message = nil)
+      initial_state = object.state
+      object.send("#{event}!")
+      state_changed = initial_state != object.state
+      default_message = "Expected event #{event} to trigger state change"
+
+      if defined?(::Minitest)
+        assert state_changed, message || default_message
+      elsif defined?(::RSpec)
+        expect(state_changed).to be_truthy, message || default_message
+      else
+        raise default_message unless state_changed
+      end
+    end
+
+    def refute_sm_event_triggers(object, event, message = nil)
+      initial_state = object.state
+      begin
+        object.send("#{event}!")
+        state_unchanged = initial_state == object.state
+        default_message = "Expected event #{event} to not trigger state change"
+
+        if defined?(::Minitest)
+          assert state_unchanged, message || default_message
+        elsif defined?(::RSpec)
+          expect(state_unchanged).to be_truthy, message || default_message
+        else
+          raise default_message unless state_unchanged
+        end
+      rescue StateMachines::InvalidTransition
+        # Expected behavior - transition was blocked
+      end
+    end
+    alias assert_sm_event_not_triggers refute_sm_event_triggers
+
+    def assert_sm_event_raises_error(object, event, error_class, message = nil)
+      default_message = "Expected event #{event} to raise #{error_class}"
+
+      if defined?(::Minitest)
+        assert_raises(error_class, message || default_message) do
+          object.send("#{event}!")
+        end
+      elsif defined?(::RSpec)
+        expect { object.send("#{event}!") }.to raise_error(error_class), message || default_message
+      else
+        begin
+          object.send("#{event}!")
+          raise default_message
+        rescue error_class
+          # Expected behavior
+        end
+      end
+    end
+
+    def assert_sm_callback_executed(object, callback_name, message = nil)
+      callbacks_executed = object.instance_variable_get(:@_sm_callbacks_executed) || []
+      callback_was_executed = callbacks_executed.include?(callback_name)
+      default_message = "Expected callback #{callback_name} to be executed"
+
+      if defined?(::Minitest)
+        assert callback_was_executed, message || default_message
+      elsif defined?(::RSpec)
+        expect(callback_was_executed).to be_truthy, message || default_message
+      else
+        raise default_message unless callback_was_executed
+      end
+    end
+
+    def refute_sm_callback_executed(object, callback_name, message = nil)
+      callbacks_executed = object.instance_variable_get(:@_sm_callbacks_executed) || []
+      callback_was_executed = callbacks_executed.include?(callback_name)
+      default_message = "Expected callback #{callback_name} to not be executed"
+
+      if defined?(::Minitest)
+        refute callback_was_executed, message || default_message
+      elsif defined?(::RSpec)
+        expect(callback_was_executed).to be_falsy, message || default_message
+      elsif callback_was_executed
+        raise default_message
+      end
+    end
+    alias assert_sm_callback_not_executed refute_sm_callback_executed
+
+    def assert_sm_state_persisted(record, expected:, message: nil)
+      record.reload if record.respond_to?(:reload)
+      actual_state = record.state
+      default_message = "Expected persisted state #{expected} but got #{actual_state}"
+
+      if defined?(::Minitest)
+        assert_equal expected, actual_state, message || default_message
+      elsif defined?(::RSpec)
+        expect(actual_state).to eq(expected), message || default_message
+      else
+        raise default_message unless expected == actual_state
+      end
+    end
+  end
+end

data/lib/state_machines/transition_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of transitions in a state machine
   class TransitionCollection < Array
@@ -30,7 +32,7 @@ module StateMachines
       attributes = map { |transition| transition.attribute }.uniq
       fail ArgumentError, 'Cannot perform multiple transitions in parallel for the same state machine attribute' if attributes.length != length
 
-      options.assert_valid_keys(:actions, :after, :use_transactions)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :actions, :after, :use_transactions)
       options = {actions: true, after: true, use_transactions: true}.merge(options)
       @skip_actions = !options[:actions]
       @skip_after = !options[:after]

data/lib/state_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StateMachines
-  VERSION = '0.10.0'
+  VERSION = '0.20.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: state_machines
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -62,7 +62,6 @@ files:
 - LICENSE.txt
 - README.md
 - lib/state_machines.rb
-- lib/state_machines/assertions.rb
 - lib/state_machines/branch.rb
 - lib/state_machines/callback.rb
 - lib/state_machines/core.rb
@@ -83,12 +82,14 @@ files:
 - lib/state_machines/matcher.rb
 - lib/state_machines/matcher_helpers.rb
 - lib/state_machines/node_collection.rb
+- lib/state_machines/options_validator.rb
 - lib/state_machines/path.rb
 - lib/state_machines/path_collection.rb
 - lib/state_machines/state.rb
 - lib/state_machines/state_collection.rb
 - lib/state_machines/state_context.rb
 - lib/state_machines/stdio_renderer.rb
+- lib/state_machines/test_helper.rb
 - lib/state_machines/transition.rb
 - lib/state_machines/transition_collection.rb
 - lib/state_machines/version.rb

data/lib/state_machines/assertions.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-class Hash
-  # Provides a set of helper methods for making assertions about the content
-  # of various objects
-
-  unless respond_to?(:assert_valid_keys)
-    # Validate all keys in a hash match <tt>*valid_keys</tt>, raising ArgumentError
-    # on a mismatch. Note that keys are NOT treated indifferently, meaning if you
-    # use strings for keys but assert symbols as keys, this will fail.
-    #
-    #   { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age"
-    #   { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'"
-    #   { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age)   # => passes, raises nothing
-    # Code from ActiveSupport
-    def assert_valid_keys(*valid_keys)
-      valid_keys.flatten!
-      each_key do |k|
-        unless valid_keys.include?(k)
-          raise ArgumentError.new("Unknown key: #{k.inspect}. Valid keys are: #{valid_keys.map(&:inspect).join(', ')}")
-        end
-      end
-    end
-  end
-
-  # Validates that the given hash only includes at *most* one of a set of
-  # exclusive keys.  If more than one key is found, an ArgumentError will be
-  # raised.
-  #
-  # == Examples
-  #
-  #   options = {:only => :on, :except => :off}
-  #   options.assert_exclusive_keys(:only)                   # => nil
-  #   options.assert_exclusive_keys(:except)                 # => nil
-  #   options.assert_exclusive_keys(:only, :except)          # => ArgumentError: Conflicting keys: only, except
-  #   options.assert_exclusive_keys(:only, :except, :with)   # => ArgumentError: Conflicting keys: only, except
-  def assert_exclusive_keys(*exclusive_keys)
-    conflicting_keys = exclusive_keys & keys
-    raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}" unless conflicting_keys.length <= 1
-  end
-end
-