evented-spec 0.4.0

data/.gitignore

@@ -0,0 +1,30 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+*.rbc
+*.class
+coverage
+config
+rdoc
+pkg
+log
+.idea
+.rvmrc
+.bundle
+Gemfile.lock
+
+## PROJECT::SPECIFIC
+spec/amqp.yml

data/HISTORY

@@ -0,0 +1,97 @@
+== 0.0.0 / 2010-10-13
+
+* Birthday!
+
+== 0.0.1 / 2010-10-13
+
+* Initial code import from EM-Spec and AMQPHelper
+
+== 0.0.2 / 2010-10-13
+
+* Minimal functionality implemented
+
+== 0.0.4 / 2010-10-14
+
+* Problems with default_options resolved
+
+== 0.1.0 / 2010-10-15
+
+* Monkeypatched start/stop_connection directly into AMQP
+
+== 0.1.2 / 2010-10-15
+
+* Cleanup in AMQP.cleanup
+
+== 0.1.3 / 2010-10-15
+
+* Make sure Thread.current[:mq] state is cleaned after each example
+
+== 0.1.7 / 2010-10-15
+
+* em interface improved for timeout arg
+
+== 0.1.11 / 2010-10-18
+
+* Optional delay added to done
+
+== 0.2.0 / 2010-10-28
+
+* Rspec 2 support added
+
+== 0.2.2 / 2010-10-31
+
+* Metadata in Rspec 1
+
+== 0.2.7 / 2010-11-04
+
+* Make AMQP.cleanup_state more thorough
+
+== 0.2.8 / 2010-11-15
+
+* syncronize method added for wrapping async calls
+
+== 0.2.9 / 2010-11-16
+
+* Fallback to a separate default timeout
+
+== 0.3.0 / 2010-11-16
+
+* Hooks em_before/em_after implemented
+
+== 0.3.1 / 2010-11-17
+
+* Documentation cleanup
+
+== 0.3.2 / 2010-11-23
+
+* EM hooks now working as they should - bugs fixed
+
+== 0.3.3 / 2010-11-24
+
+* Spec timeout refactored
+
+== 0.3.4 / 2010-11-26
+
+* amqp_before/after hooks added
+
+== 0.3.5 / 2011-01-07
+
+* Drop-in support for legacy em-spec based examples added
+
+== 0.3.6 / 2011-01-07
+
+* Changed Gemfile to avoid circular dependency on AMQP
+
+== 0.3.7 / 2011-01-07
+
+* Changed Gemspec to avoid circular dependency on AMQP
+
+== 0.3.8 / 2011-01-25
+
+* MRI 1.8.7 support added
+
+== 0.4.0 / 2011-03-13
+
+* Forked into evented-spec.
+* cool.io support
+* Using amqp 0.8.* API instead of 0.7.*

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Arvicco
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,162 @@
+h2. About evented-spec
+
+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.
+
+h2. Usage
+
+To get started with evented-spec you need to include one of the helper modules in your example groups, e.g.:
+
+bc. describe "eventmachine-based client" do
+  include EventedSpec::SpecHelper
+  it "should allow you to start a reactor" do
+    em do
+      EventMachine.reactor_running?.should be_true
+      done
+    end
+  end
+  context "nested contexts" do
+    it "don't require another include" do
+      em do
+        EventMachine.add_timer(0.1) { @timer_run = true }
+        done(0.3)
+      end
+      @timer_run.should be_true
+    end
+  end
+end
+
+Particular modules and methods are explained below.
+
+h3. #done
+
+We have no means to know when your work with reactor is finished, so whatever it is you need to call @done@ at some point. It optionally accepts a timeout and a block that is executed right before event reactor loop is stopped. If you don't call @done@, your specs are going to fail by timeout.
+
+h3. EventedSpec::SpecHelper
+
+@EventedSpec::SpecHelper@ is for semi-manual managing of reactor life-cycle. It includes three helpers: for EventMachine, Coolio and AMQP.
+
+@em@ stands for EventMachine. It takes a block, which is run after reactor starts.
+
+@amqp@ stands for AMQP. It takes a block, which is run after amqp connects with broker using given or default options.
+
+@coolio@ stands for cool.io. It takes a block, which is run after reactor starts.
+
+All three accept a hash of options. Look into method documentation to learn more.
+
+h3. EventedSpec::EMSpec, EventedSpec::AMQPSpec
+
+@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.
+
+Also note that every example group including @EMSpec@ or @AMQPSpec@ automatically includes @SpecHelper@.
+
+Example:
+
+bc. describe "eventmachine specs" do
+  include EventedSpec::EMSpec
+  it "should run in a reactor" do
+    EventMachine.reactor_running?.should be_true
+    done # don't forget to finish your specs properly!
+  end
+end
+
+
+h3. default_options, default_timeout
+
+You can also pass some default options to specs (like amqp settings), they're specific to domain you're using evented-spec in.
+
+@default_timeout@ sets time (in seconds) for specs to time out
+
+bc. describe "using default_timeout" do
+  include EventedSpec::SpecHelper
+  default_timeout 0.5
+  it "should prevent specs from hanging up" do
+    em do
+      1.should == 1 # this spec is going to fail with timeout error because #done is not called
+    end
+  end
+end
+
+
+h2. Hooks
+
+There are 4 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
+
+So, the order of hooks 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
+  amqp_before do
+    AMQP.connection.should_not be_nil
+  end
+  let(:data) { "Test string" }
+  it "should do something useful" do
+    AMQP::Channel.new do |channel, _|
+      exchange = channel.direct("amqp-test-exchange")
+      queue = channel.queue("amqp-test-queue").bind(exchange)
+      queue.subscribe do |hdr, msg|
+        hdr.should be_an AMQP::Header
+        msg.should == data
+        done { queue.unsubscribe; queue.delete }
+      end
+      EM.add_timer(0.2) do
+        exchange.publish data
+      end
+    end
+  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.
+
+For example, the following *will not* work:
+
+bc. describe "using amqp" do
+  include EventedSpec::AMQPSpec
+  it "should do something useful" do
+    channel = AMQP::Channel.new
+    sleep 0.2                     # voila, you're blocking the reactor
+    channel.should be_open        # no, it should not
+    done
+  end
+end
+
+What you *should* do instead is use callbacks:
+
+bc. describe "using amqp" do
+  include EventedSpec::AMQPSpec
+  it "should do something useful" do
+    AMQP::Channel.new do |channel, _|
+      channel.should be_open
+      done
+    end
+  end
+end
+
+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.
+
+h2. Links
+
+* "cool.io":http://coolio.github.com/
+* "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

data/Rakefile

@@ -0,0 +1,24 @@
+require 'pathname'
+NAME = 'amqp-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
+VERSION = CLASS_NAME::VERSION
+
+begin
+  require 'rake'
+rescue LoadError
+  require 'rubygems'
+  gem 'rake', '~> 0.8.3.1'
+  require 'rake'
+end
+
+# Load rakefile tasks
+Dir['tasks/*.rake'].sort.each { |file| load file }
+

data/VERSION

@@ -0,0 +1 @@
+0.4.0

data/lib/amqp-spec.rb

@@ -0,0 +1,5 @@
+puts <<-EOF
+DEPRECATION WARNING:
+Using require 'amqp-spec' is deprecated. Require 'evented-spec' instead.
+EOF
+require 'evented-spec'

data/lib/evented-spec.rb

@@ -0,0 +1,2 @@
+require 'evented-spec/version'
+require "evented-spec/rspec"

data/lib/evented-spec/amqp.rb

@@ -0,0 +1,27 @@
+# Monkey patching some methods into AMQP to make it more testable
+module AMQP
+  # Initializes new AMQP client/connection without starting another EM loop
+  def self.start_connection(opts={}, &block)
+    self.connection = connect opts, &block
+  end
+
+  # Closes AMQP connection gracefully
+  def self.stop_connection
+    if AMQP.connection and not AMQP.connection.closing?
+      @closing = true
+      self.connection.close {
+        yield if block_given?
+        self.connection = nil
+        cleanup_state
+      }
+    end
+  end
+
+  # Cleans up AMQP state after AMQP connection closes
+  def self.cleanup_state
+    Thread.list.each { |thread| thread[:mq] = nil }
+    Thread.list.each { |thread| thread[:mq_id] = nil }
+    self.connection = nil
+    @closing = false
+  end
+end

data/lib/evented-spec/evented_example.rb

@@ -0,0 +1,61 @@
+module EventedSpec
+  module SpecHelper
+    # Represents example running inside some type of event loop.
+    # You are not going to use or interact with this class and its descendants directly.
+    #
+    # @abstract
+    class EventedExample
+      # Default options to use with the examples
+      DEFAULT_OPTIONS = {
+        :spec_timeout => 1
+      }
+
+      # Create new evented example
+      def initialize(opts, example_group_instance, &block)
+        @opts, @example_group_instance, @block = DEFAULT_OPTIONS.merge(opts), example_group_instance, block
+      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.
+      #
+      # @abstract
+      def finish_example
+        raise @spec_exception if @spec_exception
+      end
+
+      # Run the example.
+      #
+      # @abstract
+      def run
+        raise NotImplementedError, "you should implement #run in #{self.class.name}"
+      end
+
+      # Sets timeout for currently running example
+      #
+      # @abstract
+      def timeout(spec_timeout)
+        raise NotImplementedError, "you should implement #timeout in #{self.class.name}"
+      end
+
+      # Breaks the event loop and finishes the spec.
+      #
+      # @abstract
+      def done(delay=nil, &block)
+        raise NotImplementedError, "you should implement #done method in #{self.class.name}"
+      end
+
+      # Override this method in your descendants
+      #
+      # @note delay may be nil, implying you need to execute the block immediately.
+      # @abstract
+      def delayed(delay = nil, &block)
+        raise NotImplementedError, "you should implement #delayed method in #{self.class.name}"
+      end # delayed(delay, &block)
+    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

@@ -0,0 +1,52 @@
+module EventedSpec
+  module SpecHelper
+    # Represents spec running inside AMQP.start loop
+    # See {EventedExample} for details and method descriptions.
+    class AMQPExample < EMExample
+      # Run @block inside the AMQP.start loop.
+      # See {EventedExample#run}
+      def run
+        run_em_loop do
+          AMQP.start_connection(@opts) do
+            run_em_hooks :amqp_before
+            @example_group_instance.instance_eval(&@block)
+          end
+        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.
+      #
+      # See {EventedExample#done}
+      def done(delay = nil)
+        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
+                # Cannot call finish_em_loop before connection is marked as closed
+                # This callback is called before that happens.
+                EM.next_tick { finish_em_loop }
+              end
+            else
+              # Need this branch because if AMQP couldn't connect,
+              # the callback would never trigger
+              AMQP.cleanup_state
+              EM.next_tick { 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.
+      #
+      # See {EventedExample#run}
+      def finish_example
+        AMQP.cleanup_state
+        super
+      end
+    end # class AMQPExample < EventedExample
+  end # module SpecHelper
+end # module EventedExample