gh-227 prepare tests and documentation

Author: geekq

README.adoc

@@ -407,6 +407,8 @@ When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>
 * If an `:if` check is present, proceed if it evaluates to true, or drop to the next event.
 * If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible.
 
+You can also pass additional arguments, which can be evaluated by :if methods or procs. See examples in
+[conditionals_test.rb](test/conditionals_test.rb#L45)
 
 ### Advanced transition hooks
 
@@ -513,6 +515,10 @@ end
 Changelog
 ---------
 
+=== New in the version 3.1.0
+
+* gh-227 allow event arguments to be taken into account when selecting the event
+
 === New in the version 3.0.0
 
 * gh-228 Support for Ruby 3 keyword args, provided by @agirling
@@ -552,7 +558,7 @@ integration with https://github.com/activeadmin/activeadmin[ActiveAdmin].
 
 Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
 
-Copyright (c) 2010-2022 Vladimir Dobriakov and Contributors
+Copyright (c) 2010-2024 Vladimir Dobriakov and Contributors
 
 Copyright (c) 2008-2009 Vodafone
 

lib/workflow/version.rb

@@ -1,3 +1,3 @@
 module Workflow
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

test/conditionals_test.rb

@@ -0,0 +1,99 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'workflow'
+require 'mocha/minitest'
+
+class ConditionalsTest < Minitest::Test
+
+  test 'can_<fire_event>? with conditions' do
+    c = Class.new do
+      include Workflow
+      workflow do
+        state :off do
+          event :turn_on, :transitions_to => :on, :if => :sufficient_battery_level?
+          event :turn_on, :transitions_to => :low_battery, :if => proc { |obj| obj.battery > 0 }
+        end
+        state :on
+        state :low_battery
+      end
+      attr_reader :battery
+      def initialize(battery)
+        @battery = battery
+      end
+
+      def sufficient_battery_level?
+        @battery > 10
+      end
+    end
+
+    device = c.new 0
+    assert_equal false, device.can_turn_on?
+
+    device = c.new 5
+    assert device.can_turn_on?
+    device.turn_on!
+    assert device.low_battery?
+    assert_equal false, device.on?
+
+    device = c.new 50
+    assert device.can_turn_on?
+    device.turn_on!
+    assert device.on?
+  end
+
+  test 'gh-227 allow event arguments in conditions - test with proc' do
+    c = Class.new do
+      include Workflow
+      # define more advanced workflow, where event methods allow arguments
+      workflow do
+        state :off do
+          # turn_on accepts additional argument `power_adapter`
+          event :turn_on, :transitions_to => :on, :if => :sufficient_battery_level?
+          event :turn_on, :transitions_to => :low_battery # otherwise
+        end
+        state :on
+        state :low_battery
+      end
+      attr_reader :battery
+      def initialize(battery)
+        @battery = battery
+      end
+
+      def sufficient_battery_level?(power_adapter=false)
+        power_adapter || @battery > 10
+      end
+    end
+
+    # test for conditions in a proc
+    device = c.new 5
+    device.turn_on!(true) # case with event arguments to be taken into account
+    assert device.on?
+  end
+
+  test 'gh-227 allow event arguments in conditions - test with a method' do
+    c = Class.new do
+      include Workflow
+      # define more advanced workflow, where event methods allow arguments
+      workflow do
+        state :off do
+          # turn_on accepts additional argument `power_adapter`
+          event :turn_on, :transitions_to => :on, :if => proc { |obj, power_adapter| power_adapter || obj.battery > 10 }
+          event :turn_on, :transitions_to => :low_battery # otherwise
+        end
+        state :on
+        state :low_battery
+      end
+      attr_reader :battery
+      def initialize(battery)
+        @battery = battery
+      end
+    end
+
+    device = c.new 5
+    device.turn_on!(true) # case with event arguments to be taken into account
+    assert device.on?
+  end
+
+end
+

test/main_test.rb

@@ -328,42 +328,6 @@ def reject(reason)
     assert_equal false, human.can_go_to_college?
   end
 
-  test 'can_<fire_event>? with conditions' do
-    c = Class.new do
-      include Workflow
-      workflow do
-        state :off do
-          event :turn_on, :transitions_to => :on, :if => :sufficient_battery_level?
-          event :turn_on, :transitions_to => :low_battery, :if => proc { |obj| obj.battery > 0 }
-        end
-        state :on
-        state :low_battery
-      end
-      attr_reader :battery
-      def initialize(battery)
-        @battery = battery
-      end
-
-      def sufficient_battery_level?
-        @battery > 10
-      end
-    end
-
-    device = c.new 0
-    assert_equal false, device.can_turn_on?
-
-    device = c.new 5
-    assert device.can_turn_on?
-    device.turn_on!
-    assert device.low_battery?
-    assert_equal false, device.on?
-
-    device = c.new 50
-    assert device.can_turn_on?
-    device.turn_on!
-    assert device.on?
-  end
-
   test 'workflow graph generation' do
     require 'workflow/draw'
     Dir.chdir('/tmp') do