statesman 4.1.2 → 4.1.3

data/lib/statesman/exceptions.rb

@@ -3,7 +3,18 @@ module Statesman
   class InvalidTransitionError < StandardError; end
   class InvalidCallbackError < StandardError; end
   class GuardFailedError < StandardError; end
-  class TransitionFailedError < StandardError; end
+  class TransitionFailedError < StandardError
+    def initialize(from, to)
+      @from = from
+      @to = to
+    end
+
+    attr_reader :from, :to
+
+    def message
+      "Cannot transition from '#{from}' to '#{to}'"
+    end
+  end
   class TransitionConflictError < StandardError; end
   class MissingTransitionAssociation < StandardError; end
 

data/lib/statesman/machine.rb

@@ -48,6 +48,8 @@ module Statesman
         @callbacks ||= {
           before: [],
           after: [],
+          after_transition_failure: [],
+          after_guard_failure: [],
           after_commit: [],
           guards: [],
         }
@@ -83,6 +85,16 @@ module Statesman
                      from: options[:from], to: options[:to], &block)
       end
 
+      def after_transition_failure(options = {}, &block)
+        add_callback(callback_type: :after_transition_failure, callback_class: Callback,
+                     from: options[:from], to: options[:to], &block)
+      end
+
+      def after_guard_failure(options = {}, &block)
+        add_callback(callback_type: :after_guard_failure, callback_class: Callback,
+                     from: options[:from], to: options[:to], &block)
+      end
+
       def validate_callback_condition(options = { from: nil, to: nil })
         from = to_s_or_nil(options[:from])
         to   = array_to_s_or_nil(options[:to])
@@ -219,9 +231,15 @@ module Statesman
       @storage_adapter.create(initial_state, new_state, metadata)
 
       true
+    rescue TransitionFailedError
+      execute(:after_transition_failure, initial_state, new_state)
+      raise
+    rescue GuardFailedError
+      execute(:after_guard_failure, initial_state, new_state)
+      raise
     end
 
-    def execute(phase, initial_state, new_state, transition)
+    def execute(phase, initial_state, new_state, transition = nil)
       callbacks = callbacks_for(phase, from: initial_state, to: new_state)
       callbacks.each { |cb| cb.call(@object, transition) }
     end
@@ -265,10 +283,7 @@ module Statesman
       to   = to_s_or_nil(options[:to])
 
       successors = self.class.successors[from] || []
-      unless successors.include?(to)
-        raise TransitionFailedError,
-              "Cannot transition from '#{from}' to '#{to}'"
-      end
+      raise TransitionFailedError.new(from, to) unless successors.include?(to)
 
       # Call all guards, they raise exceptions if they fail
       guards_for(from: from, to: to).each do |guard|

data/lib/statesman/version.rb

@@ -1,3 +1,3 @@
 module Statesman
-  VERSION = "4.1.2".freeze
+  VERSION = "4.1.3".freeze
 end

data/spec/spec_helper.rb

@@ -20,36 +20,7 @@ RSpec.configure do |config|
   config.order = "random"
 
   def connection_failure
-    if defined?(Moped)
-      Moped::Errors::ConnectionFailure
-    else
-      Mongo::Error::NoServerAvailable
-    end
-  end
-
-  if config.exclusion_filter[:mongo]
-    puts "Skipping Mongo tests"
-  else
-    require "mongoid"
-
-    # Try a mongo connection at the start of the suite and raise if it fails
-    begin
-      Mongoid.configure do |mongo_config|
-        if defined?(Moped)
-          mongo_config.connect_to("statesman_test")
-          mongo_config.sessions["default"]["options"]["max_retries"] = 2
-        else
-          mongo_config.connect_to("statesman_test", server_selection_timeout: 2)
-        end
-      end
-      # Attempting a mongo operation will trigger 2 retries then throw an
-      # exception if mongo is not running.
-      Mongoid.purge!
-    rescue connection_failure => error
-      puts "The spec suite requires MongoDB to be installed and running locally"
-      puts "Mongo dependent specs can be filtered with rspec --tag '~mongo'"
-      raise(error)
-    end
+    Moped::Errors::ConnectionFailure if defined?(Moped)
   end
 
   if config.exclusion_filter[:active_record]

data/spec/statesman/adapters/active_record_queries_spec.rb

@@ -1,6 +1,17 @@
 require "spec_helper"
 
 describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
+  def configure_old(klass, transition_class)
+    klass.define_singleton_method(:transition_class) { transition_class }
+    klass.define_singleton_method(:initial_state) { :initial }
+    klass.send(:include, described_class)
+  end
+
+  def configure_new(klass, transition_class)
+    klass.send(:include, described_class[transition_class: transition_class,
+                                         initial_state: :initial])
+  end
+
   before do
     prepare_model_table
     prepare_transitions_table
@@ -8,32 +19,6 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     prepare_other_transitions_table
 
     Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }
-
-    MyActiveRecordModel.send(:include, Statesman::Adapters::ActiveRecordQueries)
-    MyActiveRecordModel.class_eval do
-      def self.transition_class
-        MyActiveRecordModelTransition
-      end
-
-      def self.initial_state
-        :initial
-      end
-    end
-
-    OtherActiveRecordModel.send(:include,
-                                Statesman::Adapters::ActiveRecordQueries)
-    OtherActiveRecordModel.class_eval do
-      def self.transition_class
-        OtherActiveRecordModelTransition
-      end
-
-      def self.initial_state
-        :initial
-      end
-    end
-
-    MyActiveRecordModel.send(:has_one, :other_active_record_model)
-    OtherActiveRecordModel.send(:belongs_to, :my_active_record_model)
   end
 
   after { Statesman.configure { storage_adapter(Statesman::Adapters::Memory) } }
@@ -59,147 +44,172 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     model
   end
 
-  describe ".in_state" do
-    context "given a single state" do
-      subject { MyActiveRecordModel.in_state(:succeeded) }
+  shared_examples "testing methods" do
+    before do
+      if config_type == :old
+        configure_old(MyActiveRecordModel, MyActiveRecordModelTransition)
+        configure_old(OtherActiveRecordModel, OtherActiveRecordModelTransition)
+      elsif config_type == :new
+        configure_new(MyActiveRecordModel, MyActiveRecordModelTransition)
+        configure_new(OtherActiveRecordModel, OtherActiveRecordModelTransition)
+      else
+        raise "Unknown config type #{config_type}"
+      end
 
-      it { is_expected.to include model }
-      it { is_expected.to_not include other_model }
+      MyActiveRecordModel.send(:has_one, :other_active_record_model)
+      OtherActiveRecordModel.send(:belongs_to, :my_active_record_model)
     end
 
-    context "given multiple states" do
-      subject { MyActiveRecordModel.in_state(:succeeded, :failed) }
-
-      it { is_expected.to include model }
-      it { is_expected.to include other_model }
-    end
+    describe ".in_state" do
+      context "given a single state" do
+        subject { MyActiveRecordModel.in_state(:succeeded) }
 
-    context "given the initial state" do
-      subject { MyActiveRecordModel.in_state(:initial) }
+        it { is_expected.to include model }
+        it { is_expected.to_not include other_model }
+      end
 
-      it { is_expected.to include initial_state_model }
-      it { is_expected.to include returned_to_initial_model }
-    end
+      context "given multiple states" do
+        subject { MyActiveRecordModel.in_state(:succeeded, :failed) }
 
-    context "given an array of states" do
-      subject { MyActiveRecordModel.in_state(%i[succeeded failed]) }
+        it { is_expected.to include model }
+        it { is_expected.to include other_model }
+      end
 
-      it { is_expected.to include model }
-      it { is_expected.to include other_model }
-    end
+      context "given the initial state" do
+        subject { MyActiveRecordModel.in_state(:initial) }
 
-    context "merging two queries" do
-      subject do
-        MyActiveRecordModel.in_state(:succeeded).
-          joins(:other_active_record_model).
-          merge(OtherActiveRecordModel.in_state(:initial))
+        it { is_expected.to include initial_state_model }
+        it { is_expected.to include returned_to_initial_model }
       end
 
-      it { is_expected.to be_empty }
-    end
-  end
-
-  describe ".not_in_state" do
-    context "given a single state" do
-      subject { MyActiveRecordModel.not_in_state(:failed) }
+      context "given an array of states" do
+        subject { MyActiveRecordModel.in_state(%i[succeeded failed]) }
 
-      it { is_expected.to include model }
-      it { is_expected.to_not include other_model }
-    end
+        it { is_expected.to include model }
+        it { is_expected.to include other_model }
+      end
 
-    context "given multiple states" do
-      subject(:not_in_state) { MyActiveRecordModel.not_in_state(:succeeded, :failed) }
+      context "merging two queries" do
+        subject do
+          MyActiveRecordModel.in_state(:succeeded).
+            joins(:other_active_record_model).
+            merge(OtherActiveRecordModel.in_state(:initial))
+        end
 
-      it do
-        expect(not_in_state).to match_array([initial_state_model,
-                                             returned_to_initial_model])
+        it { is_expected.to be_empty }
       end
     end
 
-    context "given an array of states" do
-      subject(:not_in_state) { MyActiveRecordModel.not_in_state(%i[succeeded failed]) }
+    describe ".not_in_state" do
+      context "given a single state" do
+        subject { MyActiveRecordModel.not_in_state(:failed) }
 
-      it do
-        expect(not_in_state).to match_array([initial_state_model,
-                                             returned_to_initial_model])
+        it { is_expected.to include model }
+        it { is_expected.to_not include other_model }
       end
-    end
-  end
 
-  context "with a custom name for the transition association" do
-    before do
-      # Switch to using OtherActiveRecordModelTransition, so the existing
-      # relation with MyActiveRecordModelTransition doesn't interfere with
-      # this spec.
-      MyActiveRecordModel.send(:has_many,
-                               :custom_name,
-                               class_name: "OtherActiveRecordModelTransition")
-
-      MyActiveRecordModel.class_eval do
-        def self.transition_class
-          OtherActiveRecordModelTransition
+      context "given multiple states" do
+        subject(:not_in_state) { MyActiveRecordModel.not_in_state(:succeeded, :failed) }
+
+        it do
+          expect(not_in_state).to match_array([initial_state_model,
+                                               returned_to_initial_model])
         end
       end
-    end
 
-    describe ".in_state" do
-      subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+      context "given an array of states" do
+        subject(:not_in_state) { MyActiveRecordModel.not_in_state(%i[succeeded failed]) }
 
-      specify { expect { query }.to_not raise_error }
+        it do
+          expect(not_in_state).to match_array([initial_state_model,
+                                               returned_to_initial_model])
+        end
+      end
     end
-  end
 
-  context "with no association with the transition class" do
-    before do
-      class UnknownModelTransition < OtherActiveRecordModelTransition; end
+    context "with a custom name for the transition association" do
+      before do
+        # Switch to using OtherActiveRecordModelTransition, so the existing
+        # relation with MyActiveRecordModelTransition doesn't interfere with
+        # this spec.
+        MyActiveRecordModel.send(:has_many,
+                                 :custom_name,
+                                 class_name: "OtherActiveRecordModelTransition")
 
-      MyActiveRecordModel.class_eval do
-        def self.transition_class
-          UnknownModelTransition
+        MyActiveRecordModel.class_eval do
+          def self.transition_class
+            OtherActiveRecordModelTransition
+          end
         end
       end
-    end
 
-    describe ".in_state" do
-      subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+      describe ".in_state" do
+        subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
 
-      it "raises a helpful error" do
-        expect { query }.to raise_error(Statesman::MissingTransitionAssociation)
+        specify { expect { query }.to_not raise_error }
       end
     end
-  end
 
-  context "after_commit transactional integrity" do
-    before do
-      MyStateMachine.class_eval do
-        cattr_accessor(:after_commit_callback_executed) { false }
+    context "after_commit transactional integrity" do
+      before do
+        MyStateMachine.class_eval do
+          cattr_accessor(:after_commit_callback_executed) { false }
 
-        after_transition(from: :initial, to: :succeeded, after_commit: true) do
-          # This leaks state in a testable way if transactional integrity is broken.
-          MyStateMachine.after_commit_callback_executed = true
+          after_transition(from: :initial, to: :succeeded, after_commit: true) do
+            # This leaks state in a testable way if transactional integrity is broken.
+            MyStateMachine.after_commit_callback_executed = true
+          end
         end
       end
-    end
 
-    after do
-      MyStateMachine.class_eval do
-        callbacks[:after_commit] = []
+      after do
+        MyStateMachine.class_eval do
+          callbacks[:after_commit] = []
+        end
+      end
+
+      let!(:model) do
+        MyActiveRecordModel.create
+      end
+
+      # rubocop:disable RSpec/ExampleLength
+      it do
+        expect do
+          ActiveRecord::Base.transaction do
+            model.state_machine.transition_to!(:succeeded)
+            raise ActiveRecord::Rollback
+          end
+        end.to_not change(MyStateMachine, :after_commit_callback_executed)
       end
+      # rubocop:enable RSpec/ExampleLength
     end
+  end
+
+  context "using old configuration method" do
+    let(:config_type) { :old }
+
+    include_examples "testing methods"
+  end
 
-    let!(:model) do
-      MyActiveRecordModel.create
+  context "using new configuration method" do
+    let(:config_type) { :new }
+
+    include_examples "testing methods"
+  end
+
+  context "with no association with the transition class" do
+    before do
+      class UnknownModelTransition < OtherActiveRecordModelTransition; end
+
+      configure_old(MyActiveRecordModel, UnknownModelTransition)
     end
 
-    # rubocop:disable RSpec/ExampleLength
-    it do
-      expect do
-        ActiveRecord::Base.transaction do
-          model.state_machine.transition_to!(:succeeded)
-          raise ActiveRecord::Rollback
-        end
-      end.to_not change(MyStateMachine, :after_commit_callback_executed)
+    describe ".in_state" do
+      subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+
+      it "raises a helpful error" do
+        expect { query }.to raise_error(Statesman::MissingTransitionAssociation)
+      end
     end
-    # rubocop:enable RSpec/ExampleLength
   end
 end

data/spec/statesman/machine_spec.rb

@@ -57,7 +57,11 @@ describe Statesman::Machine do
         expect(instance).
           to receive(:transition_to).once.
           and_raise(StandardError)
-        transition_state rescue nil # rubocop:disable RescueModifier
+        begin
+          transition_state
+        rescue StandardError
+          nil
+        end
       end
 
       it "re-raises the exception" do
@@ -86,7 +90,11 @@ describe Statesman::Machine do
             to receive(:transition_to).
             exactly(retry_attempts + 1).times.
             and_raise(Statesman::TransitionConflictError)
-          transition_state rescue nil # rubocop:disable RescueModifier
+          begin
+            transition_state
+          rescue StandardError
+            nil
+          end
         end
 
         it "re-raises the conflict" do
@@ -320,6 +328,16 @@ describe Statesman::Machine do
     it_behaves_like "a callback store", :guard_transition, :guards
   end
 
+  describe ".after_transition_failure" do
+    it_behaves_like "a callback store",
+                    :after_transition_failure,
+                    :after_transition_failure
+  end
+
+  describe ".after_guard_failure" do
+    it_behaves_like "a callback store", :after_guard_failure, :after_guard_failure
+  end
+
   describe "#initialize" do
     it "accepts an object to manipulate" do
       machine_instance = machine.new(my_model)
@@ -609,8 +627,12 @@ describe Statesman::Machine do
 
     context "when the state cannot be transitioned to" do
       it "raises an error" do
+        # Hardcoding error message here to ensure backward
+        # compatibility as people may have been parsing the string
+        # to figure out the transitions involved.
         expect { instance.transition_to!(:z) }.
-          to raise_error(Statesman::TransitionFailedError)
+          to raise_error(Statesman::TransitionFailedError,
+                         "Cannot transition from 'x' to 'z'")
       end
     end
 
@@ -672,6 +694,38 @@ describe Statesman::Machine do
             expect { instance.transition_to!(:y) }.
               to raise_error(Statesman::GuardFailedError)
           end
+
+          context "and a guard failed callback defined" do
+            let(:guard_failure_result) { true }
+            let(:guard_failure_cb) { ->(*_args) { guard_failure_result } }
+
+            before { machine.after_guard_failure(from: :x, to: :y, &guard_failure_cb) }
+
+            it "calls the failure callback" do
+              expect(guard_failure_cb).to receive(:call).once.with(
+                my_model, nil
+              ).and_return(guard_failure_result)
+              expect { instance.transition_to!(:y) }.
+                to raise_error(Statesman::GuardFailedError)
+            end
+          end
+        end
+      end
+
+      context "with a transition failed callback" do
+        let(:result) { true }
+        let(:transition_failed_cb) { ->(*_args) { result } }
+        let(:instance) { machine.new(my_model) }
+
+        before do
+          machine.after_transition_failure(&transition_failed_cb)
+        end
+
+        it "raises and exception and calls the callback" do
+          expect(transition_failed_cb).to receive(:call).once.
+            with(my_model, nil).and_return(true)
+          expect { instance.transition_to!(:z) }.
+            to raise_error(Statesman::TransitionFailedError)
         end
       end
     end