statesman 0.0.1

data/spec/statesman/adapters/memory_spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+require "statesman/adapters/shared_examples"
+
+describe Statesman::Adapters::Memory do
+  let(:model) { Class.new { attr_accessor :current_state }.new }
+  it_behaves_like "an adapter", described_class, Statesman::Transition
+end

data/spec/statesman/adapters/shared_examples.rb

@@ -0,0 +1,111 @@
+require "spec_helper"
+
+# All adpators must define seven methods:
+#   initialize:       Accepts a transition class, parent model and state_attr.
+#   transition_class: Returns the transition class object passed to initialize.
+#   parent_model:     Returns the model class object passed to initialize.
+#   state_attr:       Returns the state attribute to set on the parent.
+#   create:           Accepts to_state, before callbacks, after callbacks and
+#                     optional metadata. Creates a new transition class
+#                     instance and saves metadata to it.
+#   history:          Returns the full transition history
+#   last:             Returns the latest transition history item
+#
+shared_examples_for "an adapter" do |adapter_class, transition_class|
+  let(:adapter) { adapter_class.new(transition_class, model) }
+  let(:before_cbs) { [] }
+  let(:after_cbs) { [] }
+
+  describe "#initialize" do
+    subject { adapter }
+    its(:transition_class) { should be(transition_class) }
+    its(:parent_model) { should be(model) }
+    its(:history) { should eq([]) }
+  end
+
+  describe "#create" do
+    let(:to) { :y }
+    let(:create) { adapter.create(to, before_cbs, after_cbs) }
+    subject { -> { create } }
+
+    it { should change(adapter.history, :count).by(1) }
+
+    context "the new transition" do
+      subject { create }
+      it { should be_a(transition_class) }
+      its(:to_state) { should be(to) }
+
+      context "with no previous transition" do
+        its(:sort_key) { should be(0) }
+      end
+
+      context "with a previous transition" do
+        before { adapter.create(:x, before_cbs, after_cbs) }
+        its(:sort_key) { should be(10) }
+      end
+    end
+
+    context "with before callbacks" do
+      let(:callback) { double(call: true) }
+      let(:before_cbs) { [callback] }
+
+      it "is called before the state transition" do
+        callback.should_receive(:call).with do |passed_model, transition|
+          expect(passed_model).to be(model)
+          expect(transition).to be_a(adapter.transition_class)
+          expect(adapter.history.length).to eq(0)
+        end.once
+
+        adapter.create(:x, before_cbs, after_cbs)
+        expect(adapter.history.length).to eq(1)
+      end
+    end
+
+    context "with after callbacks" do
+      let(:callback) { double(call: true) }
+      let(:after_cbs) { [callback] }
+
+      it "is called after the state transition" do
+        callback.should_receive(:call).with do |passed_model, transition|
+          expect(passed_model).to be(model)
+          expect(adapter.last).to eq(transition)
+        end.once
+        adapter.create(:x, before_cbs, after_cbs)
+      end
+    end
+
+    context "with metadata" do
+      let(:metadata) { { "some" => "hash" } }
+      subject { adapter.create(to, before_cbs, after_cbs, metadata) }
+      its(:metadata) { should eq(metadata) }
+    end
+  end
+
+  describe "#history" do
+    subject { adapter.history }
+    it { should eq([]) }
+
+    context "with transitions" do
+      let!(:transition) { adapter.create(:y, before_cbs, after_cbs) }
+      it { should eq([transition]) }
+
+      context "sorting" do
+        let!(:transition) { adapter.create(:y, before_cbs, after_cbs) }
+        let!(:transition2) { adapter.create(:y, before_cbs, after_cbs) }
+        subject { adapter.history }
+        it { should eq(adapter.history.sort_by(&:sort_key)) }
+      end
+    end
+  end
+
+  describe "#last" do
+    before do
+      adapter.create(:y, before_cbs, after_cbs)
+      adapter.create(:z, before_cbs, after_cbs)
+    end
+    subject { adapter.last }
+
+    it { should be_a(transition_class) }
+    specify { expect(adapter.last.to_state.to_sym).to eq(:z) }
+  end
+end

data/spec/statesman/callback_spec.rb

@@ -0,0 +1,119 @@
+require "spec_helper"
+
+describe Statesman::Callback do
+  let(:cb_lambda) { -> { } }
+  let(:callback) do
+    Statesman::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(Statesman::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
+      Statesman::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 { should be_true }
+      end
+
+      context "and a disallowed to value" do
+        let(:to) { :a }
+        it { should be_false }
+      end
+    end
+
+    context "with any to value" do
+      let(:to) { nil }
+
+      context "and an allowed 'from' value" do
+        let(:from) { :x }
+        it { should be_true }
+      end
+
+      context "and a disallowed 'from' value" do
+        let(:from) { :a }
+        it { should be_false }
+      end
+    end
+
+    context "with any to and any from value on the callback" do
+      let(:callback) do
+        Statesman::Callback.new(callback: cb_lambda)
+      end
+      let(:from) { :x }
+      let(:to) { :y }
+
+      it { should be_true }
+    end
+
+    context "with any from value on the callback" do
+      let(:callback) do
+        Statesman::Callback.new(to: :y, callback: cb_lambda)
+      end
+      let(:from) { :x }
+
+      context "and an allowed to value" do
+        let(:to) { :y }
+        it { should be_true }
+      end
+
+      context "and a disallowed to value" do
+        let(:to) { :a }
+        it { should be_false }
+      end
+    end
+
+    context "with any to value on the callback" do
+      let(:callback) do
+        Statesman::Callback.new(from: :x, callback: cb_lambda)
+      end
+      let(:to) { :y }
+
+      context "and an allowed to value" do
+        let(:from) { :x }
+        it { should be_true }
+      end
+
+      context "and a disallowed to value" do
+        let(:from) { :a }
+        it { should be_false }
+      end
+    end
+
+    context "with allowed 'from' and 'to' values" do
+      let(:from) { :x }
+      let(:to) { :y }
+      it { should be_true }
+    end
+
+    context "with disallowed 'from' and 'to' values" do
+      let(:from) { :a }
+      let(:to) { :b }
+      it { should be_false }
+    end
+  end
+end

data/spec/statesman/config_spec.rb

@@ -0,0 +1,34 @@
+require "spec_helper"
+
+describe Statesman::Config do
+  let(:instance) { Statesman::Config.new }
+
+  after do
+    # Don't leak global config changes into other specs
+    Statesman.configure { storage_adapter(Statesman::Adapters::Memory) }
+  end
+
+  describe "#storage_adapter" do
+    let(:adapter) { Class.new }
+    before  { instance.storage_adapter(adapter) }
+    subject { instance.adapter_class }
+    it { should be(adapter) }
+
+    it "is DSL configurable" do
+      new_adapter = adapter
+      Statesman.configure { storage_adapter(new_adapter) }
+
+      defined_adapter = nil
+      Statesman.instance_eval { defined_adapter = @storage_adapter }
+      expect(defined_adapter).to be(new_adapter)
+    end
+  end
+
+  describe "#transition_class" do
+    it "serializes metadata to JSON" do
+      klass = Class.new
+      klass.should_receive(:serialize).once.with(:metadata, JSON)
+      Statesman.configure { transition_class(klass) }
+    end
+  end
+end

data/spec/statesman/guard_spec.rb

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

data/spec/statesman/machine_spec.rb

@@ -0,0 +1,459 @@
+require "spec_helper"
+
+describe Statesman::Machine do
+  let(:machine) { Class.new { include Statesman::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 do
+            machine.state(:y, initial: true)
+          end.to raise_error(Statesman::InvalidStateError)
+        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 do
+          machine.transition
+        end.to raise_error(Statesman::InvalidStateError)
+      end
+    end
+
+    context "given an invalid 'from' state" do
+      it "raises an error" do
+        expect do
+          machine.transition(from: :a, to: :x)
+        end.to raise_error(Statesman::InvalidStateError)
+      end
+    end
+
+    context "given an invalid 'to' state" do
+      it "raises an error" do
+        expect do
+          machine.transition(from: :x, to: :a)
+        end.to raise_error(Statesman::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 do
+          machine.validate_callback_condition(from: :z, to: :y)
+        end.to raise_error(Statesman::InvalidTransitionError)
+      end
+    end
+
+    context "with an initial 'to' state" do
+      it "raises an exception" do
+        expect do
+          machine.validate_callback_condition(from: :y, to: :x)
+        end.to raise_error(Statesman::InvalidTransitionError)
+      end
+    end
+
+    context "with an invalid transition" do
+      it "raises an exception" do
+        expect do
+          machine.validate_callback_condition(from: :x, to: :z)
+        end.to raise_error(Statesman::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 do
+          machine.validate_callback_condition(from: :x, to: :y)
+        end.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
+        transition from: :x, to: :y
+      end
+    end
+
+    it "stores callbacks" do
+      expect do
+        machine.send(assignment_method) {}
+      end.to change(machine.send(callback_store), :count).by(1)
+    end
+
+    it "stores callback instances" do
+      machine.send(assignment_method) {}
+
+      machine.send(callback_store).each do |callback|
+        expect(callback).to be_a(Statesman::Callback)
+      end
+    end
+
+    context "with invalid states" do
+      it "raises an exception when both are invalid" do
+        expect do
+          machine.send(assignment_method, from: :foo, to: :bar) {}
+        end.to raise_error(Statesman::InvalidStateError)
+      end
+
+      it "raises an exception with a terminal from state and nil to state" do
+        expect do
+          machine.send(assignment_method, from: :y) {}
+        end.to raise_error(Statesman::InvalidTransitionError)
+      end
+
+      it "raises an exception with an initial to state and nil from state" do
+        expect do
+          machine.send(assignment_method, to: :x) {}
+        end.to raise_error(Statesman::InvalidTransitionError)
+      end
+    end
+
+    context "with validate_states" do
+      it "allows a nil from state" do
+        expect do
+          machine.send(assignment_method, to: :y) {}
+        end.to_not raise_error
+      end
+
+      it "allows a nil to state" do
+        expect do
+          machine.send(assignment_method, from: :x) {}
+        end.to_not raise_error
+      end
+    end
+  end
+
+  describe ".before_transition" do
+    it_behaves_like "a callback store", :before_transition, :before_callbacks
+  end
+
+  describe ".after_transition" do
+    it_behaves_like "a callback store", :after_transition, :after_callbacks
+  end
+
+  describe ".guard_transition" do
+    it_behaves_like "a callback store", :guard_transition, :guards
+  end
+
+  describe "#initialize" do
+    it "accepts an object to manipulate" do
+      machine_instance = machine.new(my_model)
+      expect(machine_instance.object).to be(my_model)
+    end
+
+    context "transition class" do
+      it "sets a default" do
+        Statesman.storage_adapter.should_receive(:new).once
+          .with(Statesman::Transition, my_model)
+        machine.new(my_model)
+      end
+
+      it "sets the passed class" do
+        my_transition_class = Class.new
+        Statesman.storage_adapter.should_receive(:new).once
+          .with(my_transition_class, my_model)
+        machine.new(my_model, transition_class: my_transition_class)
+      end
+    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 { should eq(machine.initial_state) }
+    end
+
+    context "with multiple transitions" do
+      before do
+        instance.transition_to!(:y)
+        instance.transition_to!(:z)
+      end
+
+      it { should eq("z") }
+    end
+  end
+
+  describe "#last_transition" do
+    let(:instance) { machine.new(my_model) }
+    let(:last_action) { "Whatever" }
+
+    it "delegates to the storage adapter" do
+      Statesman.storage_adapter.any_instance.should_receive(:last).once
+        .and_return(last_action)
+      expect(instance.last_transition).to be(last_action)
+    end
+  end
+
+  describe "#can_transition_to?" 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.can_transition_to?(new_state) }
+
+    context "when the transition is invalid" do
+      context "with an initial to state" do
+        let(:new_state) { :x }
+        it { should be_false }
+      end
+
+      context "with a terminal from state" do
+        before { instance.transition_to!(:y) }
+        let(:new_state) { :y }
+        it { should be_false }
+      end
+    end
+
+    context "when the transition valid" do
+      let(:new_state) { :y }
+      it { should be_true }
+
+      context "but it has a failing guard" do
+        before { machine.guard_transition(to: :y) { false } }
+        it { should be_false }
+      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 the state cannot be transitioned to" do
+      it "raises an error" do
+        expect do
+          instance.transition_to!(:z)
+        end.to raise_error(Statesman::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
+
+      it "creates a new transition object" do
+        expect do
+          instance.transition_to!(:y)
+        end.to change(instance.history, :count).by(1)
+
+        expect(instance.history.first).to be_a(Statesman::Transition)
+        expect(instance.history.first.to_state).to eq("y")
+      end
+
+      it "sends metadata to the transition object" do
+        meta = { "my" => "hash" }
+        instance.transition_to!(:y, meta)
+        expect(instance.history.first.metadata).to eq(meta)
+      end
+
+      it "returns true" do
+        expect(instance.transition_to!(:y)).to be_true
+      end
+
+      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
+            guard_cb.should_receive(:call).once
+              .with(my_model, instance.last_transition, nil).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 do
+              instance.transition_to!(:y)
+            end.to raise_error(Statesman::GuardFailedError)
+          end
+        end
+      end
+
+      context "with a before callback" do
+        let(:callbacks) { [] }
+        before { instance.stub(:before_callbacks_for).and_return(callbacks) }
+
+        it "is passed to the adapter" do
+          Statesman::Adapters::Memory.any_instance.should_receive(:create)
+            .with("y", callbacks, anything, anything)
+          instance.transition_to!(:y)
+        end
+      end
+
+      context "with an after callback" do
+        let(:callbacks) { [] }
+        before { instance.stub(:after_callbacks_for).and_return(callbacks) }
+
+        it "is passed to the adapter" do
+          Statesman::Adapters::Memory.any_instance.should_receive(:create)
+            .with("y", anything, callbacks, anything)
+          instance.transition_to!(:y)
+        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) }
+
+    context "when it is succesful" do
+      before do
+        instance.should_receive(:transition_to!).once
+          .with(:some_state, metadata).and_return(:some_state)
+      end
+      it { should be(:some_state) }
+    end
+
+    context "when it is unsuccesful" do
+      before do
+        instance.stub(:transition_to!).and_raise(Statesman::GuardFailedError)
+      end
+      it { should be_false }
+    end
+  end
+
+  shared_examples "a callback filter" do |definer, getter|
+    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(getter, 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_for
+  end
+
+  describe "#before_callbacks_for" do
+    it_behaves_like "a callback filter", :before_transition,
+                    :before_callbacks_for
+  end
+
+  describe "#after_callbacks_for" do
+    it_behaves_like "a callback filter", :after_transition,
+                    :after_callbacks_for
+  end
+end