workflow 0.3.0 → 0.4.1

data/VERSION

@@ -0,0 +1 @@
+0.4.1

data/lib/workflow.rb

@@ -1,38 +1,46 @@
 require 'rubygems'
-require 'active_support'
 
+# See also README.markdown for documentation
 module Workflow
- 
+
   class Specification
-    
+
     attr_accessor :states, :initial_state, :meta, :on_transition_proc
-    
+
     def initialize(meta = {}, &specification)
       @states = Hash.new
       @meta = meta
       instance_eval(&specification)
     end
-    
+
+    def state_names
+      states.keys
+    end
+
     private
-  
+
     def state(name, meta = {:meta => {}}, &events_and_etc)
       # meta[:meta] to keep the API consistent..., gah
-      new_state = State.new(name, meta[:meta])
+      new_state = Workflow::State.new(name, meta[:meta])
       @initial_state = new_state if @states.empty?
       @states[name.to_sym] = new_state
       @scoped_state = new_state
       instance_eval(&events_and_etc) if events_and_etc
     end
-    
+
     def event(name, args = {}, &action)
+      target = args[:transitions_to] || args[:transition_to]
+      raise WorkflowDefinitionError.new(
+        "missing ':transitions_to' in workflow event definition for '#{name}'") \
+        if target.nil?
       @scoped_state.events[name.to_sym] =
-        Event.new(name, args[:transitions_to], (args[:meta] or {}), &action)
+        Workflow::Event.new(name, target, (args[:meta] or {}), &action)
     end
-    
+
     def on_entry(&proc)
       @scoped_state.on_entry = proc
     end
-    
+
     def on_exit(&proc)
       @scoped_state.on_exit = proc
     end
@@ -41,7 +49,7 @@ module Workflow
       @on_transition_proc = proc
     end
   end
-  
+
   class TransitionHalted < Exception
 
     attr_reader :halted_because
@@ -57,14 +65,16 @@ module Workflow
 
   class WorkflowError < Exception; end
 
+  class WorkflowDefinitionError < Exception; end
+
   class State
-    
+
     attr_accessor :name, :events, :meta, :on_entry, :on_exit
-    
+
     def initialize(name, meta = {})
       @name, @events, @meta = name, Hash.new, meta
     end
-    
+
     def to_s
       "#{name}"
     end
@@ -73,20 +83,29 @@ module Workflow
       name.to_sym
     end
   end
-  
+
   class Event
-    
+
     attr_accessor :name, :transitions_to, :meta, :action
-    
+
     def initialize(name, transitions_to, meta = {}, &action)
       @name, @transitions_to, @meta, @action = name, transitions_to.to_sym, meta, action
     end
-    
+
   end
-  
+
   module WorkflowClassMethods
     attr_reader :workflow_spec
 
+    def workflow_column(column_name=nil)
+      if column_name
+        @workflow_state_column_name = column_name.to_sym
+      else
+        @workflow_state_column_name ||= :workflow_state
+      end
+      @workflow_state_column_name
+    end
+
     def workflow(&specification)
       @workflow_spec = Specification.new(Hash.new, &specification)
       @workflow_spec.states.values.each do |state|
@@ -110,7 +129,7 @@ module Workflow
   end
 
   module WorkflowInstanceMethods
-    def current_state 
+    def current_state
       loaded_state = load_workflow_state
       res = spec.states[loaded_state.to_sym] if loaded_state
       res || spec.initial_state
@@ -129,6 +148,8 @@ module Workflow
       raise NoTransitionAllowed.new(
         "There is no event #{name.to_sym} defined for the #{current_state} state") \
         if event.nil?
+      # This three member variables are a relict from the old workflow library
+      # TODO: refactor some day
       @halted_because = nil
       @halted = false
       @raise_exception_on_halt = false
@@ -150,18 +171,18 @@ module Workflow
     private
 
     def check_transition(event)
-      # Create a meaningful error message instead of 
+      # Create a meaningful error message instead of
       # "undefined method `on_entry' for nil:NilClass"
       # Reported by Kyle Burton
       if !spec.states[event.transitions_to]
-        raise WorkflowError.new("Event[#{event.name}]'s " + 
+        raise WorkflowError.new("Event[#{event.name}]'s " +
             "transitions_to[#{event.transitions_to}] is not a declared state.")
       end
     end
 
     def spec
       c = self.class
-      # using a simple loop instead of class_inheritable_accessor to avoid 
+      # using a simple loop instead of class_inheritable_accessor to avoid
       # dependency on Rails' ActiveSupport
       until c.workflow_spec || !(c.include? Workflow)
         c = c.superclass
@@ -199,9 +220,9 @@ module Workflow
       self.send action_name.to_sym, *args if self.respond_to?(action_name.to_sym)
     end
 
-    def run_on_entry(state, prior_state, triggering_event, *args)     
+    def run_on_entry(state, prior_state, triggering_event, *args)
       if state.on_entry
-        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry) 
+        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry)
       else
         hook_name = "on_#{state}_entry"
         self.send hook_name, prior_state, triggering_event, *args if self.respond_to? hook_name
@@ -237,13 +258,13 @@ module Workflow
 
   module ActiveRecordInstanceMethods
     def load_workflow_state
-      read_attribute(:workflow_state)
+      read_attribute(self.class.workflow_column)
     end
 
     # On transition the new workflow state is immediately saved in the
     # database.
     def persist_workflow_state(new_value)
-      update_attribute :workflow_state, new_value
+      update_attribute self.class.workflow_column, new_value
     end
 
     private
@@ -254,7 +275,17 @@ module Workflow
     # state. That's why it is important to save the string with the name of the
     # initial state in all the new records.
     def write_initial_state
-      write_attribute :workflow_state, current_state.to_s
+      write_attribute self.class.workflow_column, current_state.to_s
+    end
+  end
+
+  module RemodelInstanceMethods
+    def load_workflow_state
+      send(self.class.workflow_column)
+    end
+
+    def persist_workflow_state(new_value)
+      update(self.class.workflow_column => new_value)
     end
   end
 
@@ -263,9 +294,74 @@ module Workflow
     klass.extend WorkflowClassMethods
     if Object.const_defined?(:ActiveRecord)
       if klass < ActiveRecord::Base
-      klass.send :include, ActiveRecordInstanceMethods
-      klass.before_validation :write_initial_state
+        klass.send :include, ActiveRecordInstanceMethods
+        klass.before_validation :write_initial_state
+      end
+    elsif Object.const_defined?(:Remodel)
+      if klass < Remodel::Entity
+        klass.send :include, RemodelInstanceMethods
+      end
+    end
+  end
+
+  # Generates a `dot` graph of the workflow.
+  # Prerequisite: the `dot` binary.
+  # You can use it in your own Rakefile like this:
+  #
+  #     namespace :doc do
+  #       desc "Generate a graph of the workflow."
+  #       task :workflow do
+  #         Workflow::create_workflow_diagram(Order.new)
+  #       end
+  #     end
+  #
+  # You can influence the placement of nodes by specifying
+  # additional meta information in your states and transition descriptions.
+  # You can assign higher `doc_weight` value to the typical transitions
+  # in your workflow. All other states and transitions will be arranged
+  # around that main line. See also `weight` in the graphviz documentation.
+  # Example:
+  #
+  #     state :new do
+  #       event :approve, :transitions_to => :approved, :meta => {:doc_weight => 8}
+  #     end
+  #
+  #
+  # @param klass A class with the Workflow mixin, for which you wish the graphical workflow representation
+  # @param [String] target_dir Directory, where to save the dot and the pdf files
+  # @param [String] graph_options You can change graph orientation, size etc. See graphviz documentation
+  def self.create_workflow_diagram(klass, target_dir, graph_options='rankdir="LR", size="7,11.6", ratio="fill"')
+    workflow_name = "#{klass.name.tableize}_workflow"
+    fname = File.join(target_dir, "generated_#{workflow_name}")
+    File.open("#{fname}.dot", 'w') do |file|
+      file.puts %Q|
+digraph #{workflow_name} {
+  graph [#{graph_options}];
+  node [shape=box];
+  edge [len=1];
+      |
+
+      klass.workflow_spec.states.each do |state_name, state|
+        file.puts %Q{  #{state.name} [label="#{state.name}"];}
+        state.events.each do |event_name, event|
+          meta_info = event.meta
+          if meta_info[:doc_weight]
+            weight_prop = ", weight=#{meta_info[:doc_weight]}"
+          else
+            weight_prop = ''
+          end
+          file.puts %Q{  #{state.name} -> #{event.transitions_to} [label="#{event_name.to_s.humanize}" #{weight_prop}];}
+        end
       end
+      file.puts "}"
+      file.puts
     end
+    `dot -Tpdf -o#{fname}.pdf #{fname}.dot`
+    puts "
+Please run the following to open the generated file:
+
+open #{fname}.pdf
+
+"
   end
 end

data/test/couchtiny_example.rb

@@ -0,0 +1,46 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'couchtiny'
+require 'couchtiny/document'
+require 'workflow'
+
+class User < CouchTiny::Document
+  include Workflow
+  workflow do
+    state :submitted do
+      event :activate_via_link, :transitions_to => :proved_email
+    end
+    state :proved_email
+  end
+
+  def load_workflow_state
+    self[:workflow_state]
+  end
+
+  def persist_workflow_state(new_value)
+    self[:workflow_state] = new_value
+    save!
+  end
+end
+
+
+class CouchtinyExample < Test::Unit::TestCase
+
+  def setup
+    db = CouchTiny::Database.url("http://127.0.0.1:5984/test-workflow")
+    db.delete_database! rescue nil
+    db.create_database!
+    User.use_database db
+  end
+
+  test 'CouchDB persistence' do
+    user = User.new :email => 'manya@example.com'
+    user.save!
+    assert user.submitted?
+    user.activate_via_link!
+    assert user.proved_email?
+
+    reloaded_user = User.get user.id
+    puts reloaded_user.inspect
+    assert reloaded_user.proved_email?, 'Reloaded user should have the desired workflow state'
+  end
+end

data/test/main_test.rb

@@ -0,0 +1,420 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+require 'mocha'
+#require 'ruby-debug'
+
+ActiveRecord::Migration.verbose = false
+
+class Order < ActiveRecord::Base
+  include Workflow
+  workflow do
+    state :submitted do
+      event :accept, :transitions_to => :accepted, :meta => {:doc_weight => 8} do |reviewer, args|
+      end
+    end
+    state :accepted do
+      event :ship, :transitions_to => :shipped
+    end
+    state :shipped
+  end
+
+end
+
+class LegacyOrder < ActiveRecord::Base
+  include Workflow
+
+  workflow_column :foo_bar # use this legacy database column for persistence
+
+  workflow do
+    state :submitted do
+      event :accept, :transitions_to => :accepted, :meta => {:doc_weight => 8} do |reviewer, args|
+      end
+    end
+    state :accepted do
+      event :ship, :transitions_to => :shipped
+    end
+    state :shipped
+  end
+
+end
+
+
+class MainTest < Test::Unit::TestCase
+
+  def exec(sql)
+    ActiveRecord::Base.connection.execute sql
+  end
+
+  def setup
+    ActiveRecord::Base.establish_connection(
+      :adapter => "sqlite3",
+      :database  => ":memory:" #"tmp/test"
+    )
+    ActiveRecord::Base.connection.reconnect! # eliminate ActiveRecord warning. TODO: delete as soon as ActiveRecord is fixed
+
+    ActiveRecord::Schema.define do
+      create_table :orders do |t|
+        t.string :title, :null => false
+        t.string :workflow_state
+      end
+    end
+
+    exec "INSERT INTO orders(title, workflow_state) VALUES('some order', 'accepted')"
+
+    ActiveRecord::Schema.define do
+      create_table :legacy_orders do |t|
+        t.string :title, :null => false
+        t.string :foo_bar
+      end
+    end
+
+    exec "INSERT INTO legacy_orders(title, foo_bar) VALUES('some order', 'accepted')"
+
+  end
+
+  def teardown
+    ActiveRecord::Base.connection.disconnect!
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'immediately save the new workflow_state on state machine transition' do
+    o = assert_state 'some order', 'accepted'
+    o.ship!
+    assert_state 'some order', 'shipped'
+  end
+
+  test 'immediately save the new workflow_state on state machine transition with custom column name' do
+    o = assert_state 'some order', 'accepted', LegacyOrder
+    o.ship!
+    assert_state 'some order', 'shipped', LegacyOrder
+  end
+
+  test 'persist workflow_state in the db and reload' do
+    o = assert_state 'some order', 'accepted'
+    assert_equal :accepted, o.current_state.name
+    o.ship!
+    o.save!
+
+    assert_state 'some order', 'shipped'
+
+    o.reload
+    assert_equal 'shipped', o.read_attribute(:workflow_state)
+  end
+
+  test 'persist workflow_state in the db with_custom_name and reload' do
+    o = assert_state 'some order', 'accepted', LegacyOrder
+    assert_equal :accepted, o.current_state.name
+    o.ship!
+    o.save!
+
+    assert_state 'some order', 'shipped', LegacyOrder
+
+    o.reload
+    assert_equal 'shipped', o.read_attribute(:foo_bar)
+  end
+
+  test 'default workflow column should be workflow_state' do
+    o = assert_state 'some order', 'accepted'
+    assert_equal :workflow_state, o.class.workflow_column
+  end
+
+  test 'custom workflow column should be foo_bar' do
+    o = assert_state 'some order', 'accepted', LegacyOrder
+    assert_equal :foo_bar, o.class.workflow_column
+  end
+
+  test 'access workflow specification' do
+    assert_equal 3, Order.workflow_spec.states.length
+    assert_equal ['submitted', 'accepted', 'shipped'].sort,
+      Order.workflow_spec.state_names.map{|n| n.to_s}.sort
+  end
+
+  test 'current state object' do
+    o = assert_state 'some order', 'accepted'
+    assert_equal 'accepted', o.current_state.to_s
+    assert_equal 1, o.current_state.events.length
+  end
+
+  test 'on_entry and on_exit invoked' do
+    c = Class.new
+    callbacks = mock()
+    callbacks.expects(:my_on_exit_new).once
+    callbacks.expects(:my_on_entry_old).once
+    c.class_eval do
+      include Workflow
+      workflow do
+        state :new do
+          event :age, :transitions_to => :old
+        end
+        on_exit do
+          callbacks.my_on_exit_new
+        end
+        state :old
+        on_entry do
+          callbacks.my_on_entry_old
+        end
+        on_exit do
+          fail "wrong on_exit executed"
+        end
+      end
+    end
+
+    o = c.new
+    assert_equal 'new', o.current_state.to_s
+    o.age!
+  end
+
+  test 'on_transition invoked' do
+    callbacks = mock()
+    callbacks.expects(:on_tran).once # this is validated at the end
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      workflow do
+        state :one do
+          event :increment, :transitions_to => :two
+        end
+        state :two
+        on_transition do |from, to, triggering_event, *event_args|
+          callbacks.on_tran
+        end
+      end
+    end
+    assert_not_nil c.workflow_spec.on_transition_proc
+    c.new.increment!
+  end
+
+  test 'access event meta information' do
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      workflow do
+        state :main, :meta => {:importance => 8}
+        state :supplemental, :meta => {:importance => 1}
+      end
+    end
+    assert_equal 1, c.workflow_spec.states[:supplemental].meta[:importance]
+  end
+
+  test 'initial state' do
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      workflow { state :one; state :two }
+    end
+    assert_equal 'one', c.new.current_state.to_s
+  end
+
+  test 'nil as initial state' do
+    exec "INSERT INTO orders(title, workflow_state) VALUES('nil state', NULL)"
+    o = Order.find_by_title('nil state')
+    assert o.submitted?, 'if workflow_state is nil, the initial state should be assumed'
+    assert !o.shipped?
+  end
+
+  test 'initial state immediately set as ActiveRecord attribute for new objects' do
+    o = Order.create(:title => 'new object')
+    assert_equal 'submitted', o.read_attribute(:workflow_state)
+  end
+
+  test 'question methods for state' do
+    o = assert_state 'some order', 'accepted'
+    assert o.accepted?
+    assert !o.shipped?
+  end
+
+  test 'correct exception for event, that is not allowed in current state' do
+    o = assert_state 'some order', 'accepted'
+    assert_raise Workflow::NoTransitionAllowed do
+      o.accept!
+    end
+  end
+
+  test 'multiple events with the same name and different arguments lists from different states'
+
+  test 'implicit transition callback' do
+    args = mock()
+    args.expects(:my_tran).once # this is validated at the end
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      def my_transition(args)
+        args.my_tran
+      end
+      workflow do
+        state :one do
+          event :my_transition, :transitions_to => :two
+        end
+        state :two
+      end
+    end
+    c.new.my_transition!(args)
+  end
+
+  test 'Single table inheritance (STI)' do
+    class BigOrder < Order
+    end
+
+    bo = BigOrder.new
+    assert bo.submitted?
+    assert !bo.accepted?
+  end
+
+  test 'Two-level inheritance' do
+    class BigOrder < Order
+    end
+
+    class EvenBiggerOrder < BigOrder
+    end
+
+    assert EvenBiggerOrder.new.submitted?
+  end
+
+  test 'Iheritance with workflow definition override' do
+    class BigOrder < Order
+    end
+
+    class SpecialBigOrder < BigOrder
+      workflow do
+        state :start_big
+      end
+    end
+
+    special = SpecialBigOrder.new
+    assert_equal 'start_big', special.current_state.to_s
+  end
+
+  test 'Better error message for missing target state' do
+    class Problem
+      include Workflow
+      workflow do
+        state :initial do
+          event :solve, :transitions_to => :solved
+        end
+      end
+    end
+    assert_raise Workflow::WorkflowError do
+      Problem.new.solve!
+    end
+  end
+
+  # Intermixing of transition graph definition (states, transitions)
+  # on the one side and implementation of the actions on the other side
+  # for a bigger state machine can introduce clutter.
+  #
+  # To reduce this clutter it is now possible to use state entry- and
+  # exit- hooks defined through a naming convention. For example, if there
+  # is a state :pending, then you can hook in by defining method
+  # `def on_pending_exit(new_state, event, *args)` instead of using a
+  # block:
+  #
+  #     state :pending do
+  #       on_entry do
+  #         # your implementation here
+  #       end
+  #     end
+  #
+  # If both a function with a name according to naming convention and the
+  # on_entry/on_exit block are given, then only on_entry/on_exit block is used.
+  test 'on_entry and on_exit hooks in separate methods' do
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      attr_reader :history
+      def initialize
+        @history = []
+      end
+      workflow do
+        state :new do
+          event :next, :transitions_to => :next_state
+        end
+        state :next_state
+      end
+
+      def on_next_state_entry(prior_state, event, *args)
+        @history << "on_next_state_entry #{event} #{prior_state} ->"
+      end
+
+      def on_new_exit(new_state, event, *args)
+        @history << "on_new_exit #{event} -> #{new_state}"
+      end
+    end
+
+    o = c.new
+    assert_equal 'new', o.current_state.to_s
+    assert_equal [], o.history
+    o.next!
+    assert_equal ['on_new_exit next -> next_state', 'on_next_state_entry next new ->'], o.history
+
+  end
+
+  test 'diagram generation' do
+    begin
+      $stdout = StringIO.new('', 'w')
+      Workflow::create_workflow_diagram(Order, 'doc')
+      assert_match(/open.+\.pdf/, $stdout.string,
+        'PDF should be generate and a hint be given to the user.')
+    ensure
+      $stdout = STDOUT
+    end
+  end
+
+  test 'halt stops the transition' do
+    c = Class.new do
+      include Workflow
+      workflow do
+        state :young do
+          event :age, :transitions_to => :old
+        end
+        state :old
+      end
+
+      def age(by=1)
+        halt 'too fast' if by > 100
+      end
+    end
+
+    joe = c.new
+    assert joe.young?
+    joe.age! 120
+    assert joe.young?, 'Transition should have been halted'
+    assert_equal 'too fast', joe.halted_because
+  end
+
+  test 'halt! raises exception' do
+    article_class = Class.new do
+      include Workflow
+      workflow do
+        state :new do
+          event :reject, :transitions_to => :rejected
+        end
+        state :rejected
+      end
+
+      def reject(reason)
+        halt! 'We do not reject articles unless the reason is important' \
+          unless reason =~ /important/i
+      end
+    end
+
+    article = article_class.new
+    assert article.new?
+    assert_raise Workflow::TransitionHalted do
+      article.reject! 'Too funny'
+    end
+    assert article.new?, 'Transition should have been halted'
+    article.reject! 'Important: too short'
+    assert article.rejected?, 'Transition should happen now'
+  end
+
+end
+