wireframe-resque_unit 0.4.1.1

data/README.md

@@ -0,0 +1,130 @@
+ResqueUnit
+==========
+
+ResqueUnit provides some extra assertions and a mock Resque for
+testing Rails code that depends on Resque. You can install it as
+either a gem or a plugin:
+
+    gem install resque_unit
+
+and in your test.rb: 
+
+    config.gem 'resque_unit'
+
+If you'd rather install it as a plugin, you should be able to run
+
+    script/plugin install git://github.com/justinweiss/resque_unit.git
+
+inside your Rails projects. 
+
+Examples
+========
+
+ResqueUnit provides some extra assertions for your unit tests. For
+example, if you have code that queues a resque job:
+
+    class MyJob
+      @queue = :low  
+    
+      def self.perform(x)
+        # do stuff
+      end
+    end
+    
+    def queue_job
+      Resque.enqueue(MyJob, 1)
+    end
+
+You can write a unit test for code that queues this job:
+
+    def test_job_queued
+      queue_job
+      assert_queued(MyJob) # assert that MyJob was queued in the :low queue
+    end
+
+You can also verify that a job was queued with arguments:
+
+    def test_job_queued_with_arguments
+      queue_job
+      assert_queued(MyJob, [1])
+    end
+
+And you can run all the jobs in the queue, so you can verify that they
+run correctly:
+
+    def test_job_runs 
+      queue_job 
+      Resque.run!
+      assert stuff_was_done, "Job didn't run"
+    end
+
+You can also access the queues directly:
+
+    def test_jobs_in_queue
+      queue_job 
+      assert_equal 1, Resque.queue(:low).length
+    end
+
+Finally, you can enable hooks:
+
+    Resque.enable_hooks!
+
+    class MyJobWithHooks
+      @queue = :hooked
+
+      def self.perform(x)
+        # do stuff
+      end
+
+      def self.after_enqueue_mark(*args)
+        # called when the job is enqueued
+      end
+
+      def self.before_perform_mark(*args)
+        # called just before the +perform+ method
+      end
+
+      def self.after_perform_mark(*args)
+        # called just after the +perform+ method
+      end
+
+      def self.failure_perform_mark(*args)
+        # called if the +perform+ method raised
+      end
+
+    end
+
+    def queue_job
+      Resque.enqueue(MyJobWithHooks, 1)
+    end
+
+Caveats
+=======
+
+* You should make sure that you call `Resque.reset!` in your test's
+  setup method to clear all of the test queues.
+* Hooks support is optional. Just because you probably don't want to call
+  them during unit tests if they play with a DB. Call `Resque.enable_hooks!`
+  in your tests's setup method to enable hooks. To disable hooks, call
+  `Resque.disable_hooks!`.
+
+Resque-Scheduler Support
+========================
+
+By calling `require 'resque_unit_scheduler'`, ResqueUnit will provide
+mocks for [resque-scheduler's](http://github.com/bvandenbos/resque-scheduler)
+`enqueue_at` and `enqueue_in` methods, along with a few extra
+assertions. These are used like this:
+
+    Resque.enqueue_in(600, MediumPriorityJob) # enqueues MediumPriorityJob in 600 seconds
+    assert_queued_in(600, MediumPriorityJob) # will pass
+    assert_not_queued_in(300, MediumPriorityJob) # will also pass
+
+    Resque.enqueue_at(Time.now + 10, MediumPriorityJob) # enqueues MediumPriorityJob at 10 seconds from now
+    assert_queued_at(Time.now + 10, MediumPriorityJob) # will pass
+    assert_not_queued_at(Time.now + 1, MediumPriorityJob) # will also pass
+
+For now, `assert_queued` and `assert_not_queued` will pass for any
+scheduled job. `Resque.run!` will run all scheduled jobs as well.
+
+Copyright (c) 2010 Justin Weiss, released under the MIT license

data/lib/resque_unit.rb

@@ -0,0 +1,13 @@
+module ResqueUnit
+end
+
+begin
+  require 'yajl'
+rescue LoadError
+  require 'json'
+end
+
+require 'resque_unit/helpers'
+require 'resque_unit/resque'
+require 'resque_unit/errors'
+require 'resque_unit/plugin'

data/lib/resque_unit/assertions.rb

@@ -0,0 +1,81 @@
+# These are a group of assertions you can use in your unit tests to
+# verify that your code is using Resque correctly.
+module ResqueUnit::Assertions
+  
+  # Asserts that +klass+ has been queued into its appropriate queue at
+  # least once. If +args+ is nil, it only asserts that the klass has
+  # been queued. Otherwise, it asserts that the klass has been queued
+  # with the correct arguments. Pass an empty array for +args+ if you
+  # want to assert that klass has been queued without arguments. Pass a block
+  # if you want to assert something was queued within its execution.
+  def assert_queued(klass, args = nil, message = nil, &block)
+    queue_name = Resque.queue_for(klass)
+    assert_job_created(queue_name, klass, args, message, &block)
+  end
+  alias assert_queues assert_queued
+
+  # The opposite of +assert_queued+.
+  def assert_not_queued(klass = nil, args = nil, message = nil, &block)
+    queue_name = Resque.queue_for(klass)
+
+    queue = if block_given?
+      snapshot = Resque.size(queue_name)
+      yield
+      Resque.all(queue_name)[snapshot..-1]
+    else
+      Resque.all(queue_name)
+    end
+
+    assert_with_custom_message(!in_queue?(queue, klass, args),
+      message || "#{klass}#{args ? " with #{args.inspect}" : ""} should not have been queued in #{queue_name}.")
+  end
+
+  # Asserts no jobs were queued within the block passed.
+  def assert_nothing_queued(message = nil, &block)
+    snapshot = Resque.size
+    yield
+    present = Resque.size
+    assert_equal snapshot, present, message || "No jobs should have been queued"
+  end
+
+  # Asserts that a job was created and queued into the specified queue
+  def assert_job_created(queue_name, klass, args = nil, message = nil, &block)
+    queue = if block_given?
+      snapshot = Resque.size(queue_name)
+      yield
+      Resque.all(queue_name)[snapshot..-1]
+    else
+      Resque.all(queue_name)
+    end
+
+    assert_with_custom_message(in_queue?(queue, klass, args),
+      message || "#{klass}#{args ? " with #{args.inspect}" : ""} should have been queued in #{queue_name}: #{queue.inspect}.")
+  end
+
+  private
+
+  # In Test::Unit, +assert_block+ displays only the message on a test
+  # failure and +assert+ always appends a message to the end of the
+  # passed-in assertion message. In MiniTest, it's the other way
+  # around. This abstracts those differences and never appends a
+  # message to the one the user passed in.
+  def assert_with_custom_message(value, message = nil)
+    if defined?(MiniTest::Assertions)
+      assert value, message
+    else
+      assert_block message do
+        value
+      end
+    end
+  end
+  
+  def in_queue?(queue, klass, args = nil)
+    !matching_jobs(queue, klass, args).empty?
+  end
+
+  def matching_jobs(queue, klass, args = nil)
+    normalized_args = Resque.decode(Resque.encode(args)) if args
+    queue.select {|e| e["class"] == klass.to_s && (!args || e["args"] == normalized_args )}
+  end
+
+end

data/lib/resque_unit/errors.rb

@@ -0,0 +1,17 @@
+# Re-define errors in from Resque, in case the 'resque' gem was not loaded.
+module Resque
+  # Raised whenever we need a queue but none is provided.
+  unless defined?(NoQueueError)
+    class NoQueueError < RuntimeError; end
+  end
+
+  # Raised when trying to create a job without a class
+  unless defined?(NoClassError)
+    class NoClassError < RuntimeError; end
+  end
+  
+  # Raised when a worker was killed while processing a job.
+  unless defined?(DirtyExit)
+    class DirtyExit < RuntimeError; end
+  end
+end

data/lib/resque_unit/helpers.rb

@@ -0,0 +1,57 @@
+module Resque
+  module Helpers
+    # Given a Ruby object, returns a string suitable for storage in a
+    # queue.
+    def encode(object)
+      if defined? Yajl
+        Yajl::Encoder.encode(object)
+      else
+        object.to_json
+      end
+    end
+
+    # Given a string, returns a Ruby object.
+    def decode(object)
+      return unless object
+      
+      if defined? Yajl
+        begin
+          Yajl::Parser.parse(object, :check_utf8 => false)
+        rescue Yajl::ParseError
+        end
+      else
+        begin
+          JSON.parse(object)
+        rescue JSON::ParserError
+        end
+      end
+    end
+
+    # Given a word with dashes, returns a camel cased version of it.
+    #
+    # classify('job-name') # => 'JobName'
+    def classify(dashed_word)
+      dashed_word.split('-').each { |part| part[0] = part[0].chr.upcase }.join
+    end
+
+    # Given a camel cased word, returns the constant it represents
+    #
+    # constantize('JobName') # => JobName
+    def constantize(camel_cased_word)
+      camel_cased_word = camel_cased_word.to_s
+
+      if camel_cased_word.include?('-')
+        camel_cased_word = classify(camel_cased_word)
+      end
+
+      names = camel_cased_word.split('::')
+      names.shift if names.empty? || names.first.empty?
+
+      constant = Object
+      names.each do |name|
+        constant = constant.const_get(name) || constant.const_missing(name)
+      end
+      constant
+    end
+  end
+end

data/lib/resque_unit/plugin.rb

@@ -0,0 +1,70 @@
+# A copy of the original Resque:Plugin class from the "resque" gem
+# No need to redefine this class if the resque gem was already loaded
+unless defined?(Resque::Plugin)
+
+  module Resque
+    module Plugin
+      extend self
+
+      LintError = Class.new(RuntimeError)
+
+      # Ensure that your plugin conforms to good hook naming conventions.
+      #
+      #   Resque::Plugin.lint(MyResquePlugin)
+      def lint(plugin)
+        hooks = before_hooks(plugin) + around_hooks(plugin) + after_hooks(plugin)
+
+        hooks.each do |hook|
+          if hook =~ /perform$/
+            raise LintError, "#{plugin}.#{hook} is not namespaced"
+          end
+        end
+
+        failure_hooks(plugin).each do |hook|
+          if hook =~ /failure$/
+            raise LintError, "#{plugin}.#{hook} is not namespaced"
+          end
+        end
+      end
+
+      # Given an object, returns a list `before_perform` hook names.
+      def before_hooks(job)
+        job.methods.grep(/^before_perform/).sort
+      end
+
+      # Given an object, returns a list `around_perform` hook names.
+      def around_hooks(job)
+        job.methods.grep(/^around_perform/).sort
+      end
+
+      # Given an object, returns a list `after_perform` hook names.
+      def after_hooks(job)
+        job.methods.grep(/^after_perform/).sort
+      end
+
+      # Given an object, returns a list `on_failure` hook names.
+      def failure_hooks(job)
+        job.methods.grep(/^on_failure/).sort
+      end
+
+      # Given an object, returns a list `after_enqueue` hook names.
+      def after_enqueue_hooks(job)
+        job.methods.grep(/^after_enqueue/).sort
+      end
+
+      # Given an object, returns a list `before_enqueue` hook names.
+      def before_enqueue_hooks(job)
+        job.methods.grep(/^before_enqueue/).sort
+      end
+    end
+  end
+
+end
+
+unless defined?(Resque::Job::DontPerform)
+  module Resque
+    class Job
+      DontPerform = Class.new(StandardError)
+    end
+  end
+end

data/lib/resque_unit/resque.rb

@@ -0,0 +1,224 @@
+# The fake Resque class. This needs to be loaded after the real Resque
+# for the assertions in +ResqueUnit::Assertions+ to work.
+module Resque
+  include Helpers
+  extend self
+
+  # Resets all the queues to the empty state. This should be called in
+  # your test's +setup+ method until I can figure out a way for it to
+  # automatically be called.
+  #
+  # If <tt>queue_name</tt> is given, then resets only that queue.
+  def reset!(queue_name = nil)
+    if @queue && queue_name
+      @queue[queue_name] = []
+    else
+      @queue = Hash.new { |h, k| h[k] = [] }
+    end
+  end
+
+  # Returns a hash of all the queue names and jobs that have been queued. The
+  # format is <tt>{queue_name => [job, ..]}</tt>.
+  def self.queues
+    @queue || reset!
+  end
+
+  # Returns an array of all the jobs that have been queued. Each
+  # element is of the form +{"class" => klass, "args" => args}+ where
+  # +klass+ is the job's class and +args+ is an array of the arguments
+  # passed to the job.
+  def queue(queue_name)
+    queues[queue_name]
+  end
+
+  # Return an array of all jobs' payloads for queue
+  # Elements are decoded
+  def all(queue_name)
+    result = list_range(queue_name, 0, size(queue_name))
+    result.is_a?(Array) ? result : [ result ]
+  end
+
+  # Returns an array of jobs' payloads for queue.
+  #
+  # start and count should be integer and can be used for pagination.
+  # start is the item to begin, count is how many items to return.
+  #
+  # To get the 3rd page of a 30 item, paginatied list one would use:
+  #   Resque.peek('my_list', 59, 30)
+  def peek(queue_name, start = 0, count = 1)
+    list_range(queue_name, start, count)
+  end
+
+  # Gets a range of jobs' payloads from queue.
+  # Returns single element if count equal 1
+  # Elements are decoded
+  def list_range(key, start = 0, count = 1)
+    data = if count == 1
+      decode(queues[key][start])
+    else
+      (queues[key][start...start + count] || []).map { |entry| decode(entry) }
+    end
+  end
+
+  # Yes, all Resque hooks!
+  def enable_hooks!
+    @hooks_enabled = true
+  end
+
+  def disable_hooks!
+    @hooks_enabled = nil
+  end
+
+  # Executes all jobs in all queues in an undefined order.
+  def run!
+    payloads = []
+    @queue.each do |queue_name, queue|
+      payloads.concat queue.slice!(0, queue.size)
+    end
+    exec_payloads payloads.shuffle
+  end
+
+  def run_for!(queue_name, limit=false)
+    queue = @queue[queue_name]
+    exec_payloads queue.slice!(0, ( limit ? limit : queue.size) ).shuffle
+  end
+
+  def exec_payloads(raw_payloads)
+    raw_payloads.each do |raw_payload|
+      job_payload = decode(raw_payload)
+      @hooks_enabled ? perform_with_hooks(job_payload) : perform_without_hooks(job_payload)
+    end
+  end
+  private :exec_payloads
+
+  # 1. Execute all jobs in all queues in an undefined order,
+  # 2. Check if new jobs were announced, and execute them.
+  # 3. Repeat 3
+  def full_run!
+    run! until empty_queues?
+  end
+
+  # Returns the size of the given queue
+  def size(queue_name = nil)
+    if queue_name
+      queues[queue_name].length
+    else
+      queues.values.flatten.length
+    end
+  end
+
+  # :nodoc: 
+  def enqueue(klass, *args)
+    enqueue_to( queue_for(klass), klass, *args)
+  end
+
+  # :nodoc:
+  def enqueue_to( queue_name, klass, *args )
+    # Behaves like Resque, raise if no queue was specifed
+    raise NoQueueError.new("Jobs must be placed onto a queue.") unless queue_name
+    enqueue_unit(queue_name, {"class" => klass.name, "args" => args })
+  end
+
+  # :nodoc: 
+  def queue_for(klass)
+    klass.instance_variable_get(:@queue) || (klass.respond_to?(:queue) && klass.queue)
+  end
+  alias :queue_from_class :queue_for
+
+  # :nodoc:
+  def empty_queues?
+    queues.all? do |k, v|
+      v.empty?
+    end
+  end
+
+  def enqueue_unit(queue_name, hash)
+    klass = constantize(hash["class"])
+    if @hooks_enabled
+      before_hooks = Plugin.before_enqueue_hooks(klass).map do |hook|
+        klass.send(hook, *hash["args"])
+      end
+      return nil if before_hooks.any? { |result| result == false }
+    end
+    queue(queue_name) << encode(hash)
+    if @hooks_enabled
+      Plugin.after_enqueue_hooks(klass).each do |hook|
+        klass.send(hook, *hash["args"])
+      end
+    end
+    queue(queue_name).size
+  end
+
+  # Call perform on the job class
+  def perform_without_hooks(job_payload)
+    constantize(job_payload["class"]).perform(*job_payload["args"])
+  end
+
+  # Call perform on the job class, and adds support for Resque hooks.
+  def perform_with_hooks(job_payload)
+    job_class = constantize(job_payload["class"])
+    before_hooks  = Resque::Plugin.before_hooks(job_class)
+    around_hooks  = Resque::Plugin.around_hooks(job_class)
+    after_hooks   = Resque::Plugin.after_hooks(job_class)
+    failure_hooks = Resque::Plugin.failure_hooks(job_class)
+    
+    begin
+      # Execute before_perform hook. Abort the job gracefully if
+      # Resque::DontPerform is raised.
+      begin
+        before_hooks.each do |hook|
+          job_class.send(hook, *job_payload["args"])
+        end
+      rescue Resque::Job::DontPerform
+        return false
+      end
+      
+      # Execute the job. Do it in an around_perform hook if available.
+      if around_hooks.empty?
+        perform_without_hooks(job_payload)
+        job_was_performed = true
+      else
+        # We want to nest all around_perform plugins, with the last one
+        # finally calling perform
+        stack = around_hooks.reverse.inject(nil) do |last_hook, hook|
+          if last_hook
+            lambda do
+              job_class.send(hook, *job_payload["args"]) { last_hook.call }
+            end
+          else
+            lambda do
+              job_class.send(hook, *job_payload["args"]) do
+                result = perform_without_hooks(job_payload)
+                job_was_performed = true
+                result
+              end
+            end
+          end
+        end
+        stack.call
+      end
+      
+      # Execute after_perform hook
+      after_hooks.each do |hook|
+        job_class.send(hook, *job_payload["args"])
+      end
+      
+      # Return true if the job was performed
+      return job_was_performed
+      
+    # If an exception occurs during the job execution, look for an
+    # on_failure hook then re-raise.
+    rescue Object => e
+      failure_hooks.each { |hook| job_class.send(hook, e, *job_payload["args"]) }
+      raise e
+    end
+  end
+
+  class Job
+    extend Helpers
+    def self.create(queue, klass_name, *args)
+      Resque.enqueue_unit(queue, {"class" => constantize(klass_name), "args" => args})
+    end
+  end
+
+end