davidlee-state-fu 0.0.1

data/spec/units/machine_spec.rb

@@ -0,0 +1,237 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+## See state_and_event_common_spec.rb for behaviour shared between
+## StateFu::State and StateFu::Event
+##
+
+describe StateFu::Machine do
+  include MySpecHelper
+
+  before do
+  end
+
+  describe "class methods" do
+    before do
+
+    end
+
+    describe "Machine.for_class" do
+      describe "when there's no matching machine in FuSpace" do
+        before do
+          reset!
+          make_pristine_class 'Klass'
+          mock( StateFu::FuSpace ).class_machines() { { Klass => {} } }
+        end
+
+        it "should create a new machine and bind! it" do
+          @machine = Object.new
+          mock( @machine ).bind!( Klass, :moose, nil )
+          mock( StateFu::Machine ).new( :moose, {} ) { @machine }
+          StateFu::Machine.for_class( Klass, :moose )
+        end
+
+        it "should apply the block (via lathe) if one is given" do
+          @m = StateFu::Machine.for_class( Klass, :snoo ) do
+            state :porpoise
+          end
+          @m.states.map(&:name).should == [:porpoise]
+        end
+      end
+
+      describe "when there's a matching machine in FuSpace" do
+        it "should retrieve the previously created machine" do
+          @machine = Object.new
+          mock( StateFu::FuSpace ).class_machines() { { Klass => { :moose => @machine } } }
+          StateFu::Machine.for_class( Klass, :moose ).should == @machine
+        end
+      end
+
+    end
+  end
+
+  describe "attributes" do
+  end
+
+  describe "instance methods" do
+    before do
+      reset!
+      make_pristine_class 'Klass'
+      @mchn = StateFu::Machine.new( :spec_machine, options={} )
+    end
+
+    describe "helper" do
+      it "should add its arguments to the @@helpers array" do
+        module Foo; FOO = :foo; end
+        module Bar; BAR = :bar; end
+        @mchn.helper Foo, Bar
+        @mchn.helpers.should == [Foo, Bar]
+      end
+
+    end
+
+    describe ".initialize" do
+      it "should require a name" do
+        lambda do
+          StateFu::Machine.new()
+        end.should raise_error( ArgumentError )
+      end
+    end
+
+    describe ".apply!" do
+
+    end
+
+    describe ".bind!" do
+      it "should call StateFu::FuSpace.insert! with itself and its arguments" do
+        field_name = :my_field_name
+        mock( StateFu::FuSpace ).insert!( Klass, @mchn, :newname, field_name ) {}
+        @mchn.bind!( Klass, :newname, field_name )
+      end
+
+      it "should generate a field name if none is given" do
+        klass      = Klass
+        name       = :StinkJuice
+        field_name = 'stink_juice_field'
+        mock( StateFu::FuSpace ).insert!( Klass, @mchn, name, field_name.to_sym ) {}
+        @mchn.bind!( Klass, name )
+      end
+    end
+
+    describe ".initial_state=" do
+
+      it "should set @initial_state given a String, Symbol or State for an existing state" do
+        state = StateFu::State.new( @mchn, :wizzle )
+        @mchn.states << state
+        @mchn.initial_state = state
+        @mchn.initial_state.should == state
+      end
+
+      it "should create the state if it doesnt exist" do
+        @mchn.initial_state = :snoo
+        @mchn.initial_state.should be_kind_of( StateFu::State )
+        @mchn.initial_state.name.should == :snoo
+        @mchn.states.should include( @mchn.initial_state )
+      end
+
+      it "should raise an ArgumentError given a number or an Array" do
+        lambda do @mchn.initial_state = 6
+        end.should raise_error( ArgumentError )
+
+        lambda do @mchn.initial_state = [:ping]
+        end.should raise_error( ArgumentError )
+      end
+
+    end
+
+    describe ".initial_state" do
+      it "should return nil if there are no states and initial_state= has not been called" do
+        @mchn.states.should == []
+        @mchn.initial_state.should == nil
+      end
+
+      it "should return the first state if one exists" do
+        stub( @mchn ).states() {  [:a, :b, :c] }
+        @mchn.initial_state.should == :a
+      end
+
+    end
+
+    describe ".states" do
+      it "should return an array extended with StateFu::StateArray" do
+        @mchn.states.should be_kind_of( Array )
+        @mchn.states.extended_by.should include( StateFu::StateArray )
+      end
+    end
+
+    describe ".state_names" do
+      it "should return a list of symbols of state names" do
+        @mchn.states << StateFu::State.new( @mchn, :a )
+        @mchn.states << StateFu::State.new( @mchn, :b )
+        @mchn.state_names.should == [:a, :b ]
+      end
+    end
+
+    describe ".events" do
+      it "should return an array extended with StateFu::EventArray" do
+        @mchn.events.should be_kind_of( Array )
+        @mchn.events.extended_by.should include( StateFu::EventArray )
+      end
+    end
+
+    describe ".event_names" do
+      it "should return a list of symbols of event names" do
+        @mchn.events << StateFu::Event.new( @mchn, :a )
+        @mchn.events << StateFu::Event.new( @mchn, :b )
+        @mchn.event_names.should == [:a, :b ]
+      end
+    end
+
+    describe ".find_or_create_states_by_name" do
+      describe "given an array of symbols" do
+        it "should return the states named by the symbols if they exist" do
+          a = StateFu::State.new( @mchn, :a )
+          b = StateFu::State.new( @mchn, :b )
+          @mchn.states << a
+          @mchn.states << b
+          @mchn.find_or_create_states_by_name( :a, :b ).should == [a, b]
+          @mchn.find_or_create_states_by_name( [:a, :b] ).should == [a, b]
+        end
+
+        it "should return the states named by the symbols and create them if they don't exist" do
+          @mchn.states.should == []
+          res = @mchn.find_or_create_states_by_name( :a, :b )
+          res.should be_kind_of( Array )
+          res.length.should == 2
+          res.all? { |e| e.class == StateFu::State  }.should be_true
+          res.map(&:name).should == [ :a, :b ]
+          @mchn.find_or_create_states_by_name( :a, :b ).should == res
+        end
+      end # arr symbols
+
+      describe "given an array of states" do
+        it "should return the states if they're in the machine's states array" do
+          a = StateFu::State.new( @mchn, :a )
+          b = StateFu::State.new( @mchn, :b )
+          @mchn.states << a
+          @mchn.states << b
+          @mchn.find_or_create_states_by_name( a, b ).should == [a, b]
+          @mchn.find_or_create_states_by_name( [a, b] ).should == [a, b]
+          @mchn.find_or_create_states_by_name( [[a, b]] ).should == [a, b]
+        end
+
+        it "should add the states to the machine's states array if they're absent" do
+          a = StateFu::State.new( @mchn, :a )
+          b = StateFu::State.new( @mchn, :b )
+          @mchn.find_or_create_states_by_name( a, b ).should == [a, b]
+          @mchn.find_or_create_states_by_name( [a, b] ).should == [a, b]
+          @mchn.find_or_create_states_by_name( [[a, b]] ).should == [a, b]
+        end
+      end # arr states
+    end # find_or_create_states_by_name
+
+    describe "requirement_messages" do
+      it "should be a hash" do
+        @mchn.should respond_to(:requirement_messages)
+        @mchn.requirement_messages.should be_kind_of( Hash )
+      end
+
+      it "should be empty by default" do
+        @mchn.requirement_messages.should be_empty
+      end
+
+    end # requirement_messages
+
+    describe "named_procs" do
+      it "should be a hash" do
+        @mchn.should respond_to(:named_procs)
+        @mchn.named_procs.should be_kind_of( Hash )
+      end
+
+      it "should be empty by default" do
+        @mchn.named_procs.should be_empty
+      end
+
+    end # named_procs
+
+  end # instance methods
+end

data/spec/units/method_factory_spec.rb

@@ -0,0 +1,359 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+describe StateFu::MethodFactory do
+  include MySpecHelper
+
+  # TODO - move to eg method_factory integration spec
+  describe "event_methods" do
+
+    before do
+      make_pristine_class('Klass')
+    end
+
+    describe "defined on the stateful instance / object before state_fu has been called" do
+
+      before do
+          @machine = Klass.machine do
+            event( :simple_event,
+                   :from => { [:a, :b] => :targ } )
+
+          state( :a ) { cycle }
+          end # machine
+          @obj     = Klass.new
+      end
+
+      describe "when there is a method_missing already defined for the class" do
+        it "should still call the pre-defined method_missing"
+      end
+
+      describe "event creation methods" do
+        it "should call method_missing" do
+          mock( @obj ).method_missing( :simple_event! )
+          @obj.simple_event!
+        end
+
+        it "should call state_fu!" do
+          mock.proxy( StateFu::Binding ).new( Klass.machine, @obj, :state_fu )
+          @obj.simple_event!
+          # @obj.should_have_received( :state_fu! )
+        end
+
+        it "should not raise a NoMethodError" do
+          lambda { @obj.simple_event! }.should_not raise_error( NoMethodError )
+        end
+
+        it "should call binding.fire!( :simple_event ... ) with no args" do
+          mock.instance_of( StateFu::Binding ).fire!( is_a(StateFu::Event) )
+          t = @obj.simple_event!
+        end
+
+        it "should call binding.fire!( :simple_event ... ) with any specified args" do
+          mock.instance_of( StateFu::Binding ).fire!( is_a(StateFu::Event), :a, :b, {:c => "d"} )
+          t = @obj.simple_event!( :a, :b, :c => "d" )
+        end
+
+        it "should fire the transition" do
+          @obj.send(:state_fu_field).should == nil
+          t = @obj.simple_event!
+          t.should be_accepted
+          @obj.send(:state_fu_field).should == 'targ'
+        end
+
+        it "should take a block and use it as per usual"
+      end
+    end
+
+
+    describe "defined on the binding" do
+      describe "when the event is simple (has only one possible target)" do
+        before do
+          @machine = Klass.machine do
+            event( :simple_event,
+                   :from => { [:a, :b] => :targ } )
+          end # machine
+          @obj     = Klass.new
+          @binding = @obj.state_fu
+        end # before
+
+        it "should be simple?" do
+          e = @machine.events[:simple_event]
+          e.origins.length.should == 2
+          e.targets.length.should == 1
+          e.should be_simple
+        end
+
+        describe "method which returns an unfired transition" do
+          it "should have the same name as the event" do
+            @binding.should respond_to(:simple_event)
+          end
+
+          it "should return a new transition if called without any arguments" do
+            t = @binding.simple_event()
+            t.should be_kind_of( StateFu::Transition )
+            t.target.should == @machine.states[:targ]
+            t.event.should == @machine.events[:simple_event]
+            t.should_not be_fired
+          end
+
+          it "should add any arguments / options it is called with to the transition" do
+            t = @binding.simple_event(:a, :b, :c, {'d' => 'e'})
+            t.should be_kind_of( StateFu::Transition )
+            t.target.should == @machine.states[:targ]
+            t.event.should == @machine.events[:simple_event]
+            t.args.should == [:a,:b,:c]
+            t.options.should == {:d => 'e'}
+          end
+        end # transition builder
+
+        describe "method which tests if the event is fireable?" do
+          it "should have the name of the event suffixed with ?" do
+            @binding.should respond_to(:simple_event?)
+          end
+
+          it "should be true when the binding says it\'s fireable?" do
+            @binding.fireable?( :simple_event ).should == true
+            @binding.simple_event?.should == true
+          end
+
+          it "should be false when the binding says it\'s not fireable?" do
+            mock( @binding ).fireable?( anything ) { false }
+            @binding.simple_event?.should == false
+          end
+        end # fireable?
+
+        describe "bang (!) method which creates, fires and returns a transition" do
+          it "should have the name of the event suffixed with a bang (!)" do
+            @binding.should respond_to(:simple_event!)
+          end
+
+          it "should return a fired transition" do
+            t = @binding.simple_event!
+            t.should be_kind_of( StateFu::Transition )
+            t.should be_fired
+          end
+
+          it "should pass any arguments to the transition as args / options" do
+            t = @binding.simple_event!( :a, :b, {'c' => :d } )
+            t.should be_kind_of( StateFu::Transition )
+            t.args.should    == [:a, :b ]
+            t.options.should == { :c => :d }
+          end
+        end # bang!
+      end # simple
+
+      describe "when the event is complex (has more than one possible target)" do
+        before do
+          @machine = Klass.machine do
+            state :orphan
+            event( :complex_event,
+                   :from => :home,
+                   :to => [ :x, :y, :z ] )
+            initial_state :home
+          end # machine
+          @obj     = Klass.new
+          @binding = @obj.state_fu
+        end # before
+
+        it "should not be simple?" do
+          e = @machine.events[:complex_event]
+          e.origins.length.should == 1
+          e.targets.length.should == 3
+          e.should_not be_simple
+        end
+
+        describe "method which returns an unfired transition" do
+          it "should have the same name as the event" do
+            @binding.should respond_to(:complex_event)
+          end
+
+          it "should raise an error if called without any arguments" do
+            lambda { @binding.complex_event() }.should raise_error( ArgumentError )
+          end
+
+          it "should raise an ArgumentError if called with a nonexistent target state" do
+            lambda { @binding.complex_event(:nonexistent) }.should raise_error( ArgumentError )
+          end
+
+          it "should raise an InvalidTransition if called with an invalid target state" do
+            lambda { @binding.complex_event(:orphan)      }.should raise_error( StateFu::InvalidTransition )
+          end
+
+          it "should return a transition to the specified state if supplied a valid state" do
+            t = @binding.complex_event( :x )
+            t.should be_kind_of( StateFu::Transition )
+            t.target.name.should == :x
+          end
+
+          it "should add any arguments / options it is called with to the transition" do
+            t = @binding.complex_event(:x,
+                                       :a, :b, :c, {'d' => 'e'})
+            t.should be_kind_of( StateFu::Transition )
+            t.args.should == [:a,:b,:c]
+            t.options.should == {:d => 'e'}
+          end
+        end # transition builder
+
+        describe "method which tests if the event is fireable?" do
+          it "should have the name of the event suffixed with ?" do
+            @binding.should respond_to(:complex_event?)
+          end
+
+          it "should require a valid state name" do
+            lambda { @binding.complex_event?(:nonexistent) }.should raise_error( ArgumentError )
+            lambda { @binding.complex_event?(:orphan) }.should_not  raise_error()
+            @binding.complex_event?(:orphan).should == nil
+            lambda { @binding.complex_event?(:x) }.should_not       raise_error
+          end
+
+          it "should be true when the binding says the event is fireable? " do
+            @binding.fireable?( [:complex_event, :x] ).should == true
+            @binding.complex_event?(:x).should == true
+          end
+
+          it "should be false when the binding says the event is not fireable?" do
+            mock( @binding ).fireable?( anything ) { false }
+            @binding.complex_event?(:x).should == false
+          end
+        end # fireable?
+
+        describe "bang (!) method which creates, fires and returns a transition" do
+          it "should have the name of the event suffixed with a bang (!)" do
+            @binding.should respond_to(:complex_event!)
+          end
+
+          it "should require a valid state name" do
+            lambda { @binding.complex_event!(:nonexistent) }.should raise_error( ArgumentError )
+            lambda { @binding.complex_event!(:orphan) }.should      raise_error( StateFu::InvalidTransition )
+            lambda { @binding.complex_event!(:x) }.should_not       raise_error
+          end
+
+          it "should return a fired transition given a valid state name" do
+            t = @binding.complex_event!( :x )
+            t.should be_kind_of( StateFu::Transition )
+            t.target.should == @machine.states[:x]
+            t.should be_fired
+          end
+
+          it "should pass any arguments to the transition as args / options" do
+            t = @binding.complex_event!( :x,
+                                         :a, :b, {'c' => :d } )
+            t.should be_kind_of( StateFu::Transition )
+            t.target.should  == @machine.states[:x]
+            t.args.should    == [:a, :b ]
+            t.options.should == { :c => :d }
+          end
+        end # bang!
+      end # complex_event
+
+      # TODO move these to binding spec
+      describe "cycle and next_state methods" do
+        describe "when there is a valid transition available for cycle and next_state" do
+          before do
+            @machine = Klass.machine do
+              initial_state :groundhog_day
+
+              state(:groundhog_day) do
+                cycle
+              end
+
+              event(:end_movie, :from => :groundhog_day, :to => :happy_ending)
+            end # machine
+            @obj     = Klass.new
+            @binding = @obj.state_fu
+          end # before
+
+          describe "cycle methods:" do
+            describe "cycle" do
+              it "should return a transition for the cyclical event" do
+                t = @binding.cycle
+                t.should be_kind_of( StateFu::Transition )
+                t.origin.name.should == :groundhog_day
+                t.target.name.should == :groundhog_day
+                t.should_not be_fired
+              end
+            end
+
+            describe "cycle?" do
+            end
+
+            describe "cycle!" do
+            end
+          end # cycle
+
+          describe "next_state methods:" do
+            describe "next_state" do
+            end
+
+            describe "next_state?" do
+            end
+
+            describe "next_state!" do
+            end
+          end # next_state
+        end # with valid transitions
+
+        describe "when the machine is empty" do
+          before do
+            @machine = Klass.machine() {}
+            @obj     = Klass.new
+            @binding = @obj.state_fu
+          end
+
+          describe "current_state" do
+            it "should be nil" do
+              @binding.current_state.should == nil
+            end
+          end
+          describe "cycle methods:" do
+            describe "cycle" do
+              it "should return nil" do
+                @binding.cycle.should == nil
+              end
+            end
+
+            describe "cycle?" do
+              it "should return nil" do
+                @binding.cycle?.should == nil
+              end
+            end
+
+            describe "cycle!" do
+              it "should raise_error( InvalidTransition )" do
+                lambda { @binding.cycle!.should == nil }.should raise_error( StateFu::InvalidTransition )
+              end
+            end
+          end # cycle
+
+          describe "next_state methods:" do
+            describe "next_state" do
+              it "should return nil" do
+                @binding.next_state.should == nil
+              end
+            end
+
+            describe "next_state?" do
+              it "should return nil" do
+                @binding.next_state?.should == nil
+              end
+            end
+
+            describe "next_state!" do
+              it "should raise_error( InvalidTransition )" do
+                lambda { @binding.next_state! }.should raise_error( StateFu::InvalidTransition )
+              end
+            end
+          end # next_state
+
+        end # empty machine
+
+        describe "when there is more than one candidate event / state" do
+        end # too many candidates
+
+      end   # cycle & next_state
+    end     # defined on binding
+
+    describe "methods defined on the object" do
+    end
+
+  end       # event methods
+end

data/spec/units/sprocket_spec.rb

@@ -0,0 +1,71 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+##
+##
+##
+
+describe "Common features / functionality for StateFu::State & StateFu::Event" do
+
+  include MySpecHelper
+  Sprocket = StateFu::Sprocket
+  before do
+    @machine = Object.new
+  end
+
+  describe "calling Sprocket.new" do
+    it "should create a new Sprocket given valid args" do
+      sprocket = Sprocket.new(@machine, :flux, { :meta => :doodle })
+      sprocket.should be_kind_of( Sprocket )
+      sprocket.name.should == :flux
+      sprocket.options[:meta].should == :doodle
+      sprocket.machine.should == @machine
+    end
+  end
+
+  describe "instance methods" do
+    before do
+      @sprocket = Sprocket.new(@machine, :flux, {:meta => "wibble"})
+    end
+
+    describe ".apply!" do
+
+      it "should yield itself if the block's arity is 1" do
+        yielded = false
+        @sprocket.apply!{ |s| yielded = s  }
+        yielded.should == @sprocket
+      end
+
+      it "should instance_eval the block if its arity is 0/-1" do
+        yielded = false
+        @sprocket.apply!{ yielded = self }
+        yielded.should == @sprocket
+      end
+    end
+
+    describe "update!" do
+      it "should merge any options passed into .options" do
+        opts    = @sprocket.options
+        newopts =  { :size => "huge", :colour => "orange" }
+        @sprocket.update!( newopts )
+        @sprocket.options.should == opts.merge(newopts)
+      end
+
+      it "should instance_eval the block if one is passed" do
+        ref = nil
+        @sprocket.update!(){ ref = self }
+        ref.should == @sprocket
+      end
+
+      it "should return itself" do
+        @sprocket.update!.should == @sprocket
+      end
+    end
+
+    describe "to_sym" do
+      it "should return its name" do
+        @sprocket.to_sym.should == @sprocket.name
+      end
+    end
+
+  end
+end