state_machines_rspec 0.3.0

data/lib/state_machines_rspec.rb

@@ -0,0 +1,11 @@
+require 'state_machines_rspec/version'
+require 'state_machines_rspec/state_machines_introspector'
+require 'matchers/events/handle_event'
+require 'matchers/events/reject_event'
+require 'matchers/states/have_state'
+require 'matchers/states/reject_state'
+
+module StateMachinesRspec
+  module Matchers
+  end
+end

data/lib/state_machines_rspec/state_machines_introspector.rb

@@ -0,0 +1,70 @@
+class StateMachinesIntrospector
+  def initialize(subject, state_machine_name=nil)
+    @subject = subject
+    @state_machine_name = state_machine_name
+  end
+
+  def state_machine_attribute
+    state_machine.attribute
+  end
+
+  def current_state_value
+    @subject.send(state_machine_attribute)
+  end
+
+  def state(name)
+    state = state_machine.states.find { |s| s.name == name }
+  end
+
+  def undefined_states(states)
+    states.reject { |s| state_defined? s }
+  end
+
+  def defined_states(states)
+    states.select { |s| state_defined? s }
+  end
+
+  def undefined_events(events)
+    events.reject { |e| event_defined? e }
+  end
+
+  def valid_events(events)
+    events.select { |e| valid_event? e }
+  end
+
+  def invalid_events(events)
+    events.reject { |e| valid_event? e }
+  end
+
+  private
+
+  def state_machine
+    if @state_machine_name
+      unless machine = @subject.class.state_machines[@state_machine_name]
+        raise StateMachinesIntrospectorError,
+          "#{@subject.class} does not have a state machine defined " +
+          "on #{@state_machine_name}"
+      end
+    else
+      machine = @subject.class.state_machine
+    end
+
+    machine
+  end
+
+  def state_defined?(state_name)
+    state(state_name)
+  end
+
+  def event_defined?(event)
+    @subject.respond_to? "can_#{event}?"
+  end
+
+  def valid_event?(event)
+    @subject.send("can_#{event}?")
+  end
+
+end
+
+class StateMachinesIntrospectorError < StandardError
+end

data/lib/state_machines_rspec/version.rb

@@ -0,0 +1,3 @@
+module StateMachinesRspec
+  VERSION = '0.3.0'
+end

data/spec/integration/integration_spec.rb

@@ -0,0 +1,327 @@
+require 'spec_helper'
+require 'integration/models/vehicle'
+
+describe Vehicle do
+  let(:vehicle) { Vehicle.new }
+  subject { vehicle }
+
+  its(:passed_inspection?) { is_expected.to be_falsey }
+
+  shared_examples 'crashable' do
+    describe 'crash' do
+      context 'having passed inspection' do
+        before { allow(vehicle).to receive_messages(:passed_inspection => true) }
+        pending 'keeps running' do
+          initial_state = vehicle.state
+          vehicle.crash!
+
+          expect(vehicle.state).to  eq initial_state
+        end
+      end
+
+      context 'not having passed inspection' do
+        before { allow(vehicle).to receive_messages(:passed_inspection => false) }
+        it 'stalls' do
+          vehicle.crash!
+          expect(vehicle.state).to  eq :stalled.to_s
+        end
+      end
+    end
+  end
+
+  shared_examples 'speedless' do
+    it 'does not respond to speed' do
+      expect { vehicle.speed }.to raise_error StateMachines::InvalidContext
+    end
+  end
+
+  describe '#initialize' do
+    its(:seatbelt_on) { is_expected.to be_falsey }
+    its(:time_used) { is_expected.to eq 0 }
+    its(:auto_shop_busy) { is_expected.to be_truthy }
+  end
+
+  describe '#put_on_seatbelt' do
+    it 'sets seatbelt_on to true' do
+      vehicle.seatbelt_on = false
+      vehicle.put_on_seatbelt
+
+      expect(vehicle.seatbelt_on).to  be_truthy
+    end
+  end
+
+  describe 'state machines' do
+    it { is_expected.to have_states :parked, :idling, :stalled, :first_gear,
+                            :second_gear, :third_gear }
+    it { is_expected.to reject_state :flying }
+
+    it { is_expected.to handle_event :ignite, when: :parked }
+    it { is_expected.to reject_events :park, :idle, :shift_up,
+                              :shift_down, :crash, :repair,
+                              when: :parked }
+
+    it { is_expected.to handle_events :park, :shift_up, :crash, when: :idling }
+    it { is_expected.to reject_events :ignite, :idle, :shift_down, :repair,
+                              when: :idling }
+
+    it { is_expected.to handle_events :ignite, :repair, when: :stalled }
+    it { is_expected.to reject_events :park, :idle, :shift_up, :shift_down, :crash,
+                              when: :stalled }
+
+    it { is_expected.to handle_events :park, :idle, :shift_up, :crash,
+                              when: :first_gear }
+    it { is_expected.to reject_events :ignite, :shift_down, :repair,
+                              when: :first_gear }
+
+    it { is_expected.to handle_events :shift_up, :shift_down, :crash,
+                              when: :second_gear }
+    it { is_expected.to reject_events :park, :ignite, :idle, :repair,
+                              when: :second_gear }
+
+    it { is_expected.to handle_events :shift_down, :crash, when: :third_gear }
+    it { is_expected.to reject_events :park, :ignite, :idle, :shift_up, :repair,
+                              when: :third_gear }
+
+    it 'has an initial state of "parked"' do
+      expect(vehicle).to  be_parked
+    end
+
+    it 'has an initial alarm state of "active"' do
+      expect(vehicle.alarm_active?).to be_truthy
+    end
+
+    describe 'around transitions' do
+      it 'updates the time used' do
+        expect(vehicle).to receive(:time_used=).with(0)
+        Timecop.freeze { vehicle.ignite! }
+      end
+    end
+
+    context 'when parked' do
+      before { vehicle.state = :parked.to_s }
+
+      its(:speed) { is_expected.to be_zero }
+      it { is_expected.not_to be_moving }
+
+      describe 'before transitions' do
+        it 'puts on a seatbelt' do
+          expect(vehicle).to receive :put_on_seatbelt
+          vehicle.ignite!
+        end
+      end
+
+      describe 'ignite' do
+        it 'should transition to idling' do
+          vehicle.ignite!
+          expect(vehicle).to  be_idling
+        end
+      end
+    end
+
+    context 'when transitioning to parked' do
+      before { vehicle.state = :idling.to_s }
+      it 'removes seatbelts' do
+        expect(vehicle).to receive(:seatbelt_on=).with(false)
+        vehicle.park!
+      end
+    end
+
+    context 'when idling' do
+      before { vehicle.state = :idling.to_s }
+
+      its(:speed) { is_expected.to eq 10 }
+      it { is_expected.not_to be_moving }
+
+      describe 'park' do
+        it 'should transition to a parked state' do
+          vehicle.park!
+          expect(vehicle).to  be_parked
+        end
+      end
+
+      describe 'shift up' do
+        it 'should shift into first gear' do
+          vehicle.shift_up!
+          expect(vehicle).to  be_first_gear
+        end
+      end
+
+      it_behaves_like 'crashable'
+    end
+
+    context 'when stalled' do
+      before { vehicle.state = :stalled.to_s }
+
+      it { is_expected.not_to be_moving }
+      it_behaves_like 'speedless'
+
+      describe 'ignite' do
+        it 'remains stalled' do
+          vehicle.ignite!
+          expect(vehicle).to  be_stalled
+        end
+      end
+
+      describe 'repair' do
+        context 'the auto shop is busy' do
+          before { allow(vehicle).to receive_messages(:auto_shop_busy => true) }
+          it 'remains stalled' do
+            vehicle.repair!
+            expect(vehicle).to  be_stalled
+          end
+        end
+
+        context 'the auto shop is not busy' do
+          before { allow(vehicle).to receive_messages(:auto_shop_busy => false) }
+          it 'is parked' do
+            vehicle.repair!
+            expect(vehicle).to  be_parked
+          end
+        end
+      end
+    end
+
+    context 'when in first gear' do
+      before { vehicle.state = :first_gear.to_s }
+
+      its(:speed) { is_expected.to eq 10 }
+      it { is_expected.to be_moving }
+
+      describe 'park' do
+        it 'parks' do
+          vehicle.park!
+          expect(vehicle).to  be_parked
+        end
+      end
+
+      describe 'idle' do
+        it 'idles' do
+          vehicle.idle!
+          expect(vehicle).to  be_idling
+        end
+      end
+
+      describe 'shift up' do
+        it 'shift into second gear' do
+          vehicle.shift_up!
+          expect(vehicle).to  be_second_gear
+        end
+      end
+
+      it_behaves_like 'crashable'
+    end
+
+    context 'when in second gear' do
+      before { vehicle.state = :second_gear.to_s }
+
+      it { is_expected.to be_moving }
+      it_behaves_like 'speedless'
+
+      describe 'shift up' do
+        it 'shifts into third gear' do
+          vehicle.shift_up!
+          expect(vehicle).to  be_third_gear
+        end
+      end
+
+      describe 'shift down' do
+        it 'shifts back into first gear' do
+          vehicle.shift_down!
+          expect(vehicle).to  be_first_gear
+        end
+      end
+
+      it_behaves_like 'crashable'
+    end
+
+    context 'when in third gear' do
+      before { vehicle.state = :third_gear.to_s }
+
+      it { is_expected.to be_moving }
+      it_behaves_like 'speedless'
+
+      describe 'shift down' do
+        it 'shifts back into second gear' do
+          vehicle.shift_down!
+          expect(vehicle).to  be_second_gear
+        end
+      end
+
+      it_behaves_like 'crashable'
+    end
+
+    context 'on ignition' do
+      context 'when it fails' do
+        before { allow(vehicle).to receive_messages(:ignite => false) }
+        pending 'logs the failure' do
+          expect(vehicle).to receive(:log_start_failure)
+          vehicle.ignite
+        end
+      end
+    end
+
+    context 'on a crash' do
+      before { vehicle.state = :third_gear.to_s }
+      it 'gets towed' do
+        expect(vehicle).to receive(:tow)
+        vehicle.crash!
+      end
+    end
+
+    context 'upon being repaired' do
+      before { vehicle.state = :stalled.to_s }
+      it 'gets fixed' do
+        expect(vehicle).to receive(:fix)
+        vehicle.repair!
+      end
+    end
+  end
+
+  describe 'alarm state machines' do
+    it { is_expected.to have_state :active, on: :alarm_state, value: 1 }
+    it { is_expected.to have_state :off, on: :alarm_state, value: 0 }
+    it { is_expected.to reject_states :broken, :ringing, on: :alarm_state }
+
+    it { is_expected.to handle_events :enable_alarm, :disable_alarm,
+                              when: :active, on: :alarm_state }
+    it { is_expected.to handle_events :enable_alarm, :disable_alarm,
+                              when: :off, on: :alarm_state }
+
+    it 'has an initial state of activated' do
+      expect(vehicle.alarm_active?).to be_truthy
+    end
+
+    context 'when active' do
+      describe 'enable' do
+        it 'becomes active' do
+          vehicle.enable_alarm!
+          expect(vehicle.alarm_active?).to be_truthy
+        end
+      end
+
+      describe 'disable' do
+        it 'turns the alarm off' do
+          vehicle.disable_alarm!
+          expect(vehicle.alarm_off?).to be_truthy
+        end
+      end
+    end
+
+    context 'when off' do
+      before { vehicle.alarm_state = 0 }
+      describe 'enable' do
+        it 'becomes active' do
+          vehicle.enable_alarm!
+          expect(vehicle.alarm_active?).to be_truthy
+        end
+      end
+
+      describe 'disable' do
+        it 'turns the alarm off' do
+          vehicle.disable_alarm!
+          expect(vehicle.alarm_off?).to be_truthy
+        end
+      end
+    end
+  end
+end

data/spec/integration/models/vehicle.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+
+class Vehicle
+  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
+
+  state_machine :state, :initial => :parked do
+    before_transition :parked => any - :parked, :do => :put_on_seatbelt
+
+    after_transition :on => :crash, :do => :tow
+    after_transition :on => :repair, :do => :fix
+    after_transition any => :parked do |vehicle, transition|
+      vehicle.seatbelt_on = false
+    end
+
+    after_failure :on => :ignite, :do => :log_start_failure
+
+    around_transition do |vehicle, transition, block|
+      start = Time.now
+      block.call
+      vehicle.time_used += Time.now - start
+    end
+
+    event :park do
+      transition [:idling, :first_gear] => :parked
+    end
+
+    event :ignite do
+      transition :stalled => same, :parked => :idling
+    end
+
+    event :idle do
+      transition :first_gear => :idling
+    end
+
+    event :shift_up do
+      transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
+    end
+
+    event :shift_down do
+      transition :third_gear => :second_gear, :second_gear => :first_gear
+    end
+
+    event :crash do
+      transition all - [:parked, :stalled] => :stalled, :if => lambda {|vehicle| !vehicle.passed_inspection?}
+    end
+
+    event :repair do
+      # The first transition that matches the state and passes its conditions
+      # will be used
+      transition :stalled => :parked, :unless => :auto_shop_busy
+      transition :stalled => same
+    end
+
+    state :parked do
+      def speed
+        0
+      end
+    end
+
+    state :idling, :first_gear do
+      def speed
+        10
+      end
+    end
+
+    state all - [:parked, :stalled, :idling] do
+      def moving?
+        true
+      end
+    end
+
+    state :parked, :stalled, :idling do
+      def moving?
+        false
+      end
+    end
+  end
+
+  state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
+    event :enable do
+      transition all => :active
+    end
+
+    event :disable do
+      transition all => :off
+    end
+
+    state :active, :value => 1
+    state :off, :value => 0
+  end
+
+  def initialize
+    @seatbelt_on = false
+    @time_used = 0
+    @auto_shop_busy = true
+    super() # NOTE: This *must* be called, otherwise states won't get initialized
+  end
+
+  def put_on_seatbelt
+    @seatbelt_on = true
+  end
+
+  def passed_inspection?
+    false
+  end
+
+  def tow
+    # tow the vehicle
+  end
+
+  def fix
+    # get the vehicle fixed by a mechanic
+  end
+
+  def log_start_failure
+    # log a failed attempt to start the vehicle
+  end
+end
+