amqp-spec 0.2.7 → 0.3.0

data/HISTORY

@@ -10,10 +10,6 @@
 
 * Minimal functionality implemented
 
-== 0.0.3 / 2010-10-13
-
-* Bunch of non-working specs added
-
 == 0.0.4 / 2010-10-14
 
 * Problems with default_options resolved
@@ -30,22 +26,10 @@
 
 * Make sure Thread.current[:mq] state is cleaned after each example
 
-== 0.1.4 / 2010-10-15
-
-* Problematic tests all fixed
-
 == 0.1.7 / 2010-10-15
 
 * em interface improved for timeout arg
 
-== 0.1.8 / 2010-10-15
-
-* Add AMQP as a dependency
-
-== 0.1.9 / 2010-10-15
-
-* SpecHelper class methods refactored
-
 == 0.1.11 / 2010-10-18
 
 * Optional delay added to done
@@ -54,30 +38,22 @@
 
 * Rspec 2 support added
 
-== 0.2.1 / 2010-10-28
-
-* RSpec2-specific examples added
-
 == 0.2.2 / 2010-10-31
 
 * Metadata in Rspec 1
 
-== 0.2.3 / 2010-10-31
-
-* Documentation cleaned up
-
-== 0.2.4 / 2010-11-01
+== 0.2.7 / 2010-11-04
 
-* Release
+* Make AMQP.cleanup_state more thorough
 
-== 0.2.5 / 2010-11-04
+== 0.2.8 / 2010-11-15
 
-* Minor Gemfile update
+* syncronize method added for wrapping async calls
 
-== 0.2.6 / 2010-11-04
+== 0.2.9 / 2010-11-16
 
-* Fixed subtly failing specs
+* Fallback to a separate default timeout
 
-== 0.2.7 / 2010-11-04
+== 0.3.0 / 2010-11-16
 
-* Make AMQP.cleanup_state more thorough
+* Hooks em_before/em_after implemented

data/README.rdoc

@@ -8,52 +8,56 @@ Simple API for writing asynchronous EventMachine/AMQP specs. Supports RSpec and
 
 == Description
 
-EventMachine-based code, including synchronous {AMQP library}[http://github.com/tmm1/amqp] is
-notoriously difficult to test. To the point that many people recommend using either
-Mocks[http://github.com/danielsdeleo/moqueue] or {synchronous libraries}[http://github.com/celldee/bunny]
-instead of EM-based libraries in unit tests. This is not always an option, however - sometimes your code
-is supposed to run inside event loop, and you want to test a real thing, not mocks.
-
-EM-Spec[http://github.com/tmm1/em-spec] gem made it easier to write evented specs, but it has several drawbacks.
-First, it is not easy to manage both EM.run and AMQP.start loops at the same time. Second, AMQP is not
-properly stopped and deactivated upon exceptions and timeouts, resulting in AMQP library state leak
-between examples and multiple mystereous failures.
-
-AMQP-Spec is built upon EM-Spec code but makes it easier to test AMQP event loops specifically. API is
-very similar to EM-Spec, only a bit extended. The final goal is to make writing AMQP specs reasonably
-pleasant experience and dispel the notion that evented AMQP-based libs are impossible to unit-test.
-
-Mind you, you still have to properly manage your AMQP broker in order to prevent broker state from leaking
-between examples. You can try to combine AMQP-Spec and Moqueue[http://github.com/danielsdeleo/moqueue]
-if you want to abstract away actual broker interactions, but still specify some event-based expectations.
+EventMachine-based code, including synchronous {AMQP library}[http://github.com/tmm1/amqp]
+is notoriously difficult to test. To the point that many people recommend using either
+Mocks[http://github.com/danielsdeleo/moqueue] or {synchronous}[http://github.com/celldee/bunny]
+libraries instead of EM-based libraries in unit tests. This is not always an option, however -
+sometimes your code just has to run inside the event loop, and you want to test a real thing,
+not mocks.
+
+EM-Spec[http://github.com/tmm1/em-spec] gem made it easier to write evented specs, but it
+has several drawbacks. First, it is not easy to manage both EM.run and AMQP.start loops
+at the same time. Second, AMQP is not properly stopped and deactivated upon exceptions and
+timeouts, resulting in state leak between examples and multiple mystereous failures.
+
+AMQP-Spec is based on EM-Spec code but makes it easier to test AMQP event loops specifically.
+API is very similar to EM-Spec's, only a bit extended. The final goal is to make writing AMQP
+specs reasonably pleasant experience and dispel the notion that evented AMQP-based libs are
+impossible to unit-test.
+
+Mind you, you still have to properly manage your AMQP broker in order to prevent broker
+state from leaking between examples. You can try to combine AMQP-Spec and
+Moqueue[http://github.com/danielsdeleo/moqueue] if you want to abstract away actual broker
+interactions, but still specify some event-based expectations.
 
 ==Rspec
 
-There are several ways to use amqp-spec. To use it as a helper, include AMQP::SpecHelper in your describe block.
-You then use either 'amqp' or 'em' methods to wrap your evented test code. Inside the amqp/em block, you must call
-#done after your expectations. Everything works normally otherwise. You can use default_timeout and default_options
-macros to avoid manually setting AMQP options in each example. However, if you DO manually set options inside
-the example, they override the defaults.
+There are several ways to use amqp-spec. To use it as a helper, include AMQP::SpecHelper
+in your describe block. You then use either 'amqp' or 'em' methods to wrap your evented
+test code. Inside the amqp/em block, you must call #done after your expectations. Everything
+works normally otherwise. You can set default_timeout and default_options to avoid manually
+setting AMQP options for each example. However, if you DO supply options to #amqp method
+inside the example, they override the defaults.
 
-Default options and default timeout are local for each example group and inherited by its nested groups,
-different example groups can have separate defaults. Please note that this is different from em-spec where
-default_timeout is effectively a global setting.
+Default options and default timeout are local for each example group and inherited by
+its nested groups, unconnected example groups DO NOT share defaults. Please note that
+this is different from EM-Spec where default_timeout is effectively a global setting.
+
+In order to setup/teardown EM state before/after your examples, you'll need to use
+*em_before{}* and *em_after{}* hooks. These hooks are similar to standard RSpec's
+*before/after* hooks but run inside the EM event loop before/after your example block.
 
   require "amqp-spec/rspec"
 
   describe AMQP do
     include AMQP::SpecHelper
   
-    default_options :host => 'my.amqp.broker.org', :port => '21118'
+    default_options = {:host => 'my.amqp.broker.org', :port => '21118'}
     # Can be used to set default options for your amqp{} event loops
 
-    default_timeout 1
+    default_timeout = 1
     # Can be used to set default :spec_timeout for your evented specs
 
-    before(:each) do
-      puts EM.reactor_running?
-    end
-
     it "works normally when not using #amqp or #em" do
       1.should == 1
     end
@@ -78,25 +82,31 @@ default_timeout is effectively a global setting.
 
     it "optionally raises timeout exception if your loop hangs for some reason" do
       proc {
-        amqp(:spec_timeout => 3){}
+        amqp(:spec_timeout => 0.5){}
       }.should raise_error SpecTimeoutExceededError
     end
 
   end
 
-Another option is to include AMQP::Spec in your describe block. This will patch Rspec so that all of your
-examples run inside an amqp block automatically. A word of caution about before{} and after{} hooks in your example
-groups including AMQP::Spec. Each of these hooks will run in its separate EM loop that you'll need to shut down
-either manually (done) or via default_timeout. Essentially, this means that any EM-related state that you'd like
-to setup/teardown using these hooks will be lost as each example will run in a separate EM loop. In order to
-run setup/teardown hooks inside the EM loop, you'll need to use before_amqp{} and after_amqp{} hooks that run
-inside the EM loop but before/after AMQP loop (these hooks are currently not implemented)
+Another option is to include AMQP::Spec in your describe block. This will patch Rspec so
+that all of your examples run inside an amqp block automatically. A word of caution about
+*before{}*/*after{}* hooks in your example groups including AMQP::Spec. Each of these hooks
+will run in its separate EM loop that you'll need to shut down either manually (done) or
+via timeout. Essentially, this means that any EM-related state that you'd like to set up or
+tear down using these hooks will be lost as example itself will run in a different EM loop.
+
+In short, you should avoid using *before/after* if you include AMQP::Spec - instead, use
+*em_before/em_after* hooks that run inside the EM event loop. One more note: you don't need
+to call 'done' inside *em_before/em_after*, otherwise it'll shut down the reactor.
+
 
   describe AMQP do
     include AMQP::Spec
 
-    default_options :host => 'my.amqp.broker.org', :port => '21118'
-    default_timeout 1
+    default_options = {:host => 'my.amqp.broker.org', :port => '21118'}
+    default_timeout = 1
+
+    em_before { @start = Time.now }
 
     it "requires a call to #done in every example" do
       1.should == 1
@@ -104,10 +114,9 @@ inside the EM loop but before/after AMQP loop (these hooks are currently not imp
     end
     
     it "runs test code in an amqp block automatically" do
-      start = Time.now
 
       EM.add_timer(0.5){
-        (Time.now-start).should be_close( 0.5, 0.1 )
+        (Time.now-@start).should be_close( 0.5, 0.1 )
         done
       }
     end
@@ -122,9 +131,9 @@ inside the EM loop but before/after AMQP loop (these hooks are currently not imp
     end
   end
 
-Finally, you can include AMQP::EMSpec in your describe block. This will run all the group examples
-inside em block instead of amqp. before{} and after{} hooks should be finished with 'done', same as
-when including AMQP::Spec, and same caution about using them applies.
+Finally, you can include AMQP::EMSpec in your describe block. This will run all the group
+examples inside em block instead of amqp. *before/after* hooks should be finished
+with #done, same as when including AMQP::Spec, and same caution about using them applies.
 
   describe AMQP do
     include AMQP::EMSpec
@@ -157,9 +166,11 @@ when including AMQP::Spec, and same caution about using them applies.
 
 ==General notes
 
-For a developer new to evented specs, it is not easy to internalize that the blocks given to asynchronous
-methods are turned into real callbacks, intended to fire some time later. It is not easy to keep track of
-the actual execution path of your code, when your blocks are supposed to fire and in what sequence.
+For a developer new to evented specs, it is not easy to internalize that the blocks given
+to asynchronous methods are turned into real callbacks, intended to fire some time later.
+It is not easy to keep track of the actual execution path of your code, when your blocks
+are supposed to fire and in what sequence.
+
 Take the following spec as an example:
 
   it 'receives published message' do
@@ -174,22 +185,24 @@ Take the following spec as an example:
     end
   end
 
-Seems like a straightforward spec: you subscribe to a message queue, you set expectations inside
-your subscribe block, then you publish into this queue, then you call done. What may be wrong with it?
-Well, if you happen to use this spec against live AMQP broker, everything may be wrong.
-First, communication delays. There is no guarantee that by the time you publish your message, the queue
-have been either created or subscribed to. There is also no guarantee that your subscriber received
-the message by the time you are unsubscribing and deleting your queue.
-Second, sequence of your blocks. Remember, they are delayed callbacks! Don't just assume your previous
-block is already executed when you start your new asynchronous action. In this spec, when done is called,
-it stops everything before your subscribe callback even has a chance to fire. As a result, you'll get a
-PASSING spec even though your expectation was never executed!
-
-How to improve this spec? Allow some time for async actions to finish: either use EM timers or pass
-:nowait=>false to your asynch calls to force them into synchronicity. Keep in mind the sequence in which
-your callbacks are expected to fire - so place your done call at the end of subscribe block in this
-example. If you want to be paranoid, you can set flags inside your callbacks and then check that they
-actually fired at all AFTER your amqp/em block. Something like this will do the trick:
+Seems like a straightforward spec: you subscribe to a message queue, you set expectations
+inside your subscribe block, then you publish into this queue, then you call done. What may
+be wrong with it? Well, if you happen to use this spec against live AMQP broker, everything
+may be wrong. First, communication delays. There is no guarantee that by the time you publish
+your message, the queue have been either created or subscribed to. There is also no guarantee
+that your subscriber received the message by the time you are unsubscribing and deleting your
+queue. Second, sequence of your blocks. Remember, they are delayed callbacks! Don't just
+assume your previous block is already executed when you start your new asynchronous action.
+In this spec, when done is called, it stops everything before your subscribe callback even
+has a chance to fire. As a result, you'll get a PASSING spec even though your expectation
+was never executed!
+
+How to improve this spec? Allow some time for async actions to finish: either use EM timers
+or pass :nowait=>false to your asynch calls to force them into synchronicity. Keep in mind
+the sequence in which your callbacks are expected to fire - so place your done call at the
+end of subscribe block in this example. If you want to be paranoid, you can set flags inside
+your callbacks and then check that they actually fired at all AFTER your amqp/em block.
+Something like this will do the trick:
 
   it 'receives published message' do
     amqp do
@@ -208,10 +221,11 @@ actually fired at all AFTER your amqp/em block. Something like this will do the
 
 ==Limitations
 
-AMQP-Spec can be currently used with Rspec only. I suppose, there is nothing special in extending EM-Spec's
-test unit and bacon support, I just do not have experience dealing with these platforms. Another limitation,
-it uses native Fibers and therefore not compatible with Ruby 1.8. Again, it seems possible to rewrite it in
-1.8-compatible style, with string evals and Fiber backport, but I'd rather leave this work to someone else.
+AMQP-Spec can be currently used with Rspec only. I suppose, there is nothing special in
+extending EM-Spec's test unit and bacon support, I just do not have experience dealing with
+these platforms. Another limitation, it uses native Fibers and therefore not compatible with
+Ruby 1.8. Again, it seems possible to rewrite it in 1.8-compatible style, with string evals
+and Fiber backport, but I'd rather leave this work to someone else.
 
 Any help improving this library is greatly appreciated...
 

data/VERSION

@@ -1 +1 @@
-0.2.7
+0.3.0

data/lib/amqp-spec.rb

@@ -20,5 +20,5 @@ end
 
 # Require all ruby source files located under directory lib/amqp-spec
 # If you need files in specific order, you should specify it here before the glob
-AMQP::Spec.require_libs %W[**/*]
+AMQP::Spec.require_libs %W[rspec]
 

data/lib/amqp-spec/amqp.rb

@@ -1,5 +1,6 @@
 require 'mq'
 
+# Monkey patching some methods into AMQP to make it more testable
 module AMQP
 
   # Initializes new AMQP client/connection without starting another EM loop
@@ -24,9 +25,9 @@ module AMQP
   # Cleans up AMQP state after AMQP connection closes
   def self.cleanup_state
 #   MQ.reset ?
-    Thread.list.each {|thread| thread[:mq] = nil }
-    Thread.list.each {|thread| thread[:mq_id] = nil }
-    @conn                  = nil
-    @closing               = false
+    Thread.list.each { |thread| thread[:mq] = nil }
+    Thread.list.each { |thread| thread[:mq_id] = nil }
+    @conn    = nil
+    @closing = false
   end
 end

data/lib/amqp-spec/evented_example.rb

@@ -0,0 +1,160 @@
+require 'fiber' unless Fiber.respond_to?(:current)
+
+module AMQP
+
+  module SpecHelper
+
+    # Represents example running inside some type of event loop
+    class EventedExample
+
+      # Create new evented example
+      def initialize opts = {}, example_group_instance, &block
+        @opts, @example_group_instance, @block = opts, example_group_instance, block
+      end
+
+      # Sets timeout for currently running example
+      #
+      def timeout(spec_timeout)
+        EM.cancel_timer(@spec_timer) if @spec_timer
+        @spec_timer = EM.add_timer(spec_timeout) do
+          @spec_exception = SpecTimeoutExceededError.new "Example timed out"
+          done
+        end
+      end
+
+      # Breaks the event loop and finishes the spec.
+      #
+      # This is under-implemented (generic) method that only implements optional delay.
+      # It should be given a block that does actual work of finishing up the event loop
+      # and cleaning any remaining artifacts.
+      #
+      # Please redefine it inside descendant class and call super.
+      #
+      def done delay=nil, &block
+        if delay
+          EM.add_timer delay, &block
+        else
+          block.call
+        end
+      end
+
+      # Retrieves metadata passed in from enclosing example groups
+      #
+      def metadata
+        @metadata ||= @example_group_instance.metadata.dup rescue {}
+      end
+
+      # Runs hooks of specified type (hopefully, inside the event loop)
+      #
+      def run_hooks type
+        hooks = @example_group_instance.class.em_hooks[type]
+        (:before == type ? hooks : hooks.reverse).each do |hook|
+          if @example_group_instance.respond_to? :instance_eval_without_event_loop
+            @example_group_instance.instance_eval_without_event_loop(&hook)
+          else
+            @example_group_instance.instance_eval(&hook) #_with_rescue(&hook)
+          end
+        end
+      end
+
+      # Runs given block inside EM event loop.
+      # Double-round exception handler needed because some of the exceptions bubble
+      # outside of event loop due to asynchronous nature of evented examples
+      #
+      def run_em_loop
+        begin
+          EM.run do
+            run_hooks :before
+
+            @spec_exception = nil
+            timeout(@opts[:spec_timeout]) if @opts[:spec_timeout]
+            begin
+              yield
+            rescue Exception => @spec_exception
+#              p "Inside loop, caught #{@spec_exception}"
+              done # We need to properly terminate the event loop
+            end
+          end
+        rescue Exception => @spec_exception
+#          p "Outside loop, caught #{@spec_exception}"
+          run_hooks :after # Event loop was broken, but we still need to run em_after hooks
+        ensure
+          finish_example
+        end
+      end
+
+      # Stops EM event loop. It is called from #done
+      #
+      def finish_em_loop
+        run_hooks :after
+        EM.stop_event_loop if EM.reactor_running?
+      end
+
+      # Called from #run_event_loop when event loop is stopped, but before example returns.
+      # Descendant classes may redefine to clean up type-specific state.
+      #
+      def finish_example
+        raise @spec_exception if @spec_exception
+      end
+
+    end # class EventedExample
+
+    # Represents spec running inside AMQP.run loop
+    class EMExample < EventedExample
+
+      # Run @block inside the EM.run event loop
+      def run
+        run_em_loop &@block
+      end
+
+      # Breaks the EM event loop and finishes the spec.
+      # Done yields to any given block first, then stops EM event loop.
+      #
+      def done(delay=nil)
+        super(delay) do
+          yield if block_given?
+          EM.next_tick do
+            finish_em_loop
+          end
+        end
+      end # done
+    end # class EMExample < EventedExample
+
+    # Represents spec running inside AMQP.run loop
+    class AMQPExample < EventedExample
+
+      # Run @block inside the AMQP.start loop
+      def run
+        run_em_loop do
+          AMQP.start_connection @opts, &@block
+        end
+      end
+
+      # Breaks the event loop and finishes the spec. It yields to any given block first,
+      # then stops AMQP, EM event loop and cleans up AMQP state.
+      #
+      def done(delay=nil)
+        super(delay) do
+          yield if block_given?
+          EM.next_tick do
+            if AMQP.conn and not AMQP.closing
+              AMQP.stop_connection do
+                finish_em_loop
+              end
+            else
+              finish_em_loop
+            end
+          end
+        end
+      end
+
+      # Called from run_event_loop when event loop is finished, before any exceptions
+      # is raised or example returns. We ensure AMQP state cleanup here
+      def finish_example
+        AMQP.cleanup_state
+        super
+      end
+
+    end # class AMQPExample < EventedExample
+  end # module SpecHelper
+end # module AMQP

data/lib/amqp-spec/rspec.rb

@@ -1,51 +1,49 @@
-require 'fiber' unless Fiber.respond_to?(:current)
 require 'amqp-spec/amqp'
+require 'amqp-spec/evented_example'
 
 # You can include one of the following modules into your example groups:
 # AMQP::SpecHelper,
 # AMQP::Spec,
 # AMQP::EMSpec.
 #
-# AMQP::SpecHelper module defines #ampq method that can be safely used inside your specs(examples)
-# to test expectations inside running AMQP.start loop. Each loop is running in a separate Fiber,
-# and you can control for timeouts using either :spec_timeout option given to #amqp method,
-# or setting default timeout with class method default_timeout(timeout). In addition to #amqp
-# method, you can use #em method - it creates plain EM.run loop without starting AMQP.
+# AMQP::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 AMQP::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 class method is defined. Remember, when using AMQP::Specs, you
-# will have a single set of AMQP.start options for all your examples.
+# If you include AMQP::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 AMQP::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.
-# For example, if you are using subscribe block that tests expectations on messages, 'done' should be
-# probably called at the end of this block.
+# 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 AMQP
-  # AMQP::SpecHelper module defines #ampq method that can be safely used inside your specs(examples)
-  # to test expectations inside running AMQP.start loop. Each loop is running in a separate Fiber,
-  # and you can control for timeouts using either :spec_timeout option given to #amqp method,
-  # or setting default timeout with class method default_timeout(timeout). In addition to #amqp
-  # method, you can use #em method - it creates plain EM.run loop without starting AMQP.
-  #
-  # TODO: Define 'async' method wrapping async requests and returning results... 'async_loop' too for subscribe block?
-  # TODO: 'evented_before', 'evented_after' that will be run inside EM before the example
+
+  # AMQP::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.
   #
   # noinspection RubyArgCount
   module SpecHelper
 
     SpecTimeoutExceededError = Class.new(RuntimeError)
 
-    # Class methods (macros) for example group that includes SpecHelper
+    # Class methods (macros) for any example groups that includes SpecHelper.
+    # You can use these methods as macros inside describe/context block.
     #
     module GroupMethods
-      unless respond_to?(:metadata)
-        # Hacking in metadata into RSpec1 to imitate Rspec2's metadata.
-        # You can add to metadata Hash to pass options into examples and
-        # nested groups.
+      unless respond_to? :metadata
+        # Hacking in metadata into RSpec1 to imitate Rspec2's metadata. Now you can add
+        # anything to metadata Hash to pass options into examples and nested groups.
         #
         def metadata
           @metadata ||= superclass.metadata.dup rescue {}
@@ -55,96 +53,76 @@ module AMQP
       # Sets/retrieves default timeout for running evented specs for this
       # example group and its nested groups.
       #
-      def default_timeout(spec_timeout=nil)
-        metadata[:em_default_timeout] = spec_timeout if spec_timeout
-        metadata[:em_default_timeout]
+      def default_timeout spec_timeout=nil
+        metadata[:em_timeout] = spec_timeout if spec_timeout
+        metadata[:em_timeout]
       end
 
       # Sets/retrieves default AMQP.start options for this example group
       # and its nested groups.
       #
-      def default_options(opts=nil)
-        metadata[:em_default_options] = opts if opts
-        metadata[:em_default_options]
+      def default_options opts=nil
+        metadata[:em_defaults] = opts if opts
+        metadata[:em_defaults]
+      end
+
+      # Add before hook that will run inside EM event loop
+      def em_before scope = :each, &block
+        raise ArgumentError, "em_before only supports :each scope" unless :each == scope
+        em_hooks[:before] << block
+      end
+
+      # Add after hook that will run inside EM event loop
+      def em_after scope = :each, &block
+        raise ArgumentError, "em_after only supports :each scope" unless :each == scope
+        em_hooks[:after] << block
+      end
+
+      # Collection of evented hooks
+      def em_hooks
+        metadata[:em_hooks] ||= {:before => [], :after => []}
       end
     end
 
-    def self.included(example_group)
+    def self.included example_group
       unless example_group.respond_to? :default_timeout
-        example_group.extend(GroupMethods)
-        example_group.metadata[:em_default_options] = {}
-        example_group.metadata[:em_default_timeout] = nil
+        example_group.extend GroupMethods
+        example_group.metadata[:em_defaults] = {}
+        example_group.metadata[:em_timeout] = nil
       end
     end
 
-
-    # Yields to given block inside EM.run and AMQP.start loops. This method takes any option that is
-    # also accepted by EventMachine::connect. Also, options for AMQP.start include:
-    # * :user => String (default ‘guest’) - The username as defined by the AMQP server.
-    # * :pass => String (default ‘guest’) - The password for the associated :user as defined by the AMQP server.
-    # * :vhost => String (default ’/’)    - The virtual host as defined by the AMQP server.
+    # Yields to a given block inside EM.run and AMQP.start loops. This method takes
+    # any option that is accepted by EventMachine::connect. Options for AMQP.start include:
+    # * :user => String (default ‘guest’) - Username as defined by the AMQP server.
+    # * :pass => String (default ‘guest’) - Password as defined by the AMQP server.
+    # * :vhost => String (default ’/’)    - Virtual host as defined by the AMQP server.
     # * :timeout => Numeric (default nil) - *Connection* timeout, measured in seconds.
-    # * :logging => true | false (default false) - Toggle the extremely verbose AMQP logging.
+    # * :logging => Bool (default false) - Toggle the extremely verbose AMQP logging.
     #
-    # In addition to EM and AMQP options, :spec_timeout option (in seconds) is used to force spec to timeout
-    # if something goes wrong and EM/AMQP loop hangs for some reason. SpecTimeoutExceededError is raised.
+    # In addition to EM and AMQP options, :spec_timeout option (in seconds) is used
+    # to force spec to timeout if something goes wrong and EM/AMQP loop hangs for some
+    # reason. SpecTimeoutExceededError is raised if it happens.
     #
     def amqp opts={}, &block
       opts = self.class.default_options.merge opts
-      begin
-        EM.run do
-          @_em_spec_with_amqp = true
-          @_em_spec_exception = nil
-          spec_timeout        = opts.delete(:spec_timeout) || self.class.default_timeout
-          timeout(spec_timeout) if spec_timeout
-          @_em_spec_fiber     = Fiber.new do
-            begin
-              AMQP.start_connection opts, &block
-            rescue Exception => @_em_spec_exception
-              done
-            end
-            Fiber.yield
-          end
-
-          @_em_spec_fiber.resume
-        end
-      rescue Exception => outer_spec_exception
-        # Make sure AMQP state is cleaned even after Rspec failures
-        AMQP.cleanup_state
-        raise outer_spec_exception
-      end
+      opts[:spec_timeout] ||= self.class.default_timeout
+      @evented_example = AMQPExample.new(opts, self, &block)
+      @evented_example.run
     end
 
-    # 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. SpecTimeoutExceededError is raised.
+    # 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. SpecTimeoutExceededError is raised if it happens.
     #
-    def em(spec_timeout = self.class.default_timeout, &block)
-      spec_timeout = spec_timeout[:spec_timeout] || self.class.default_timeout if spec_timeout.is_a?(Hash)
-      EM.run do
-        @_em_spec_with_amqp = false
-        @_em_spec_exception = nil
-        timeout(spec_timeout) if spec_timeout
-        @_em_spec_fiber     = Fiber.new do
-          begin
-            block.call
-          rescue Exception => @_em_spec_exception
-            done
-          end
-          Fiber.yield
-        end
-
-        @_em_spec_fiber.resume
-      end
-    end
-
-    # Sets timeout for current running example
-    #
-    def timeout(spec_timeout)
-      EM.cancel_timer(@_em_timer) if @_em_timer
-      @_em_timer = EM.add_timer(spec_timeout) do
-        @_em_spec_exception = SpecTimeoutExceededError.new
-        done
+    def em opts = {}, &block
+      if opts.is_a? Hash
+        opts[:spec_timeout] ||= self.class.default_timeout
+      else
+        opts = {spec_timeout: opts}
       end
+      @evented_example = EMExample.new(opts, self, &block)
+      @evented_example.run
     end
 
     # Breaks the event loop and finishes the spec. This should be called after
@@ -156,58 +134,31 @@ module AMQP
     # that your (default or explicit) spec timeout may fire before your delayed done
     # callback is due, leading to SpecTimeoutExceededError
     #
-    def done(delay=nil)
-      done_proc = proc do
-        yield if block_given?
-        EM.next_tick do
-          if @_em_spec_with_amqp
-            if AMQP.conn and not AMQP.closing
-              AMQP.stop_connection do
-                finish_em_spec_fiber { AMQP.cleanup_state }
-              end
-            else
-              finish_em_spec_fiber { AMQP.cleanup_state }
-            end
-          else
-            finish_em_spec_fiber
-          end
-        end
-      end
-      if delay
-        EM.add_timer delay, &done_proc
-      else
-        done_proc.call
-      end
+    def done *args, &block
+      @evented_example.done *args, &block
     end
 
-    # Retrieves metadata passed in from enclosing example groups
+    # Manually sets timeout for currently running example
     #
-    def metadata
-      @metadata ||= self.class.metadata.dup rescue {}
+    def timeout *args
+      @evented_example.timeout *args
     end
 
-    private
+  end # module SpecHelper
 
-    # Stops EM loop, executes optional block, finishes off fiber and raises exception if any
-    #
-    def finish_em_spec_fiber
-      EM.stop_event_loop if EM.reactor_running?
-      yield if block_given?
-      @_em_spec_fiber.resume if @_em_spec_fiber.alive?
-      raise @_em_spec_exception if @_em_spec_exception
-    end
-  end
-
-  # If you include AMQP::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 class method is defined. Remember, when using AMQP::Specs, you
-  # will have a single set of AMQP.start options for all your examples.
+  # If you include AMQP::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 class method is defined. Remember,
+  # when using AMQP::Specs, you'll have a single set of AMQP.start options for all your
+  # examples.
   #
   module Spec
     def self.included(example_group)
       example_group.send(:include, SpecHelper)
     end
 
+    alias instance_eval_without_event_loop instance_eval
+
     def instance_eval(&block)
       amqp do
         super(&block)
@@ -215,18 +166,20 @@ module AMQP
     end
   end
 
-  # Including AMQP::EMSpec module into your example group, each example of this group will run
-  # inside EM.run loop without the need to explicitly call 'em'.
+  # Including AMQP::EMSpec module into your example group, each example of this group
+  # will run inside EM.run loop without the need to explicitly call 'em'.
   #
   module EMSpec
     def self.included(example_group)
       example_group.send(:include, SpecHelper)
     end
 
+    alias instance_eval_without_event_loop instance_eval
+
     def instance_eval(&block)
       em do
         super(&block)
       end
     end
   end
-end
+end

data/spec/em_hooks_spec.rb

@@ -0,0 +1,156 @@
+require 'spec_helper'
+
+shared_examples_for 'hooked em specs' do
+  it 'should execute em_before' do
+    em do
+      @hooks_called.should include :em_before
+      @hooks_called.should_not include :em_after
+      done
+    end
+  end
+
+  it 'should execute em_after if business exception is raised' do
+    em do
+      expect {
+        raise StandardError
+      }.to raise_error
+      done
+    end
+  end
+
+  it 'should execute em_after if RSpec expectation fails' do
+    em do
+      expect { :this.should == :fail
+      }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+      done
+    end
+  end
+end
+
+shared_examples_for 'hooked amqp specs' do
+  it 'should execute em_before' do
+    amqp do
+      @hooks_called.should include :em_before
+      @hooks_called.should_not include :em_after
+      done
+    end
+  end
+
+  it 'should execute em_after if business exception is raised' do
+    amqp do
+      expect {
+        raise StandardError
+      }.to raise_error
+      done
+    end
+  end
+
+  it 'should execute em_after if RSpec expectation fails' do
+    amqp do
+      expect { :this.should == :fail
+      }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+      done
+    end
+  end
+end
+
+describe AMQP, " with em_before/em_after" do
+  before { @hooks_called = [] } #; puts "In before: #{self}"}  #
+
+  describe AMQP, " tested with AMQP::SpecHelper" do
+    include AMQP::SpecHelper
+    default_options AMQP_OPTS if defined? AMQP_OPTS
+
+    before { @hooks_called << :before } #; puts "In before 2: #{self}" }
+
+    em_before { @hooks_called << :em_before } # puts "In em_before: #{self}";
+    em_after { @hooks_called << :em_after } # puts "In em_after: #{self}";
+
+    context 'for non-evented specs' do
+      after { @hooks_called.should == [:before] }
+
+      it 'should NOT execute em_before or em_after' do
+        @hooks_called.should_not include :em_before
+        @hooks_called.should_not include :em_after
+      end
+
+      it 'should NOT execute em_after if business exception is raised' do
+        expect { raise StandardError
+        }.to raise_error
+      end
+
+      it 'should execute em_after if RSpec expectation fails' do
+        expect { :this.should == :fail
+        }.to raise_error RSPEC::Expectations::ExpectationNotMetError
+      end
+    end # context 'for non-evented specs'
+
+    context 'for evented specs' do #, pending: true do
+      after { @hooks_called.should include :before, :em_before, :em_after }
+
+      context 'with em block' do
+
+        it_should_behave_like 'hooked em specs'
+
+        context 'inside nested example group' do
+          before { @hooks_called << :context_before }
+          em_before { @hooks_called << :context_em_before }
+          em_after { @hooks_called << :context_em_after }
+
+          after { @hooks_called.should include :before,
+                                               :context_before,
+                                               :em_before,
+                                               :context_em_before,
+                                               :context_em_after,
+                                               :em_after }
+
+          it 'should fire both nested :before hooks' do
+            em do
+              @hooks_called.should include :before,
+                                           :context_before,
+                                           :em_before,
+                                           :context_em_before
+              @hooks_called.should_not include :em_after, :context_em_after
+              done
+            end
+          end
+
+          it_should_behave_like 'hooked em specs'
+
+        end # context 'inside nested example group'
+      end # context 'with em block'
+
+      context 'with amqp block' do
+
+        it_should_behave_like 'hooked amqp specs'
+
+        context 'inside nested example group' do
+          before { @hooks_called << :context_before }
+          em_before { @hooks_called << :context_em_before }
+          em_after { @hooks_called << :context_em_after }
+
+          after { @hooks_called.should include :before,
+                                               :context_before,
+                                               :em_before,
+                                               :context_em_before,
+                                               :context_em_after,
+                                               :em_after }
+
+          it 'should fire both nested :before hooks' do
+            amqp do
+              @hooks_called.should include :before,
+                                           :context_before,
+                                           :em_before,
+                                           :context_em_before
+              @hooks_called.should_not include :em_after, :context_em_after
+              done
+            end
+          end
+
+          it_should_behave_like 'hooked amqp specs'
+
+        end # context 'inside nested example group'
+      end # context 'with amqp block'
+    end # context 'for evented specs'
+  end # describe AMQP, " tested with AMQP::SpecHelper"
+end # describe AMQP, " with em_before/em_after"

data/spec/failing_rspec_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe 'Following examples should all be failing:' do
+describe 'Following 8 examples should all be failing:' do
   describe EventMachine, " when running failing examples" do
     include AMQP::EMSpec
 
@@ -19,8 +19,6 @@ describe 'Following examples should all be failing:' do
   describe EventMachine, " when testing with AMQP::EMSpec with a maximum execution time per test" do
     include AMQP::EMSpec
 
-    # For RSpec 1, default_timeout and default_options are global
-    # For RSpec 2, default_timeout and default_options are example-group local, inheritable by nested groups
     default_timeout 1
 
     it 'should timeout before reaching done' do
@@ -37,8 +35,6 @@ describe 'Following examples should all be failing:' do
 
     include AMQP::Spec
 
-    # For RSpec 1, default_timeout and default_options are global
-    # For RSpec 2, default_timeout and default_options are example-group local, inheritable by nested groups
     default_timeout 1
 
     it 'should timeout before reaching done' do

data/spec/problematic_rspec_spec.rb

@@ -1,5 +1,4 @@
-require_relative 'spec_helper.rb'
+require 'spec_helper'
 
 describe '!!!!!!!!! LEAKING OR PROBLEMATIC EXAMPLES !!!!!!!!!' do
-end
-
+end

data/spec/rspec_amqp_spec.rb

@@ -1,4 +1,4 @@
-require_relative 'spec_helper.rb'
+require 'spec_helper'
 
 def publish_and_consume_once(queue_name="test_sink", data="data")
   amqp do
@@ -27,8 +27,8 @@ describe 'Evented AMQP specs' do
     default_options AMQP_OPTS if defined? AMQP_OPTS
     default_timeout 1
 
-    puts "Default timeout: #{default_timeout}, Default options:"
-    p default_options
+    puts "Default timeout: #{default_timeout}"
+    puts "Default options :#{default_options}"
 
     it_should_behave_like 'SpecHelper examples'
 

data/spec/rspec_em_spec.rb

@@ -1,4 +1,4 @@
-require_relative 'spec_helper.rb'
+require 'spec_helper'
 
 describe 'Plain EM, no AMQP' do
   describe EventMachine, " when testing with AMQP::SpecHelper" do

data/spec/shared_examples.rb

@@ -47,6 +47,7 @@ shared_examples_for 'SpecHelper examples' do
     AMQP.conn.should be_nil
   end
 
+  # TODO: remove dependency on (possibly long) DNS lookup
   it "should gracefully exit if no AMQP connection was made" do
     expect {
       amqp(:host => 'Impossible') do
@@ -58,6 +59,7 @@ shared_examples_for 'SpecHelper examples' do
   end
 
   it_should_behave_like 'done examples'
+
   it_should_behave_like 'timeout examples'
 end
 
@@ -101,7 +103,7 @@ shared_examples_for 'timeout examples' do
 
   it 'should timeout before reaching done because of default spec timeout' do
     expect { amqp { EM.add_timer(2) { done } } }.
-            to raise_error SpecTimeoutExceededError
+        to raise_error SpecTimeoutExceededError
     (Time.now-@start).should be_close(1.0, 0.1)
   end
 
@@ -117,13 +119,13 @@ shared_examples_for 'timeout examples' do
 
   specify "spec timeout given in amqp options has higher priority than default" do
     expect { amqp(:spec_timeout => 0.2) {} }.
-            to raise_error SpecTimeoutExceededError
+        to raise_error SpecTimeoutExceededError
     (Time.now-@start).should be_close(0.2, 0.1)
   end
 
   specify "but timeout call inside amqp loop has even higher priority" do
     expect { amqp(:spec_timeout => 0.5) { timeout(0.2) } }.
-            to raise_error SpecTimeoutExceededError
+        to raise_error SpecTimeoutExceededError
     (Time.now-@start).should be_close(0.2, 0.1)
   end
 
@@ -131,25 +133,22 @@ shared_examples_for 'timeout examples' do
     AMQP.conn.should be_nil
   end
 
-  if rspec2?
-    context 'embedded context can set up separate defaults' do
-      default_timeout 0.2 # Can be used to set default :spec_timeout for all your amqp-based specs
+  context 'embedded context can set up separate defaults' do
+    default_timeout 0.2 # Can be used to set default :spec_timeout for all evented specs
 
-      specify 'default timeout should be 0.2' do
-        expect { amqp { EM.add_timer(2) { done } } }.to raise_error SpecTimeoutExceededError
-        (Time.now-@start).should be_close(0.2, 0.1)
-      end
+    specify 'default timeout should be 0.2' do
+      expect { em { EM.add_timer(2) { done } } }.to raise_error SpecTimeoutExceededError
+      (Time.now-@start).should be_close(0.2, 0.1)
+    end
 
-      context 'deeply embedded context can set up separate defaults' do
-        default_timeout 0.5 # Can be used to set default :spec_timeout for all your amqp-based specs
+    context 'deeply embedded context can set up separate defaults' do
+      default_timeout 0.5
 
-        specify 'default timeout should be 0.5' do
-          expect { amqp { EM.add_timer(2) { done } } }.to raise_error SpecTimeoutExceededError
-          (Time.now-@start).should be_close(0.5, 0.1)
-        end
+      specify 'default timeout should be 0.5' do
+        expect { amqp { EM.add_timer(2) { done } } }.to raise_error SpecTimeoutExceededError
+        (Time.now-@start).should be_close(0.5, 0.1)
       end
     end
-
   end
 end
 

data/spec/spec_helper.rb

@@ -12,6 +12,10 @@ def rspec2?
   defined?(RSpec)
 end
 
+# Done is defined as noop to help share examples between evented and non-evented specs
+def done
+end
+
 RSPEC = rspec2? ? RSpec : Spec
 
 amqp_config = File.dirname(__FILE__) + '/amqp.yml'

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: amqp-spec
 version: !ruby/object:Gem::Version 
-  hash: 25
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 7
-  version: 0.2.7
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Arvicco
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-04 00:00:00 +03:00
+date: 2010-11-16 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 13
         segments: 
         - 1
         - 2
@@ -42,7 +40,6 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 9
         segments: 
         - 0
         - 6
@@ -62,10 +59,12 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - lib/amqp-spec/amqp.rb
+- lib/amqp-spec/evented_example.rb
 - lib/amqp-spec/rspec.rb
 - lib/amqp-spec.rb
 - lib/version.rb
 - spec/amqp.yml
+- spec/em_hooks_spec.rb
 - spec/failing_rspec_spec.rb
 - spec/problematic_rspec_spec.rb
 - spec/rspec_amqp_spec.rb
@@ -104,7 +103,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -113,7 +111,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -126,6 +123,7 @@ specification_version: 3
 summary: Simple API for writing asynchronous EventMachine/AMQP specs. Supports RSpec and RSpec2.
 test_files: 
 - spec/amqp.yml
+- spec/em_hooks_spec.rb
 - spec/failing_rspec_spec.rb
 - spec/problematic_rspec_spec.rb
 - spec/rspec_amqp_spec.rb