evented-spec 0.4.0 → 0.4.1

data/HISTORY

@@ -94,4 +94,11 @@
 
 * Forked into evented-spec.
 * cool.io support
-* Using amqp 0.8.* API instead of 0.7.*
+* Using amqp 0.8.* API instead of 0.7.*
+
+== 0.4.1 / 2011-04-29
+
+* More cool.io goodies:
+  * EventedSpec::CoolioSpec module similar to EMSpec and AMQPSpec
+  * coolio_before / coolio_after hooks
+* #delayed helper

data/README.textile

@@ -4,7 +4,7 @@ Evented-spec is a set of helpers to help you test your asynchronous code.
 
 EventMachine/Cool.io-based code, including asynchronous "AMQP library":https://github.com/ruby-amqp/ruby-amqp is notoriously difficult to test. To the point that many people recommend using either "mocks":https://github.com/danielsdeleo/moqueue or "synchronous libraries":https://github.com/ruby-amqp/bunny 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 just mocks.
 
-"em-spec":https://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, and, subsequently, evented-spec add more helpers to keep your specs from being bloated.
+"em-spec":https://github.com/tmm1/em-spec gem made it easier to write evented specs, but it had 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, and, subsequently, evented-spec add more helpers to keep your specs from being bloated.
 
 h2. Usage
 
@@ -47,7 +47,7 @@ h3. EventedSpec::SpecHelper
 
 All three accept a hash of options. Look into method documentation to learn more.
 
-h3. EventedSpec::EMSpec, EventedSpec::AMQPSpec
+h3. EventedSpec::EMSpec, EventedSpec::AMQPSpec, EventedSpec::CoolioSpec
 
 @EventedSpec::EMSpec@ wraps every example in em block, so it might save you a couple of lines per example. @EventedSpec::AMQPSpec@ wraps every example in amqp block.
 
@@ -83,17 +83,21 @@ end
 
 h2. Hooks
 
-There are 4 hooks available to evented specs:
+There are 6 hooks available to evented specs:
 
 * @em_before@ -- launches after reactor started, before example runs
 * @em_after@ -- launches right before reactor is stopped, after example runs
 * @amqp_before@ -- launches after amqp connects, before example runs
 * @amqp_after@ -- launches before amqp disconnects, after example runs
+* @coolio_before@ -- launches after Cool.io starts, before example runs
+* @coolio_after@ -- launches before Cool.io stops, after example runs
 
-So, the order of hooks is as follows: @before(:all)@, @before(:each)@,
+So, the order of hooks for an AMQP spec is as follows: @before(:all)@, @before(:each)@,
 @em_before@, @amqp_before@, example, @amqp_after@, @em_after@, @after(:each)@,
 @after(:all)@
 
+
+
 bc. describe "using amqp hooks" do
   include EventedSpec::AMQPSpec
   default_timeout 0.5
@@ -117,10 +121,6 @@ bc. describe "using amqp hooks" do
   end
 end
 
-h2. AMQP gem compatibility
-
-AMQP spec helpers are for newer version of AMQP gem, 0.8. If you need spec-helpers for AMQP gem 0.7, take a look at "amqp-spec":https://github.com/ruby-amqp/amqp-spec, API is mostly the same.
-
 h2. Words of warning on blocking the reactor
 
 Evented specs are currently run inside of reactor thread. What this effectively means is that you *should not block* during spec execution.
@@ -149,6 +149,48 @@ bc. describe "using amqp" do
   end
 end
 
+You can also use #delayed helper method to maintain order of execution when callbacks are not an option.
+
+bc. describe "using amqp" do
+  include EventedSpec::AMQPSpec
+  it "should do something useful" do
+    channel = AMQP::Channel.new
+    @stage = 0
+    delayed(0.2) {
+      channel.should be_open
+      @stage = 1
+    }
+    delayed(0.3) {
+      @stage.should == 1
+      done
+    }
+    delayed(0.4) {
+      # this block is never going to be executed
+      raise "Help me!"
+    }
+  end
+end
+
+
+h2. I have an existing reactor running in separate thread, amqp specs won't work for me what should I do?
+
+Unfortunately, right now there aren't many remedies to your problem, besides stopping the event loop in before(:all) hook like this:
+
+bc. describe "Example" do
+  before(:all) { EM.stop_event_loop; sleep(0.1) }
+  after(:all) { do_something_to_restart_the_eventmachine }
+  include EventedSpec::SpecHelper
+  it "should do something" do
+    em { done }
+  end
+end
+
+Reason is simple: if we don't restart event loop every spec example, all kinds of state leaks may occur: stale timers, delayed exceptions, weirdest errors and even segfaults. It isn't impossible but it certainly is very invasive.
+
+h2. Compatibility
+
+EventedSpec is tested with RSpec >= 2.5.0, Cool.io ~> 1.0.0, EventMachine >= 0.12.10, and AMQP >= 0.8.0. Running it with RSpec 1.3 and/or AMQP 0.7.0 is not unheard of, although not tested in all its entirety.
+
 h2. See also
 
 You can see evented-spec in use in spec suites for our amqp gems, "amq-client":https://github.com/ruby-amqp/amq-client/tree/master/spec and "amqp":https://github.com/ruby-amqp/amqp/tree/master/spec.
@@ -159,4 +201,4 @@ h2. Links
 * "amqp-spec":https://github.com/ruby-amqp/amqp-spec
 * "eventmachine":http://eventmachine.rubyforge.org/
 * "amqp":https://github.com/ruby-amqp/amqp
-* "amq-client":https://github.com/ruby-amqp/amq-client
+* "amq-client":https://github.com/ruby-amqp/amq-client

data/Rakefile

@@ -1,14 +1,13 @@
 require 'pathname'
-NAME = 'amqp-spec'
+NAME = 'evented-spec'
 BASE_PATH = Pathname.new(__FILE__).dirname
 LIB_PATH =  BASE_PATH + 'lib'
 PKG_PATH =  BASE_PATH + 'pkg'
 DOC_PATH =  BASE_PATH + 'rdoc'
 
 $LOAD_PATH.unshift LIB_PATH.to_s
-require 'version'
-
-CLASS_NAME = EventedSpec::AMQPSpec
+require 'evented-spec'
+CLASS_NAME = EventedSpec
 VERSION = CLASS_NAME::VERSION
 
 begin

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

data/lib/evented-spec.rb

@@ -1,2 +1,23 @@
+# There's little to no point in requiring only subset of evented-spec code yet,
+# but in case you really want to, it won't stand in your way.
+
+# These files are required
+require 'evented-spec/util'
 require 'evented-spec/version'
-require "evented-spec/rspec"
+require 'evented-spec/evented_example'
+require 'evented-spec/spec_helper'
+
+# As of now, amqp depends on em, em doesn't depend on anyone and
+# neither does coolio.
+# Pick the files accordingly.
+require 'evented-spec/evented_example/em_example'
+require 'evented-spec/evented_example/amqp_example'
+require 'evented-spec/evented_example/coolio_example'
+
+require 'evented-spec/spec_helper/event_machine_helpers'
+require 'evented-spec/spec_helper/amqp_helpers'
+require 'evented-spec/spec_helper/coolio_helpers'
+
+require 'evented-spec/em_spec'
+require 'evented-spec/amqp_spec'
+require 'evented-spec/coolio_spec'

data/lib/evented-spec/amqp_spec.rb

@@ -0,0 +1,27 @@
+module EventedSpec
+  # If you include EventedSpec::AMQPSpec 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 EventedSpec::Specs, you'll have a single set of AMQP.start options for all your
+  # examples.
+  #
+  module AMQPSpec
+    def self.included(example_group)
+      example_group.send(:include, SpecHelper)
+      example_group.extend(ClassMethods)
+    end
+
+    # @private
+    module ClassMethods
+      def it(*args, &block)
+        if block
+          new_block = Proc.new {|example_group_instance| (example_group_instance || self).instance_eval { amqp(&block) } }
+          super(*args, &new_block)
+        else
+          # pending example
+          super
+        end
+      end # it
+    end # ClassMethods
+  end # AMQPSpec
+end # module EventedSpec

data/lib/evented-spec/coolio_spec.rb

@@ -0,0 +1,26 @@
+module EventedSpec
+  # Including EventedSpec::CoolioSpec module into your example group, each example of this group
+  # will run inside cool.io loop without the need to explicitly call 'coolio'.
+  #
+  module CoolioSpec
+    def self.included(example_group)
+      example_group.send(:include, SpecHelper)
+      example_group.extend ClassMethods
+    end
+
+    # @private
+    module ClassMethods
+      def it(*args, &block)
+        if block
+          # Shared example groups seem to pass example group instance
+          # to the actual example block
+          new_block = Proc.new {|example_group_instance| (example_group_instance || self).instance_eval { coolio(&block) } }
+          super(*args, &new_block)
+        else
+          # pending example
+          super
+        end
+      end # it
+    end # ClassMethods
+  end # EMSpec
+end # module EventedSpec

data/lib/evented-spec/em_spec.rb

@@ -0,0 +1,26 @@
+module EventedSpec
+  # 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'.
+  #
+  module EMSpec
+    def self.included(example_group)
+      example_group.send(:include, SpecHelper)
+      example_group.extend ClassMethods
+    end
+
+    # @private
+    module ClassMethods
+      def it(*args, &block)
+        if block
+          # Shared example groups seem to pass example group instance
+          # to the actual example block
+          new_block = Proc.new {|example_group_instance| (example_group_instance || self).instance_eval { em(&block) } }
+          super(*args, &new_block)
+        else
+          # pending example
+          super
+        end
+      end # it
+    end # ClassMethods
+  end # EMSpec
+end # module EventedSpec

data/lib/evented-spec/evented_example.rb

@@ -7,7 +7,7 @@ module EventedSpec
     class EventedExample
       # Default options to use with the examples
       DEFAULT_OPTIONS = {
-        :spec_timeout => 1
+        :spec_timeout => 5
       }
 
       # Create new evented example
@@ -15,6 +15,16 @@ module EventedSpec
         @opts, @example_group_instance, @block = DEFAULT_OPTIONS.merge(opts), example_group_instance, block
       end
 
+      # Runs hooks of specified type (hopefully, inside event loop)
+      #
+      # @param hook type
+      def run_hooks(type)
+        @example_group_instance.class.evented_spec_hooks_for(type).each do |hook|
+          @example_group_instance.instance_eval(&hook)
+        end
+      end
+
+
       # Called from #run_event_loop when event loop is stopped,
       # but before the example returns.
       # Descendant classes may redefine to clean up type-specific state.
@@ -47,6 +57,8 @@ module EventedSpec
 
       # Override this method in your descendants
       #
+      # @note block should be evaluated in EventedExample descendant instance context
+      #       (e.g. in EMExample instance)
       # @note delay may be nil, implying you need to execute the block immediately.
       # @abstract
       def delayed(delay = nil, &block)
@@ -55,7 +67,3 @@ module EventedSpec
     end # class EventedExample
   end # module SpecHelper
 end # module AMQP
-
-require 'evented-spec/evented_example/em_example'
-require 'evented-spec/evented_example/amqp_example'
-require 'evented-spec/evented_example/coolio_example'

data/lib/evented-spec/evented_example/amqp_example.rb

@@ -1,3 +1,4 @@
+require 'evented-spec/ext/amqp'
 module EventedSpec
   module SpecHelper
     # Represents spec running inside AMQP.start loop
@@ -7,8 +8,8 @@ module EventedSpec
       # See {EventedExample#run}
       def run
         run_em_loop do
-          AMQP.start_connection(@opts) do
-            run_em_hooks :amqp_before
+          ::AMQP.start_connection(@opts) do
+            run_hooks :amqp_before
             @example_group_instance.instance_eval(&@block)
           end
         end
@@ -22,9 +23,9 @@ module EventedSpec
         delayed(delay) do
           yield if block_given?
           EM.next_tick do
-            run_em_hooks :amqp_after
-            if AMQP.connection && !AMQP.closing?
-              AMQP.stop_connection do
+            run_hooks :amqp_after
+            if ::AMQP.connection && !::AMQP.closing?
+              ::AMQP.stop_connection do
                 # Cannot call finish_em_loop before connection is marked as closed
                 # This callback is called before that happens.
                 EM.next_tick { finish_em_loop }
@@ -32,7 +33,7 @@ module EventedSpec
             else
               # Need this branch because if AMQP couldn't connect,
               # the callback would never trigger
-              AMQP.cleanup_state
+              ::AMQP.cleanup_state
               EM.next_tick { finish_em_loop }
             end
           end
@@ -44,7 +45,7 @@ module EventedSpec
       #
       # See {EventedExample#run}
       def finish_example
-        AMQP.cleanup_state
+        ::AMQP.cleanup_state
         super
       end
     end # class AMQPExample < EventedExample

data/lib/evented-spec/evented_example/coolio_example.rb

@@ -1,3 +1,4 @@
+require 'evented-spec/ext/coolio'
 #
 # Cool.io loop is a little bit trickier to test, since it
 # doesn't go into a loop if there are no watchers.
@@ -14,6 +15,7 @@ module EventedSpec
         reset
         delayed(0) do
           begin
+            run_hooks :coolio_before
             @example_group_instance.instance_eval(&@block)
           rescue Exception => e
             @spec_exception ||= e
@@ -43,6 +45,7 @@ module EventedSpec
 
       # Stops the loop and finalizes the example
       def finish_loop
+        run_hooks :coolio_after
         default_loop.stop
         finish_example
       end
@@ -77,21 +80,4 @@ module EventedSpec
       end
     end # class CoolioExample
   end # module SpecHelper
-end # module EventedSpec
-
-# Cool.io provides no means to change the default loop which makes sense in
-# most situations, but not ours.
-#
-# @private
-module Coolio
-  class Loop
-    # Sets cool.io default loop.
-    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
+end # module EventedSpec

data/lib/evented-spec/evented_example/em_example.rb

@@ -3,13 +3,6 @@ module EventedSpec
     # Represents spec running inside EM.run loop.
     # See {EventedExample} for details and method descriptions.
     class EMExample < EventedExample
-      # Runs hooks of specified type (hopefully, inside the event loop)
-      def run_em_hooks(type)
-        @example_group_instance.class.em_hooks[type].each do |hook|
-          @example_group_instance.instance_eval(&hook) #_with_rescue(&hook)
-        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
@@ -17,7 +10,7 @@ module EventedSpec
       def run_em_loop
         begin
           EM.run do
-            run_em_hooks :em_before
+            run_hooks :em_before
 
             @spec_exception = nil
             timeout(@opts[:spec_timeout]) if @opts[:spec_timeout]
@@ -32,7 +25,7 @@ module EventedSpec
         rescue Exception => e
           @spec_exception ||= e
           # p "Outside loop, caught #{@spec_exception.class.name}: #{@spec_exception}"
-          run_em_hooks :em_after # Event loop broken, but we still need to run em_after hooks
+          run_hooks :em_after # Event loop broken, but we still need to run em_after hooks
         ensure
           finish_example
         end
@@ -41,7 +34,7 @@ module EventedSpec
       # Stops EM event loop. It is called from #done
       #
       def finish_em_loop
-        run_em_hooks :em_after
+        run_hooks :em_after
         EM.stop_event_loop if EM.reactor_running?
       end
 
@@ -76,10 +69,11 @@ module EventedSpec
 
       # See {EventedExample#delayed}
       def delayed(delay, &block)
+        instance = self
         if delay
-          EM.add_timer delay, &block
+          EM.add_timer delay, Proc.new { instance.instance_eval(&block) }
         else
-          yield
+          instance.instance_eval(&block)
         end
       end # delayed
     end # class EMExample < EventedExample

data/lib/evented-spec/{amqp.rb → ext/amqp.rb}

@@ -1,8 +1,31 @@
 # Monkey patching some methods into AMQP to make it more testable
+module EventedSpec
+  module AMQPBackports
+    def self.included(base)
+      base.extend ClassMethods
+    end # self.included
+
+    module ClassMethods
+      def connection
+        @conn
+      end # connection
+
+      def connection=(new_connection)
+        @conn = new_connection
+      end # connection=
+    end # module ClassMethods
+  end # module AMQPBackports
+end # module EventedSpec
+
 module AMQP
   # Initializes new AMQP client/connection without starting another EM loop
   def self.start_connection(opts={}, &block)
-    self.connection = connect opts, &block
+    if amqp_pre_08?
+      self.connection = connect opts
+      self.connection.callback &block
+    else
+      self.connection = connect opts, &block
+    end
   end
 
   # Closes AMQP connection gracefully
@@ -24,4 +47,10 @@ module AMQP
     self.connection = nil
     @closing = false
   end
-end
+
+  def self.amqp_pre_08?
+    AMQP::VERSION < "0.8"
+  end # self.amqp_pre_08?
+
+  include EventedSpec::AMQPBackports
+end