state_machines 0.6.0 → 0.20.0

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.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # A transition represents a state change for a specific attribute.
   #

data/lib/state_machines/transition_collection.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of transitions in a state machine
   class TransitionCollection < Array
@@ -28,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,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
-  VERSION = '0.6.0'
+  VERSION = '0.20.0'
 end

data/lib/state_machines.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 require 'state_machines/version'
 require 'state_machines/core'
-require 'state_machines/core_ext'
+require 'state_machines/core_ext'
+require 'state_machines/stdio_renderer'

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: state_machines
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 - Aaron Pfeifer
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -56,7 +55,6 @@ dependencies:
 description: Adds support for creating state machines for attributes on any Ruby class
 email:
 - terminale@gmail.com
-- aaron@pluginaweek.org
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -64,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
@@ -79,24 +76,30 @@ files:
 - lib/state_machines/integrations.rb
 - lib/state_machines/integrations/base.rb
 - lib/state_machines/machine.rb
+- lib/state_machines/machine/class_methods.rb
 - lib/state_machines/machine_collection.rb
 - lib/state_machines/macro_methods.rb
 - 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
 homepage: https://github.com/state-machines/state_machines
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  changelog_uri: https://github.com/state-machines/state_machines/blob/master/CHANGELOG.md
+  homepage_uri: https://github.com/state-machines/state_machines
+  source_code_uri: https://github.com/state-machines/state_machines
 rdoc_options: []
 require_paths:
 - lib
@@ -111,8 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: State machines for attributes
 test_files: []

data/lib/state_machines/assertions.rb

@@ -1,40 +0,0 @@
-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
-