evented-spec 0.4.0 → 0.4.1

data/lib/evented-spec/ext/coolio.rb

@@ -0,0 +1,14 @@
+# Monkey patching some methods into Cool.io to make it more testable
+module Coolio
+  class Loop
+    # Cool.io provides no means to change the default loop which makes sense in
+    # most situations, but not ours.
+    def self.default_loop=(event_loop)
+      if RUBY_VERSION >= "1.9.0"
+        Thread.current.instance_variable_set :@_coolio_loop, event_loop
+      else
+        @@_coolio_loop = event_loop
+      end
+    end
+  end
+end

data/lib/evented-spec/spec_helper.rb

@@ -0,0 +1,141 @@
+# You can include one of the following modules into your example groups:
+# EventedSpec::SpecHelper,
+# EventedSpec::AMQPSpec,
+# EventedSpec::EMSpec.
+#
+# EventedSpec::SpecHelper module defines #ampq and #em methods that can be safely used inside
+# your specs (examples) to test code running inside AMQP.start or EM.run loop
+# respectively. Each example is running in a separate event loop,you can control
+# for timeouts either with :spec_timeout option given to #amqp/#em method or setting
+# a default timeout using default_timeout(timeout) macro inside describe/context block.
+#
+# If you include EventedSpec::Spec module into your example group, each example of this group
+# will run inside AMQP.start loop without the need to explicitly call 'amqp'. In order to
+# provide options to AMQP loop, default_options({opts}) macro is defined.
+#
+# Including EventedSpec::EMSpec module into your example group, each example of this group will
+# run inside EM.run loop without the need to explicitly call 'em'.
+#
+# In order to stop AMQP/EM loop, you should call 'done' AFTER you are sure that your
+# example is finished and your expectations executed. For example if you are using
+# subscribe block that tests expectations on messages, 'done' should be probably called
+# at the end of this block.
+#
+module EventedSpec
+
+  # EventedSpec::SpecHelper module defines #ampq and #em methods that can be safely used inside
+  # your specs (examples) to test code running inside AMQP.start or EM.run loop
+  # respectively. Each example is running in a separate event loop, you can control
+  # for timeouts either with :spec_timeout option given to #amqp/#em/#coolio method or setting
+  # a default timeout using default_timeout(timeout) macro inside describe/context block.
+  module SpecHelper
+    # Error which shows in RSpec log when example does not call #done inside
+    # of event loop.
+    SpecTimeoutExceededError = Class.new(RuntimeError)
+
+    # Class methods (macros) for any example groups that includes SpecHelper.
+    # You can use these methods as macros inside describe/context block.
+    module GroupMethods
+      # Returns evented-spec related metadata for particular example group.
+      # Metadata is cloned from parent to children, so that children inherit
+      # all the options and hooks set in parent example groups
+      #
+      # @return [Hash] hash with example group metadata
+      def evented_spec_metadata
+        if @evented_spec_metadata
+          @evented_spec_metadata
+        else
+          @evented_spec_metadata = superclass.evented_spec_metadata rescue {}
+          @evented_spec_metadata = EventedSpec::Util.deep_clone(@evented_spec_metadata)
+        end
+      end # evented_spec_metadata
+
+      # Sets/retrieves default timeout for running evented specs for this
+      # example group and its nested groups.
+      #
+      # @param [Float] desired timeout for the example group
+      # @return [Float]
+      def default_timeout(spec_timeout = nil)
+        if spec_timeout
+          default_options[:spec_timeout] = spec_timeout
+        else
+          default_options[:spec_timeout] || self.superclass.default_timeout
+        end
+      end
+
+      # Sets/retrieves default AMQP.start options for this example group
+      # and its nested groups.
+      #
+      # @param [Hash] context-specific options for helper methods like #amqp, #em, #coolio
+      # @return [Hash]
+      def default_options(opts = nil)
+        evented_spec_metadata[:default_options] ||= {}
+        if opts
+          evented_spec_metadata[:default_options].merge!(opts)
+        else
+          evented_spec_metadata[:default_options]
+        end
+      end
+
+      # Collection of evented hooks for current example group
+      #
+      # @return [Hash] hash with hooks
+      def evented_spec_hooks
+        evented_spec_metadata[:es_hooks] ||= Hash.new
+      end
+
+      # Collection of evented hooks of predefined type for current example group
+      #
+      # @param [Symbol] hook type
+      # @return [Array] hooks
+      def evented_spec_hooks_for(type)
+        evented_spec_hooks[type] ||= []
+      end # evented_spec_hooks_for
+    end
+
+    def self.included(example_group)
+      unless example_group.respond_to? :default_timeout
+        example_group.extend GroupMethods
+      end
+    end
+
+    # Retrieves default options passed in from enclosing example groups
+    #
+    # @return [Hash] default option for currently running example
+    def default_options
+      @default_options ||= self.class.default_options.dup rescue {}
+    end
+
+    # Executes an operation after certain delay
+    #
+    # @param [Float] time to wait before operation
+    def delayed(time, &block)
+      @evented_example.delayed(time) do
+        @example_group_instance.instance_eval(&block)
+      end
+    end # delayed
+
+    # Breaks the event loop and finishes the spec. This should be called after
+    # you are reasonably sure that your expectations succeeded.
+    # Done yields to any given block first, then stops EM event loop.
+    # For amqp specs, stops AMQP and cleans up AMQP state.
+    #
+    # You may pass delay (in seconds) to done. If you do so, please keep in mind
+    # that your (default or explicit) spec timeout may fire before your delayed done
+    # callback is due, leading to SpecTimeoutExceededError
+    #
+    # @param [Float] Delay before event loop is stopped
+    def done(*args, &block)
+      @evented_example.done *args, &block if @evented_example
+    end
+
+    # Manually sets timeout for currently running example. If spec doesn't call
+    # #done before timeout, it is marked as failed on timeout.
+    #
+    # @param [Float] Delay before event loop is stopped with error
+    def timeout(*args)
+      @evented_example.timeout *args if @evented_example
+    end
+
+  end # module SpecHelper
+end # EventedSpec

data/lib/evented-spec/spec_helper/amqp_helpers.rb

@@ -0,0 +1,55 @@
+module EventedSpec
+  module SpecHelper
+    module AMQPHelpers # naming is v
+      module GroupMethods
+        # Adds before hook that will run inside AMQP connection (AMQP.start loop)
+        # before example starts
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def amqp_before(scope = :each, &block)
+          raise ArgumentError, "amqp_before only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:amqp_before) << block
+        end
+
+        # Adds after hook that will run inside AMQP connection (AMQP.start loop)
+        # after example finishes
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def amqp_after(scope = :each, &block)
+          raise ArgumentError, "amqp_after only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:amqp_after).unshift block
+        end
+      end # module GroupMethods
+
+      module ExampleMethods
+        # Yields to a given block inside EM.run and AMQP.start loops.
+        #
+        # @param [Hash] options for amqp connection initialization
+        # @option opts [String] :user ('guest') Username as defined by the AMQP server.
+        # @option opts [String] :pass ('guest') Password as defined by the AMQP server.
+        # @option opts [String] :vhost ('/') Virtual host as defined by the AMQP server.
+        # @option opts [Numeric] :timeout (nil) *Connection* timeout, measured in seconds.
+        # @option opts [Boolean] :logging (false) Toggle the extremely verbose AMQP logging.
+        # @option opts [Numeric] :spec_timeout (nil) Amount of time before spec is stopped by timeout
+        # @yield block to execute after amqp connects
+        def amqp(opts = {}, &block)
+          opts = default_options.merge opts
+          @evented_example = AMQPExample.new(opts, self, &block)
+          @evented_example.run
+        end
+      end # module ExampleMethods
+    end # module AMQP
+  end # module SpecHelper
+end # module EventedSpec
+
+module EventedSpec
+  module SpecHelper
+    module GroupMethods
+      include EventedSpec::SpecHelper::AMQPHelpers::GroupMethods
+    end # module GroupMethods
+
+    include EventedSpec::SpecHelper::AMQPHelpers::ExampleMethods
+  end # module SpecHelper
+end # module EventedSpec

data/lib/evented-spec/spec_helper/coolio_helpers.rb

@@ -0,0 +1,49 @@
+module EventedSpec
+  module SpecHelper
+    module CoolioHelpers
+      module GroupHelpers
+        # Adds before hook that will run inside coolio event loop before example starts.
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def coolio_before(scope = :each, &block)
+          raise ArgumentError, "coolio_before only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:coolio_before) << block
+        end
+
+        # Adds after hook that will run inside coolio event loop after example finishes.
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def coolio_after(scope = :each, &block)
+          raise ArgumentError, "coolio_after only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:coolio_after).unshift block
+        end
+      end # module GroupHelpers
+
+      module ExampleHelpers
+        # Yields to block inside cool.io loop, :spec_timeout option (in seconds) is used to
+        # force spec to timeout if something goes wrong and EM/AMQP loop hangs for some
+        # reason.
+        #
+        # @param [Hash] options for cool.io
+        # @param opts [Numeric] :spec_timeout (nil) Amount of time before spec is stopped by timeout
+        # @yield block to execute after cool.io loop starts
+        def coolio(opts = {}, &block)
+          opts = default_options.merge opts
+          @evented_example = CoolioExample.new(opts, self, &block)
+          @evented_example.run
+        end
+      end # module ExampleHelpers
+    end # module CoolioHelpers
+  end # module SpecHelper
+end # module EventedSpec
+
+module EventedSpec
+  module SpecHelper
+    module GroupMethods
+      include EventedSpec::SpecHelper::CoolioHelpers::GroupHelpers
+    end # module GroupHelpers
+    include EventedSpec::SpecHelper::CoolioHelpers::ExampleHelpers
+  end # module SpecHelper
+end # module EventedSpec

data/lib/evented-spec/spec_helper/event_machine_helpers.rb

@@ -0,0 +1,52 @@
+module EventedSpec
+  module SpecHelper
+    module EventMachineHelpers
+      module GroupMethods
+        # Adds before hook that will run inside EM event loop before example starts.
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def em_before(scope = :each, &block)
+          raise ArgumentError, "em_before only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:em_before) << block
+        end
+
+        # Adds after hook that will run inside EM event loop after example finishes.
+        #
+        # @param [Symbol] scope for hook (only :each is supported currently)
+        # @yield hook block
+        def em_after(scope = :each, &block)
+          raise ArgumentError, "em_after only supports :each scope" unless :each == scope
+          evented_spec_hooks_for(:em_after).unshift block
+        end
+      end # module GroupMethods
+
+      module ExampleMethods
+        # Yields to block inside EM loop, :spec_timeout option (in seconds) is used to
+        # force spec to timeout if something goes wrong and EM/AMQP loop hangs for some
+        # reason.
+        #
+        # For compatibility with EM-Spec API, em method accepts either options Hash
+        # or numeric timeout in seconds.
+        #
+        # @param [Hash] options for eventmachine
+        # @param opts [Numeric] :spec_timeout (nil) Amount of time before spec is stopped by timeout
+        # @yield block to execute after eventmachine loop starts
+        def em(opts = {}, &block)
+          opts = default_options.merge(opts.is_a?(Hash) ? opts : { :spec_timeout =>  opts })
+          @evented_example = EMExample.new(opts, self, &block)
+          @evented_example.run
+        end
+      end # module ExampleMethods
+    end # module EventMachine
+  end # module SpecHelper
+end # module EventedSpec
+
+module EventedSpec
+  module SpecHelper
+    module GroupMethods
+      include EventedSpec::SpecHelper::EventMachineHelpers::GroupMethods
+    end # module GroupMethods
+    include EventedSpec::SpecHelper::EventMachineHelpers::ExampleMethods
+  end # module SpecHelper
+end # module EventedSpec

data/spec/em_hooks_spec.rb

@@ -43,7 +43,7 @@ shared_examples_for 'hooked em specs' do
     # Expectation is set in after{} hook
     em do
       expect { :this.should == :fail
-      }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+      }.to raise_error RSpec::Expectations::ExpectationNotMetError
       done
     end
   end
@@ -74,7 +74,7 @@ shared_examples_for 'hooked amqp specs' do
     # Expectation is set in after{} hook
     amqp do
       expect { :this.should == :fail
-      }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+      }.to raise_error RSpec::Expectations::ExpectationNotMetError
       done
     end
   end
@@ -108,7 +108,7 @@ describe EventedSpec::SpecHelper, ".em_before/.em_after" do
 
       it 'should execute em_after if RSpec expectation fails' do
         expect { :this.should == :fail
-        }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+        }.to raise_error RSpec::Expectations::ExpectationNotMetError
       end
     end # context 'for non-evented specs'
 

data/spec/evented-spec/adapters/adapter_seg.rb

@@ -0,0 +1,156 @@
+# Our assumptions with this seg:
+#   - let(:prefix) is defined (e.g. 'coolio_')
+#   - let(:method_name) is defined (e.g. 'coolio')
+#   - #{prefix}running? method is defined in example group, it is true inside
+#     #{method_name} call block, and false outside of it
+#
+shared_examples_for "EventedSpec adapter" do
+  # Unfortunately, I know no other way to extract variables from let(...)
+  prefix      = self.new.prefix
+  method_name = self.new.method_name
+
+  def loop_running?
+    send("#{prefix}running?")
+  end
+
+  def loop(*args)
+    send(method_name, *args) do
+      yield
+    end
+  end
+
+  before(:each) { loop_running?.should be_false }
+  after(:each) { loop_running?.should be_false }
+
+  describe "sanity check:" do
+    it "we should not be in #{method_name} loop unless explicitly asked" do
+      loop_running?.should be_false
+    end
+  end
+
+  describe "#{method_name}" do
+    it "should execute given block in the right scope" do
+      @variable = 1
+      loop do
+        @variable.should == 1
+        @variable = true
+        done
+      end
+      @variable.should == true
+    end
+
+    it "should start default event loop and give control" do
+      loop do
+        loop_running?.should be_true
+        done
+      end
+    end
+
+    it "should stop the event loop afterwards" do
+      loop do
+        done
+      end
+      loop_running?.should be_false
+    end
+
+    it "should raise SpecTimeoutExceededError when #done is not issued" do
+      expect {
+        loop do
+        end
+      }.to raise_error(EventedSpec::SpecHelper::SpecTimeoutExceededError)
+    end
+
+    it "should propagate mismatched rspec expectations" do
+      expect {
+        loop do
+          :fail.should == :win
+        end
+      }.to raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+
+
+  describe "#done" do
+    it "should execute given block" do
+      loop do
+        done(0.05) do
+          @variable = true
+        end
+      end
+      @variable.should be_true
+    end
+
+    it "should cancel timeout" do
+      expect {
+        loop do
+          done(0.2)
+        end
+      }.to_not raise_error
+    end
+  end
+
+  describe "hooks" do
+    context "before" do
+      send("#{prefix}before") do
+        @called_back = true
+        loop_running?.should be_true
+      end
+
+      it "should run before example starts" do
+        loop do
+          @called_back.should be_true
+          done
+        end
+      end
+    end
+
+    context "after" do
+      send("#{prefix}after") do
+        @called_back = true
+        loop_running?.should be_true
+      end
+
+      it "should run after example finishes" do
+        loop do
+          @called_back.should be_false
+          done
+        end
+        @called_back.should be_true
+      end
+    end
+  end
+
+  describe "#delayed" do
+    it "should run an operation after certain amount of time" do
+      loop(:spec_timeout => 3) do
+        time = Time.now
+        delayed(0.5) do
+          (Time.now - time).should be_within(0.3).of(0.5)
+          done
+        end
+      end
+    end
+
+    it "should preserve context" do
+      loop(:spec_timeout => 3) do
+        @instance_var = true
+        delayed(0.1) do
+          @instance_var.should be_true
+          done
+        end
+      end
+    end
+  end
+
+
+  describe "error handling" do
+    it "bubbles failing expectations up to Rspec" do
+      expect {
+        loop do
+          :this.should == :fail
+        end
+      }.to raise_error(RSpec::Expectations::ExpectationNotMetError)
+      loop_running?.should be_false
+    end
+  end
+end