mattsnyder-stately 0.2.1

data/spec/functional/stately_spec.rb

@@ -0,0 +1,305 @@
+require 'ostruct'
+require 'spec_helper'
+
+describe Stately do
+  before do
+    @order_class = Class.new(OpenStruct) do
+      stately :start => :processing do
+        state :completed do
+          prevent_from :refunded
+
+          before_transition :from => :processing, :do => :before_completed
+          before_transition :from => :invalid, :do => :cleanup_invalid
+          after_transition :do => :after_completed
+
+          validate :validates_amount
+          validate :validates_credit_card
+        end
+
+        state :invalid do
+          prevent_from :completed, :refunded
+        end
+
+        state :processing do
+          prevent_from :completed, :invalid, :refunded
+        end
+
+        state :refunded do
+          allow_from :completed
+
+          before_transition :from => :completed, :do => :before_refunded
+          after_transition :from => :completed, :do => :after_refunded
+        end
+      end
+
+      private
+
+      def before_completed
+        self.serial_number = Time.now.usec
+      end
+
+      def after_completed
+      end
+
+      def before_refunded
+        self.refunded_reason = 'Overcharged'
+      end
+
+      def after_refunded
+      end
+
+      def cleanup_invalid
+        self.serial_number = nil
+      end
+
+      def validates_amount
+        amount > 0.0 && amount < 100.0
+      end
+
+      def validates_credit_card
+        self.cc_number == 123
+      end
+    end
+  end
+
+  def self.should_call_callbacks_on_complete(order)
+    @order = order
+
+    describe 'callbacks' do
+      it 'calls callbacks in order' do
+        @order.should_receive(:before_completed).ordered
+        @order.should_receive(:after_completed).ordered
+        @order.should_not_receive :cleanup_invalid
+
+        @order.complete
+      end
+
+      it 'sets serial_number' do
+        @order.serial_number.should be_nil
+        @order.complete
+        @order.serial_number.should_not be_nil
+      end
+    end
+  end
+
+  def self.should_call_validations_on_complete(order)
+    @order = order
+
+    describe 'validations' do
+      it 'calls validations in order' do
+        @order.should_receive(:validates_amount).ordered
+        @order.should_receive(:validates_credit_card).ordered
+
+        @order.complete
+      end
+
+      describe 'return values' do
+        before do
+          @order.stub :validates_amount => false
+        end
+
+        it 'should halt on false' do
+          @order.should_receive :validates_amount
+          @order.should_receive :validates_credit_card
+          @order.should_not_receive :before_completed
+          @order.should_not_receive :after_completed
+          @order.should_not_receive :cleanup_invalid
+
+          current_state = @order.state
+          @order.complete
+          @order.state.should == current_state
+        end
+      end
+    end
+  end
+
+  def self.should_prevent_transition(from, to, action)
+    before do
+      @order = @order_class.new(:amount => 99, :cc_number => 123)
+      @order.state = from
+    end
+
+    it 'should be prevented' do
+      lambda { @order.send(action) }.should raise_error(Stately::InvalidTransition,
+        "Prevented transition from #{from} to #{to}.")
+    end
+  end
+
+  def self.should_set_state(new_state, order, action)
+    @order = order
+
+    describe 'on success' do
+      before do
+        @order.send action
+      end
+
+      it 'sets state' do
+        @order.state.should == new_state
+      end
+    end
+  end
+
+  describe 'initial state' do
+    before do
+      @order = @order_class.new(:amount => 99, :cc_number => 123)
+    end
+
+    it 'creates actions for each state' do
+      @order_class.method_defined?(:complete).should be_true
+      @order_class.method_defined?(:process).should be_true
+      @order_class.method_defined?(:refund).should be_true
+    end
+
+    it 'finds all states' do
+      @order.states.should == [:completed, :invalid, :processing, :refunded]
+    end
+
+    it 'sets initial state to processing' do
+      @order.state.should == 'processing'
+    end
+  end
+
+  describe '#process' do
+    describe 'from processing' do
+      should_prevent_transition('processing', 'processing', :process)
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'processing', :process)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'processing', :process)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'processing', :process)
+    end
+  end
+
+  describe '#complete' do
+    before do
+      @order = @order_class.new(:amount => 99, :cc_number => 123)
+    end
+
+    describe 'from processing' do
+      should_call_validations_on_complete(@order)
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:before_completed).ordered
+          @order.should_receive(:after_completed).ordered
+          @order.should_not_receive :cleanup_invalid
+
+          @order.complete
+        end
+
+        it 'sets serial_number' do
+          @order.serial_number.should be_nil
+          @order.complete
+          @order.serial_number.should_not be_nil
+        end
+      end
+
+      should_set_state('completed', @order, :complete)
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'completed', :complete)
+    end
+
+    describe 'from invalid' do
+      before do
+        @order.serial_number = Time.now.usec
+        @order.state = 'invalid'
+      end
+
+      should_call_validations_on_complete(@order)
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:cleanup_invalid).ordered
+          @order.should_receive(:after_completed).ordered
+          @order.should_not_receive :before_completed
+
+          @order.complete
+        end
+
+        it 'sets serial_number to nil' do
+          @order.serial_number.should_not be_nil
+          @order.complete
+          @order.serial_number.should be_nil
+        end
+      end
+
+      should_set_state('completed', @order, :complete)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'completed', :complete)
+    end
+  end
+
+  describe '#invalidate' do
+    describe 'from processing' do
+      before do
+        @order = @order_class.new(:amount => 99, :cc_number => 123)
+        @order.invalidate
+      end
+
+      it 'sets state' do
+        @order.state.should == 'invalid'
+      end
+    end
+
+    describe 'from completed' do
+      should_prevent_transition('completed', 'invalid', :invalidate)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'invalid', :invalidate)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'invalid', :invalidate)
+    end
+  end
+
+  describe '#refund' do
+    describe 'from processing' do
+      should_prevent_transition('processing', 'refunded', :refund)
+    end
+
+    describe 'from completed' do
+      before do
+        @order = @order_class.new(:amount => 99, :cc_number => 123)
+        @order.state = 'completed'
+      end
+
+      describe 'callbacks' do
+        it 'calls callbacks in order' do
+          @order.should_receive(:before_refunded).ordered
+          @order.should_receive(:after_refunded).ordered
+
+          @order.refund
+        end
+
+        it 'sets refunded_reason' do
+          @order.refunded_reason.should be_nil
+          @order.refund
+          @order.refunded_reason.should_not be_nil
+        end
+      end
+
+      should_set_state('refunded', @order, :refund)
+    end
+
+    describe 'from invalid' do
+      should_prevent_transition('invalid', 'refunded', :refund)
+    end
+
+    describe 'from refunded' do
+      should_prevent_transition('refunded', 'refunded', :refund)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH << File.join(File.dirname(__FILE__))
+
+require 'rspec'
+require 'stately'

data/spec/unit/stately/machine_spec.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+
+describe Stately::Machine do
+  before do
+    @machine = Stately::Machine.new(:state, :processing)
+  end
+
+  describe 'initialize' do
+    it 'sets initial vars' do
+      @machine.start.should == :processing
+      @machine.state_attr.should == :state
+      @machine.states.map(&:to_s).should == ['processing']
+    end
+
+    it 'guesses the initial action' do
+      @machine.states.first.action.should == 'process'
+    end
+  end
+
+  describe '#state' do
+    describe 'with name only' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:completed)
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'completed']
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing)
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+      end
+    end
+
+    describe 'with name and action' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:new_state, :action =>  :transition_to_new_state)
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'new_state']
+        end
+
+        it 'adds the correct action to the new state' do
+          @machine.states.last.action.should == 'transition_to_new_state'
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing, :action =>  :transition_to_processing)
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+
+        it 'adds the correct action to the existing state' do
+          @machine.states.first.action.should == 'transition_to_processing'
+        end
+      end
+    end
+
+    describe 'with name, action, and block' do
+      describe 'of a new state' do
+        before do
+          @machine.state(:new_state, :action =>  :transition_to_new_state) do
+            allow_from :completed
+          end
+
+          @new_state = @machine.states.last
+        end
+
+        it 'adds a new state' do
+          @machine.states.map(&:to_s).should == ['processing', 'new_state']
+        end
+
+        it 'adds the correct action to the new state' do
+          @new_state.action.should == 'transition_to_new_state'
+        end
+
+        it 'includes the allow_from param' do
+          @new_state.allow_from_states.should == [:completed]
+        end
+      end
+
+      describe 'of a previously defined state' do
+        before do
+          @machine.state(:processing, :action =>  :transition_to_processing) do
+            allow_from :completed
+          end
+
+          @new_state = @machine.states.last
+        end
+
+        it "doesn't add a new state" do
+          @machine.states.map(&:to_s).should == ['processing']
+        end
+
+        it 'adds the correct action to the new state' do
+          @new_state.action.should == 'transition_to_processing'
+        end
+
+        it 'includes the allow_from param' do
+          @new_state.allow_from_states.should == [:completed]
+        end
+      end
+    end
+  end
+end

data/spec/unit/stately/state_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe Stately::State do
+  describe 'initialize' do
+    describe 'with a block given' do
+      describe 'new' do
+        before do
+          @state = Stately::State.new(:invalid, nil) do
+            allow_from :completed
+            prevent_from :completed, :refunded
+
+            before_transition :do => :prepare
+            before_transition :from => :processing, :do => :before_completed
+            after_transition :do => :cleanup
+            after_transition :from => :processing, :do => :after_processing
+
+            validate :validates_amount
+            validate :validates_credit_card
+          end
+        end
+
+        it 'should set initial values' do
+          @state.name.should == :invalid
+
+          @state.allow_from_states.should == [:completed]
+          @state.prevent_from_states.should == [:completed, :refunded]
+
+          @state.before_transitions.should == [{:do => :prepare}, {:from => :processing,
+            :do => :before_completed}]
+          @state.after_transitions.should == [{:do => :cleanup}, {:from => :processing,
+            :do => :after_processing}]
+          @state.validations.should == [:validates_amount, :validates_credit_card]
+        end
+      end
+    end
+
+    describe 'without a block given' do
+      describe 'new' do
+        before do
+          @state = Stately::State.new(:test_state)
+        end
+
+        it 'should set initial values' do
+          @state.name.should == :test_state
+
+          @state.allow_from_states.should == []
+          @state.prevent_from_states.should == []
+
+          @state.before_transitions.should == []
+          @state.after_transitions.should == []
+          @state.validations.should == []
+        end
+      end
+
+      describe 'with a given action' do
+        before do
+          @state = Stately::State.new(:test_state, :test_action)
+        end
+
+        it 'should set the given action name' do
+          @state.action.should == 'test_action'
+        end
+      end
+
+      describe 'without a given action' do
+        before do
+          @actions = { :completed => :complete, :converting => :convert, :invalid => :invalidate,
+            :preparing => :prepare, :processing => :process, :refunded => :refund, :reticulating => :reticulate,
+            :saving => :save, :searching => :search, :started => :start, :stopped => :stop }
+        end
+
+        it 'should set the correct action verb' do
+          @actions.map do |state_name, action_name|
+            state = Stately::State.new(state_name)
+            state.action.should == action_name.to_s
+          end
+        end
+      end
+    end
+  end
+
+  describe '#to_s' do
+    before do
+      @state = Stately::State.new(:test_state)
+    end
+
+    it 'should return a string' do
+      @state.to_s.should == 'test_state'
+    end
+  end
+
+  describe '#to_sym' do
+    before do
+      @state = Stately::State.new('test_state')
+    end
+
+    it 'should return a symbol' do
+      @state.to_sym.should == :test_state
+    end
+  end
+end

data/spec/unit/stately_spec.rb

@@ -0,0 +1,58 @@
+require 'ostruct'
+require 'spec_helper'
+
+describe Stately::InstanceMethods do
+  before do
+    @test_class = Class.new(Object) do
+      attr_accessor :state
+
+      stately :start => :processing do
+        state :completed
+      end
+    end
+
+    @object = @test_class.new
+  end
+
+  describe 'initialize' do
+    it 'creates a new Stately::Machine' do
+      @object.stately_machine.class.should == Stately::Machine
+      @object.stately_machine.should == @test_class.stately_machine
+    end
+
+    it 'sets initial state' do
+      @object.state.should == 'processing'
+    end
+  end
+
+  describe '#states' do
+    it 'returns known state names in order' do
+      @object.states.should == [:processing, :completed]
+    end
+  end
+
+  describe 'actions' do
+    it 'defines action methods' do
+      @test_class.method_defined?(:complete).should be_true
+      @test_class.method_defined?(:process).should be_true
+    end
+  end
+
+  describe 'stately_machine' do
+    it 'defines a class-level accessor called stately_machine' do
+      @test_class.respond_to?(:stately_machine).should be_true
+    end
+
+    it 'defines an instance-level accessor called stately_machine' do
+      @test_class.method_defined?(:stately_machine).should be_true
+    end
+
+    it 'defines a class-level setter called stately_machine=' do
+      @test_class.respond_to?(:stately_machine=).should be_true
+    end
+
+    it 'defines an instance-level setter called stately_machine=' do
+      @test_class.method_defined?(:stately_machine=).should be_true
+    end
+  end
+end

data/stately.gemspec

@@ -0,0 +1,23 @@
+$LOAD_PATH << File.expand_path('../lib', __FILE__)
+require 'stately/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'mattsnyder-stately'
+  s.version     = Stately::VERSION
+  s.authors     = ['Ryan Twomey']
+  s.email       = ['rtwomey@gmail.com']
+  s.homepage    = 'http://github.com/rtwomey/stately'
+  s.summary     = 'A simple, elegant state machine for Ruby'
+  s.description = 'Add an elegant state machine to your ruby objects with a simple DSL'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
+
+  s.add_development_dependency 'redcarpet', '~> 2.2.2'
+  s.add_development_dependency 'rspec', '~> 2.0'
+  s.add_development_dependency 'yard', '~> 0.8.3'
+  s.add_development_dependency 'rdoc'
+
+  s.required_ruby_version = Gem::Requirement.new('>= 1.8.7')
+  s.require_paths = ['lib']
+end