statesmin 1.0.0

data/spec/statesmin/callback_spec.rb

@@ -0,0 +1,120 @@
+require "spec_helper"
+
+describe Statesmin::Callback do
+  let(:cb_lambda) { -> {} }
+  let(:callback) do
+    Statesmin::Callback.new(from: nil, to: nil, callback: cb_lambda)
+  end
+
+  describe "#initialize" do
+    context "with no callback" do
+      let(:cb_lambda) { nil }
+
+      it "raises an error" do
+        expect { callback }.to raise_error(Statesmin::InvalidCallbackError)
+      end
+    end
+  end
+
+  describe "#call" do
+    let(:spy) { double.as_null_object }
+    let(:cb_lambda) { -> { spy.call } }
+
+    it "delegates to callback" do
+      callback.call
+      expect(spy).to have_received(:call)
+    end
+  end
+
+  describe "#applies_to" do
+    let(:callback) do
+      Statesmin::Callback.new(from: :x, to: :y, callback: cb_lambda)
+    end
+    subject { callback.applies_to?(from: from, to: to) }
+
+    context "with any from value" do
+      let(:from) { nil }
+
+      context "and an allowed to value" do
+        let(:to) { :y }
+        it { is_expected.to be_truthy }
+      end
+
+      context "and a disallowed to value" do
+        let(:to) { :a }
+        it { is_expected.to be_falsey }
+      end
+    end
+
+    context "with any to value" do
+      let(:to) { nil }
+
+      context "and an allowed 'from' value" do
+        let(:from) { :x }
+        it { is_expected.to be_truthy }
+      end
+
+      context "and a disallowed 'from' value" do
+        let(:from) { :a }
+        it { is_expected.to be_falsey }
+      end
+    end
+
+    context "with any to and any from value on the callback" do
+      let(:callback) { Statesmin::Callback.new(callback: cb_lambda) }
+      let(:from) { :x }
+      let(:to) { :y }
+
+      it { is_expected.to be_truthy }
+    end
+
+    context "with any from value on the callback" do
+      let(:callback) do
+        Statesmin::Callback.new(to: [:y, :z], callback: cb_lambda)
+      end
+      let(:from) { :x }
+
+      context "and an allowed to value" do
+        let(:to) { :y }
+        it { is_expected.to be_truthy }
+      end
+
+      context "and another allowed to value" do
+        let(:to) { :z }
+        it { is_expected.to be_truthy }
+      end
+
+      context "and a disallowed to value" do
+        let(:to) { :a }
+        it { is_expected.to be_falsey }
+      end
+    end
+
+    context "with any to value on the callback" do
+      let(:callback) { Statesmin::Callback.new(from: :x, callback: cb_lambda) }
+      let(:to) { :y }
+
+      context "and an allowed to value" do
+        let(:from) { :x }
+        it { is_expected.to be_truthy }
+      end
+
+      context "and a disallowed to value" do
+        let(:from) { :a }
+        it { is_expected.to be_falsey }
+      end
+    end
+
+    context "with allowed 'from' and 'to' values" do
+      let(:from) { :x }
+      let(:to) { :y }
+      it { is_expected.to be_truthy }
+    end
+
+    context "with disallowed 'from' and 'to' values" do
+      let(:from) { :a }
+      let(:to) { :b }
+      it { is_expected.to be_falsey }
+    end
+  end
+end

data/spec/statesmin/guard_spec.rb

@@ -0,0 +1,22 @@
+require "spec_helper"
+
+describe Statesmin::Guard do
+  let(:callback) { -> {} }
+  let(:guard) { Statesmin::Guard.new(from: nil, to: nil, callback: callback) }
+
+  specify { expect(guard).to be_a(Statesmin::Callback) }
+
+  describe "#call" do
+    subject(:call) { guard.call }
+
+    context "success" do
+      let(:callback) { -> { true } }
+      specify { expect { call }.to_not raise_error }
+    end
+
+    context "error" do
+      let(:callback) { -> { false } }
+      specify { expect { call }.to raise_error(Statesmin::GuardFailedError) }
+    end
+  end
+end

data/spec/statesmin/machine_spec.rb

@@ -0,0 +1,704 @@
+require "spec_helper"
+
+describe Statesmin::Machine do
+  let(:machine) { Class.new { include Statesmin::Machine } }
+  let(:my_model) { Class.new { attr_accessor :current_state }.new }
+
+  describe ".state" do
+    before { machine.state(:x) }
+    before { machine.state(:y) }
+    specify { expect(machine.states).to eq(%w(x y)) }
+
+    context "initial" do
+      before { machine.state(:x, initial: true) }
+      specify { expect(machine.initial_state).to eq("x") }
+
+      context "when an initial state is already defined" do
+        it "raises an error" do
+          expect { machine.state(:y, initial: true) }.
+            to raise_error(Statesmin::InvalidStateError)
+        end
+      end
+    end
+  end
+
+  describe ".retry_conflicts" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+    let(:instance) { machine.new(my_model) }
+    let(:retry_attempts) { 2 }
+
+    subject(:transition_state) do
+      Statesmin::Machine.retry_conflicts(retry_attempts) do
+        instance.transition_to(:y)
+      end
+    end
+
+    context "when no exception occurs" do
+      it "runs the transition once" do
+        expect(instance).to receive(:transition_to).once
+        transition_state
+      end
+    end
+
+    context "when an irrelevant exception occurs" do
+      it "runs the transition once" do
+        expect(instance).
+          to receive(:transition_to).once.
+          and_raise(StandardError)
+        transition_state rescue nil # rubocop:disable RescueModifier
+      end
+
+      it "re-raises the exception" do
+        allow(instance).to receive(:transition_to).once.
+          and_raise(StandardError)
+        expect { transition_state }.to raise_error(StandardError)
+      end
+    end
+
+    context "when a TransitionConflictError occurs" do
+      context "and is resolved on the second attempt" do
+        it "runs the transition twice" do
+          expect(instance).
+            to receive(:transition_to).once.
+            and_raise(Statesmin::TransitionConflictError).
+            ordered
+          expect(instance).
+            to receive(:transition_to).once.ordered.and_call_original
+          transition_state
+        end
+      end
+
+      context "and keeps occurring" do
+        it "runs the transition `retry_attempts + 1` times" do
+          expect(instance).
+            to receive(:transition_to).
+            exactly(retry_attempts + 1).times.
+            and_raise(Statesmin::TransitionConflictError)
+          transition_state rescue nil # rubocop:disable RescueModifier
+        end
+
+        it "re-raises the conflict" do
+          allow(instance).
+            to receive(:transition_to).
+            and_raise(Statesmin::TransitionConflictError)
+          expect { transition_state }.
+            to raise_error(Statesmin::TransitionConflictError)
+        end
+      end
+    end
+  end
+
+  describe ".transition" do
+    before do
+      machine.class_eval do
+        state :x
+        state :y
+        state :z
+      end
+    end
+
+    context "given neither a 'from' nor a 'to' state" do
+      it "raises an error" do
+        expect { machine.transition }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "given no 'from' state and a valid 'to' state" do
+      it "raises an error" do
+        expect { machine.transition from: nil, to: :x }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "given a valid 'from' state and a no 'to' state" do
+      it "raises an error" do
+        expect { machine.transition from: :x, to: nil }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "given a valid 'from' state and an empty 'to' state array" do
+      it "raises an error" do
+        expect { machine.transition from: :x, to: [] }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "given an invalid 'from' state" do
+      it "raises an error" do
+        expect { machine.transition(from: :a, to: :x) }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "given an invalid 'to' state" do
+      it "raises an error" do
+        expect { machine.transition(from: :x, to: :a) }.
+          to raise_error(Statesmin::InvalidStateError)
+      end
+    end
+
+    context "valid 'from' and 'to' states" do
+      it "records the transition" do
+        machine.transition(from: :x, to: :y)
+        machine.transition(from: :x, to: :z)
+        expect(machine.successors).to eq("x" => %w(y z))
+      end
+    end
+  end
+
+  describe ".validate_callback_condition" do
+    before do
+      machine.class_eval do
+        state :x
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+
+    context "with a terminal 'from' state" do
+      it "raises an exception" do
+        expect { machine.validate_callback_condition(from: :z, to: :y) }.
+          to raise_error(Statesmin::InvalidTransitionError)
+      end
+    end
+
+    context "with an initial 'to' state" do
+      it "raises an exception" do
+        expect { machine.validate_callback_condition(from: :y, to: :x) }.
+          to raise_error(Statesmin::InvalidTransitionError)
+      end
+    end
+
+    context "with an invalid transition" do
+      it "raises an exception" do
+        expect { machine.validate_callback_condition(from: :x, to: :z) }.
+          to raise_error(Statesmin::InvalidTransitionError)
+      end
+    end
+
+    context "with any states" do
+      it "does not raise an exception" do
+        expect { machine.validate_callback_condition }.to_not raise_error
+      end
+    end
+
+    context "with a valid transition" do
+      it "does not raise an exception" do
+        expect { machine.validate_callback_condition(from: :x, to: :y) }.
+          to_not raise_error
+      end
+    end
+  end
+
+  shared_examples "a callback store" do |assignment_method, callback_store|
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: [:y, :z]
+      end
+    end
+
+    let(:options) { { from: nil, to: [] } }
+    let(:set_callback) { machine.send(assignment_method, options) {} }
+
+    shared_examples "fails" do |error_type|
+      specify { expect { set_callback }.to raise_error(error_type) }
+
+      it "does not add a callback" do
+        expect do
+          begin
+            set_callback
+          rescue error_type
+            nil
+          end
+        end.to_not change(machine.callbacks[callback_store], :count)
+      end
+    end
+
+    shared_examples "adds callback" do
+      specify { expect { set_callback }.to_not raise_error }
+
+      it "stores callbacks" do
+        expect { set_callback }.
+          to change(machine.callbacks[callback_store], :count).by(1)
+      end
+
+      it "stores callback instances" do
+        set_callback
+        machine.callbacks[callback_store].each do |callback|
+          expect(callback).to be_a(Statesmin::Callback)
+        end
+      end
+    end
+
+    context "with invalid states" do
+      context "when both are invalid" do
+        let(:options) { { from: :foo, to: :bar } }
+        it_behaves_like "fails", Statesmin::InvalidStateError
+      end
+
+      context "from a terminal state to anything" do
+        let(:options) { { from: :y, to: [] } }
+        it_behaves_like "fails", Statesmin::InvalidTransitionError
+      end
+
+      context "to an initial state and from anything" do
+        let(:options) { { from: nil, to: :x } }
+        it_behaves_like "fails", Statesmin::InvalidTransitionError
+      end
+
+      context "from a terminal state and to multiple states" do
+        let(:options) { { from: :y, to: [:x, :z] } }
+        it_behaves_like "fails", Statesmin::InvalidTransitionError
+      end
+
+      context "to an initial state and other states" do
+        let(:options) { { from: nil, to: [:y, :x, :z] } }
+        it_behaves_like "fails", Statesmin::InvalidTransitionError
+      end
+    end
+
+    context "with validate_states" do
+      context "from anything" do
+        let(:options) { { from: nil, to: :y } }
+        it_behaves_like "adds callback"
+      end
+
+      context "to anything" do
+        let(:options) { { from: :x, to: [] } }
+        it_behaves_like "adds callback"
+      end
+
+      context "to several" do
+        let(:options) { { from: :x, to: [:y, :z] } }
+        it_behaves_like "adds callback"
+      end
+
+      context "from any to several" do
+        let(:options) { { from: nil, to: [:y, :z] } }
+        it_behaves_like "adds callback"
+      end
+    end
+  end
+
+  describe ".before_transition" do
+    it_behaves_like "a callback store", :before_transition, :before
+  end
+
+  describe ".after_transition" do
+    it_behaves_like "a callback store", :after_transition, :after
+  end
+
+  describe ".guard_transition" do
+    it_behaves_like "a callback store", :guard_transition, :guards
+  end
+
+  describe "#initialize" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+      end
+    end
+
+    it "accepts an object to manipulate" do
+      machine_instance = machine.new(my_model)
+      expect(machine_instance.object).to be(my_model)
+    end
+
+    context "with a state option given" do
+      context "and the option is a valid state" do
+        it "sets the current_state to the supplied state option" do
+          machine_instance = machine.new(my_model, state: :y)
+          expect(machine_instance.current_state).to eq("y")
+        end
+      end
+
+      context "and the option is not a valid state" do
+        it "raises an InvalidStateError" do
+          expect { machine.new(my_model, state: :xyz) }.
+            to raise_error(Statesmin::InvalidStateError)
+        end
+      end
+    end
+
+    context "without a state option given" do
+      it "sets the current_state to the class defined initial state" do
+        machine_instance = machine.new(my_model)
+        expect(machine_instance.current_state).to eq("x")
+      end
+    end
+  end
+
+  describe "#after_initialize" do
+    it "is called after initialize" do
+      machine.class_eval do
+        def after_initialize; end
+      end
+      expect_any_instance_of(machine).to receive :after_initialize
+      machine.new(my_model)
+    end
+  end
+
+  describe "#current_state" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    subject { instance.current_state }
+
+    context "with no transitions" do
+      it { is_expected.to eq(machine.initial_state) }
+    end
+
+    context "with multiple transitions" do
+      before { instance.transition_to!(:y) }
+      before { instance.transition_to!(:z) }
+
+      it { is_expected.to eq("z") }
+    end
+  end
+
+  describe "#in_state?" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        transition from: :x, to: :y
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    subject { instance.in_state?(state) }
+    before { instance.transition_to!(:y) }
+
+    context "when machine is in given state" do
+      let(:state) { "y" }
+      it { is_expected.to eq(true) }
+    end
+
+    context "when machine is not in given state" do
+      let(:state) { "x" }
+      it { is_expected.to eq(false) }
+    end
+
+    context "when given a symbol" do
+      let(:state) { :y }
+      it { is_expected.to eq(true) }
+    end
+
+    context "when given multiple states" do
+      context "when given multiple arguments" do
+        context "when one of the states is the current state" do
+          subject { instance.in_state?(:x, :y) }
+          it { is_expected.to eq(true) }
+        end
+
+        context "when none of the states are the current state" do
+          subject { instance.in_state?(:x, :z) }
+          it { is_expected.to eq(false) }
+        end
+      end
+
+      context "when given an array" do
+        context "when one of the states is the current state" do
+          subject { instance.in_state?([:x, :y]) }
+          it { is_expected.to eq(true) }
+        end
+
+        context "when none of the states are the current state" do
+          subject { instance.in_state?([:x, :z]) }
+          it { is_expected.to eq(false) }
+        end
+      end
+    end
+  end
+
+  describe "#allowed_transitions" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: [:y, :z]
+        transition from: :y, to: :z
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    subject { instance.allowed_transitions }
+
+    context "with multiple possible states" do
+      it { is_expected.to eq(%w(y z)) }
+    end
+
+    context "with one possible state" do
+      before { instance.transition_to!(:y) }
+      it { is_expected.to eq(['z']) }
+    end
+
+    context "with no possible transitions" do
+      before { instance.transition_to!(:z) }
+      it { is_expected.to eq([]) }
+    end
+  end
+
+  describe "#can_transition_to?" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    subject { instance.can_transition_to?(new_state) }
+
+    context "when the transition is invalid" do
+      context "with an initial to state" do
+        let(:new_state) { :x }
+        it { is_expected.to be_falsey }
+      end
+
+      context "with a terminal from state" do
+        before { instance.transition_to!(:y) }
+        let(:new_state) { :y }
+        it { is_expected.to be_falsey }
+      end
+
+      context "and is guarded" do
+        let(:guard_cb) { -> { false } }
+        let(:new_state) { :z }
+        before { machine.guard_transition(to: new_state, &guard_cb) }
+
+        it "does not fire guard" do
+          expect(guard_cb).not_to receive(:call)
+          is_expected.to be_falsey
+        end
+      end
+    end
+
+    context "when the transition valid" do
+      let(:new_state) { :y }
+      it { is_expected.to be_truthy }
+
+      context "but it has a failing guard" do
+        before { machine.guard_transition(to: :y) { false } }
+        it { is_expected.to be_falsey }
+      end
+    end
+  end
+
+  describe "#transition_to!" do
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+
+    context "when it is called with a block" do
+      let(:block_spy)   { double(called: 'called') }
+      let(:block) { proc { block_spy.called } }
+
+      context "and the state cannot be transitioned to" do
+        it "does not call the block" do
+          expect(block_spy).to_not receive(:called)
+          expect { instance.transition_to!(:z, &block) }.to raise_error
+        end
+      end
+
+      context "and the state can be transitioned to" do
+        it "calls the block" do
+          expect(block_spy).to receive(:called)
+          instance.transition_to(:y, &block)
+        end
+
+        context 'and the block errors' do
+          let(:error_block) { proc { raise } }
+
+          it "raises the error" do
+            expect { instance.transition_to(:y, &error_block) }.
+              to raise_error(RuntimeError)
+          end
+
+          it "does not change the current_state" do
+            expect { instance.transition_to(:y, &error_block) }.to raise_error
+            expect(instance.current_state).to eq('x')
+          end
+        end
+
+        context 'and the block does not error' do
+          it "returns the value of the block" do
+            expect(instance.transition_to(:y, &block)).to eq('called')
+          end
+
+          it "updates the current_state" do
+            instance.transition_to(:y, &block)
+            expect(instance.current_state).to eq('y')
+          end
+        end
+      end
+    end
+
+    context "when the state cannot be transitioned to" do
+      it "raises an error" do
+        expect { instance.transition_to!(:z) }.
+          to raise_error(Statesmin::TransitionFailedError)
+      end
+    end
+
+    context "when the state can be transitioned to" do
+      it "changes state" do
+        instance.transition_to!(:y)
+        expect(instance.current_state).to eq("y")
+      end
+
+      specify { expect(instance.transition_to!(:y)).to eq(true) }
+
+      context "with a guard" do
+        let(:result) { true }
+        let(:guard_cb) { ->(*_args) { result } }
+        before { machine.guard_transition(from: :x, to: :y, &guard_cb) }
+
+        context "and an object to act on" do
+          let(:instance) { machine.new(my_model) }
+
+          it "passes the object to the guard" do
+            expect(guard_cb).to receive(:call).once.
+              with(my_model, {}).and_return(true)
+            instance.transition_to!(:y)
+          end
+        end
+
+        context "which passes" do
+          it "changes state" do
+            instance.transition_to!(:y)
+            expect(instance.current_state).to eq("y")
+          end
+        end
+
+        context "which fails" do
+          let(:result) { false }
+
+          it "raises an exception" do
+            expect { instance.transition_to!(:y) }.
+              to raise_error(Statesmin::GuardFailedError)
+          end
+        end
+      end
+    end
+  end
+
+  describe "#transition_to" do
+    let(:instance) { machine.new(my_model) }
+    let(:metadata) { { some: :metadata } }
+    subject { instance.transition_to(:some_state, metadata, &proc {}) }
+
+    context "when it is succesful" do
+      before do
+        expect(instance).to receive(:transition_to!).once.
+          with(:some_state, metadata).and_return(:some_state)
+      end
+      it { is_expected.to be(:some_state) }
+    end
+
+    context "when it is unsuccesful" do
+      before do
+        allow(instance).to receive(:transition_to!).
+          and_raise(Statesmin::GuardFailedError)
+      end
+      it { is_expected.to be_falsey }
+    end
+
+    context "when a non statesmin exception is raised" do
+      before do
+        allow(instance).to receive(:transition_to!).
+          and_raise(RuntimeError, 'user defined exception')
+      end
+
+      it "should not rescue the exception" do
+        expect { instance.transition_to(:some_state, metadata) }.
+          to raise_error(RuntimeError, 'user defined exception')
+      end
+    end
+  end
+
+  shared_examples "a callback filter" do |definer, phase|
+    before do
+      machine.class_eval do
+        state :x
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+      end
+    end
+
+    let(:instance) { machine.new(my_model) }
+    let(:callbacks) { instance.send(:callbacks_for, phase, from: :x, to: :y) }
+
+    context "with no defined callbacks" do
+      specify { expect(callbacks).to eq([]) }
+    end
+
+    context "with defined callbacks" do
+      let(:callback_1) { -> { "Hi" } }
+      let(:callback_2) { -> { "Bye" } }
+
+      before do
+        machine.send(definer, from: :x, to: :y, &callback_1)
+        machine.send(definer, from: :y, to: :z, &callback_2)
+      end
+
+      it "contains the relevant callback" do
+        expect(callbacks.map(&:callback)).to include(callback_1)
+      end
+
+      it "does not contain the irrelevant callback" do
+        expect(callbacks.map(&:callback)).to_not include(callback_2)
+      end
+    end
+  end
+
+  describe "#guards_for" do
+    it_behaves_like "a callback filter", :guard_transition, :guards
+  end
+
+  describe "#before_callbacks_for" do
+    it_behaves_like "a callback filter", :before_transition, :before
+  end
+
+  describe "#after_callbacks_for" do
+    it_behaves_like "a callback filter", :after_transition, :after
+  end
+end