rspec-eventmachine 0.1.0

data/README.md

@@ -0,0 +1,120 @@
+# RSpec::EventMachine
+
+This library provides some extensions to RSpec that make testing
+EventMachine-based applications easier. It includes functionality for running
+asynchronous code in tests, and for stubbing out the EventMachine timer methods.
+
+
+## Installation
+
+```
+$ gem install rspec-eventmachine
+```
+
+
+## Usage
+
+The library includes two main modules: `AsyncSteps` facilities the writing of
+tests with async logic, and `FakeClock` stubs out timer methods.
+
+
+### `AsyncSteps`
+
+To keep async tests clean, it helps to implement all the separate logical steps
+in them as separate functions. Using `AsyncSteps`, you write a module
+containing definitions of all your test steps, where each method takes a
+callback. You then mix this module into your tests, and you can use the methods
+without callbacks to write terse, flat tests.
+
+```rb
+require "rspec/em"
+
+MathSteps = RSpec::EM.async_steps do
+  def add(x, y, &callback)
+    EM.add_timer 0.1 do
+      @result = x + y
+      callback.call
+    end
+  end
+
+  def multiply(f, &callback)
+    EM.add_timer 0.2 do
+      @result = @result * f
+      callback.call
+    end
+  end
+
+  def check_result(n, &callback)
+    @result.should == n
+    callback.call
+  end
+end
+
+describe "Math" do
+  include MathSteps
+
+  it "adds and multiplies" do
+    add 3, 4
+    multiply 5
+    check_result 35
+  end
+end
+```
+
+Note that you must put all the logic in the async steps module. The method calls
+in your `before`, `after` and `it` blocks are really just adding the named
+methods and arguments to a queue, which `AsyncSteps` executes sequentially by
+calling each method when the previous one invokes its callback. `AsyncSteps`
+also makes sure that the reactor is running for the duration of each test, and
+catches and reports any errors or failures that happen during the test.
+
+
+### `FakeClock`
+
+The `FakeClock` module lets you freeze time and move it forward by hand, to test
+code that uses the EventMachine `add_timer` and `add_periodic_timer` methods.
+
+```rb
+require "rspec/em"
+
+describe "Math" do
+  include RSpec::EM::FakeClock
+
+  before { clock.stub }
+  after { clock.reset }
+
+  it "adds and multiplies" do
+    value = 0
+    EM.add_timer(1) { value += 3 }
+    EM.add_timer(3) { value *= 2 }
+
+    clock.tick(2)
+    value.should == 3
+    clock.tick(2)
+    value.should == 6
+  end
+end
+```
+
+
+## License
+
+Copyright (c) 2011-2013 James Coglan
+
+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/lib/rspec/em.rb

@@ -0,0 +1,2 @@
+require File.expand_path('../eventmachine', __FILE__)
+

data/lib/rspec/eventmachine.rb

@@ -0,0 +1,19 @@
+require 'eventmachine'
+require 'rspec/mocks'
+require 'set'
+
+module RSpec
+  module EventMachine
+    root = File.expand_path('../eventmachine', __FILE__)
+
+    autoload :AsyncSteps, root + '/async_steps'
+    autoload :FakeClock,  root + '/fake_clock'
+    
+    def self.async_steps(&block)
+      AsyncSteps.new(&block)
+    end
+  end
+
+  EM = EventMachine
+end
+

data/lib/rspec/eventmachine/async_steps.rb

@@ -0,0 +1,83 @@
+module RSpec::EM
+  class AsyncSteps < Module
+    
+    def included(klass)
+      klass.__send__(:include, Scheduler)
+    end
+    
+    def method_added(method_name)
+      async_method_name = "async_#{method_name}"
+
+      return if instance_methods(false).map { |m| m.to_s }.include?(async_method_name) or
+                method_name.to_s =~ /^async_/
+      
+      module_eval <<-RUBY
+        alias :#{async_method_name} :#{method_name}
+
+        def #{method_name}(*args)
+          __enqueue__([#{async_method_name.inspect}] + args)
+        end
+      RUBY
+    end
+    
+    module Scheduler
+      def __enqueue__(args)
+        @__step_queue__ ||= []
+        @__step_queue__ << args
+        return if @__running_steps__
+        @__running_steps__ = true
+        EventMachine.next_tick { __run_next_step__ }
+      end
+      
+      def __run_next_step__
+        step = @__step_queue__.shift
+        return EventMachine.stop unless step
+        
+        method_name, args = step.shift, step
+        begin
+          method(method_name).call(*args) { __run_next_step__ }
+        rescue Object => error
+          @example.set_exception(error) if @example
+          __end_steps__
+        end
+      end
+      
+      def __end_steps__
+        @__step_queue__ = []
+        __run_next_step__
+      end
+      
+      def verify_mocks_for_rspec
+        EventMachine.reactor_running? ? false : super
+      rescue Object => error
+        @example.set_exception(error) if @example
+      end
+      
+      def teardown_mocks_for_rspec
+        EventMachine.reactor_running? ? false : super
+      rescue Object => error
+        @example.set_exception(error) if @example
+      end
+    end
+    
+  end
+end
+
+class RSpec::Core::Example
+  hook_method = %w[with_around_hooks with_around_each_hooks].find { |m| instance_method(m) rescue nil }
+  
+  class_eval %Q{
+    alias :synchronous_run :#{hook_method}
+    
+    def #{hook_method}(*args, &block)
+      if @example_group_instance.is_a?(RSpec::EM::AsyncSteps::Scheduler)
+        EventMachine.run { synchronous_run(*args, &block) }
+        @example_group_instance.verify_mocks_for_rspec
+        @example_group_instance.teardown_mocks_for_rspec
+      else
+        synchronous_run(*args, &block)
+      end
+    end
+  }
+end
+

data/lib/rspec/eventmachine/fake_clock.rb

@@ -0,0 +1,106 @@
+module RSpec::EM
+  module FakeClock
+    
+    def clock
+      API
+    end
+    
+    module API
+      STUBBED_METHODS = [:add_timer, :add_periodic_timer, :cancel_timer]
+      
+      def self.stub
+        reset
+        STUBBED_METHODS.each do |method_name|
+          EventMachine.stub(method_name, &FakeClock.method(method_name))
+        end
+        Time.stub(:now, &FakeClock.method(:now))
+      end
+      
+      def self.reset
+        FakeClock.reset
+      end
+      
+      def self.tick(seconds)
+        FakeClock.tick(seconds)
+      end
+    end
+    
+    class Schedule < SortedSet
+      def next_scheduled_at(time)
+        find { |timeout| timeout.time <= time }
+      end
+    end
+    
+    class Timeout
+      include Comparable
+      
+      attr_accessor :time
+      attr_reader :block, :interval, :repeat
+      
+      def initialize(block, interval, repeat)
+        @block    = block
+        @interval = interval
+        @repeat   = repeat
+      end
+      
+      def <=>(other)
+        @time - other.time
+      end
+    end
+    
+    def self.now
+      @call_time
+    end
+    
+    def self.reset
+      @current_time = Time.now
+      @call_time    = @current_time
+      @schedule     = Schedule.new
+    end
+    
+    def self.tick(seconds)
+      @current_time += seconds
+      while timeout = @schedule.next_scheduled_at(@current_time)
+        run(timeout)
+      end
+      @call_time = @current_time
+    end
+    
+    def self.run(timeout)
+      @call_time = timeout.time
+      timeout.block.call
+      
+      if timeout.repeat
+        timeout.time += timeout.interval
+        @schedule = Schedule.new(@schedule)
+      else
+        clear_timeout(timeout)
+      end
+    end
+    
+    def self.timer(block, seconds, repeat)
+      timeout = Timeout.new(block, seconds, repeat)
+      timeout.time = @call_time + seconds
+      @schedule.add(timeout)
+      timeout
+    end
+    
+    def self.add_timer(seconds, proc = nil, &block)
+      timer(block || proc, seconds, false)
+    end
+    
+    def self.add_periodic_timer(seconds, proc = nil, &block)
+      timer(block || proc, seconds, true)
+    end
+    
+    def self.cancel_timer(timeout)
+      clear_timeout(timeout)
+    end
+    
+    def self.clear_timeout(timeout)
+      @schedule.delete(timeout)
+    end
+    
+  end
+end
+

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: rspec-eventmachine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- James Coglan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 
+email: jcoglan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/rspec/eventmachine.rb
+- lib/rspec/eventmachine/async_steps.rb
+- lib/rspec/eventmachine/fake_clock.rb
+- lib/rspec/em.rb
+homepage: http://github.com/jcoglan/rspec-eventmachine
+licenses:
+- MIT
+post_install_message: 
+rdoc_options:
+- --main
+- README.md
+- --markup
+- markdown
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: RSpec extensions for testing EventMachine code
+test_files: []