rspec-sidekiq 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47fe73bb71c8962a243f7128bffe68ce0ec5a4c644f1e1bb597723980af806b0
-  data.tar.gz: 0fdfbac81db581526c48fb58741e56eaee011507235538df4a48a66584477c74
+  metadata.gz: 829c5fcd191be48f662173034da4820f8dd5d405c85a865cc272048b1cee3b95
+  data.tar.gz: 07d430fa03b32c89f6d859c4fc44034ecc517d4eeec623d552854d5deaa142f4
 SHA512:
-  metadata.gz: 01a72c5aa64da2033f4efc53000fd52241d120d8c761dd095272b6111807d99ae50746428c5a222c670a8ff573b39a911faeb1a0b3e21b93bfedaa8068f60ec6
-  data.tar.gz: 6d052d8dd15a05a002cbc30a26e81aa61621cc9c8e8ec1789e4b6fdb7174cb74727c81baf9cdbf1727eed951f18b65397718800f90d5adfc067dc5a6d803844f
+  metadata.gz: c2a20b0ba6848989deea4759a0dfaec982c05f9543b60d42343d4b7d69e22e38f175596e53a00f911ad94732a9b6fca7904703f60b35bd014b00180d905b266a
+  data.tar.gz: bc0b993e2fe9350b2f72c8b5e7711b2c642a8098566edebfef5dd00b2f3a5aadef6a014de61831ff05a255376824e441076e29ff1ca0491f56e5fce98d52f57b

data/CHANGES.md

@@ -1,6 +1,15 @@
 Unreleased
 ---
 
+5.3.0
+---
+* Add `have_job` matcher and named queue stubs (`stub_named_queues`) (#279)
+* Add `have_job_option` and `have_job_options` matchers for job option assertions (#278)
+* Add `respond_to_missing?` to `NullBatch` for proper method reflection (#275)
+* Support RSpec matchers with `at` and `in` evaluators (#272)
+* Allow `on` to accept either a `String` or `Symbol` queue name (#273)
+* Avoid `require "sidekiq/testing"` deprecation on Sidekiq 8.1.1+ (#280)
+
 5.2.0
 ---
 * Add `never` matcher for aliasing `exactly(0)` (#256)

data/README.md

@@ -3,21 +3,26 @@
 
 Simple testing of Sidekiq jobs via a collection of matchers and helpers.
 
-[Jump to Matchers »](#matchers) | [Jump to Helpers »](#helpers)
+[Jump to Matchers »](#matchers) | [Jump to Helpers »](#helpers)
 
 ## Installation
+
 ```ruby
 # Gemfile
 group :test do
   gem 'rspec-sidekiq'
 end
 ```
-rspec-sidekiq requires ```sidekiq/testing``` by default so there is no need to include the line ```require "sidekiq/testing"``` inside your ```spec_helper.rb```.
 
-*IMPORTANT! This has the effect of not pushing enqueued jobs to Redis but to a ```job``` array to enable testing ([see the FAQ & Troubleshooting Wiki page][rspec_sidekiq_wiki_faq_&_troubleshooting]). Thus, only include ```gem "rspec-sidekiq"``` in environments where this behaviour is required, such as the ```test``` group.*
+rspec-sidekiq requires `sidekiq/testing` by default so there is no need to include the line `require "sidekiq/testing"` inside your `spec_helper.rb`.
+
+> [!IMPORTANT]
+> This has the effect of not pushing enqueued jobs to Redis but to a `job` array to enable testing ([see the FAQ & Troubleshooting Wiki page][rspec_sidekiq_wiki_faq_&_troubleshooting]). Thus, only include `gem "rspec-sidekiq"` in environments where this behaviour is required, such as the `test` group.*
 
 ## Configuration
-If you wish to modify the default behaviour, add the following to your ```spec_helper.rb``` file
+
+If you wish to modify the default behaviour, add the following to your `spec_helper.rb` file
+
 ```ruby
 RSpec::Sidekiq.configure do |config|
   # Clears all job queues before each example
@@ -32,16 +37,20 @@ end
 ```
 
 ## Matchers
-* [```enqueue_sidekiq_job```](#enqueue_sidekiq_job)
-* [```have_enqueued_sidekiq_job```](#have_enqueued_sidekiq_job)
-* [```be_processed_in```](#be_processed_in)
-* [```be_retryable```](#be_retryable)
-* [```save_backtrace```](#save_backtrace)
-* [```be_unique```](#be_unique)
-* [```be_expired_in```](#be_expired_in)
-* [```be_delayed``` (_deprecated_)](#be_delayed)
 
-### ```enqueue_sidekiq_job```
+* [`enqueue_sidekiq_job`](#enqueue_sidekiq_job)
+* [`have_enqueued_sidekiq_job`](#have_enqueued_sidekiq_job)
+* [`have_job`](#have_job)
+* [`have_job_option`](#have_job_option)
+* [`have_job_options`](#have_job_options)
+* [`be_processed_in`](#be_processed_in)
+* [`be_retryable`](#be_retryable)
+* [`save_backtrace`](#save_backtrace)
+* [`be_unique`](#be_unique)
+* [`be_expired_in`](#be_expired_in)
+* [`be_delayed` (_deprecated_)](#be_delayed)
+
+### `enqueue_sidekiq_job`
 
 *Describes that the block should enqueue a job*. Optionally specify the
 specific job class, arguments, timing, and other context
@@ -108,7 +117,7 @@ expect do
 end.to enqueue_sidekiq_job(AwesomeJob).and enqueue_sidekiq_job(OtherJob)
 ```
 
-### ```have_enqueued_sidekiq_job```
+### `have_enqueued_sidekiq_job`
 
 Describes that there should be an enqueued job (with the specified arguments):
 
@@ -120,6 +129,7 @@ expect(AwesomeJob).to have_enqueued_sidekiq_job('Awesome', true)
 ```
 
 You can use the built-in RSpec args matchers too:
+
 ```ruby
 AwesomeJob.perform_async({"something" => "Awesome", "extra" => "stuff"})
 
@@ -146,6 +156,7 @@ expect(AwesomeJob).to have_enqueued_sidekiq_job.at_most(:thrice)
 ```
 
 Likewise, specify what should be in the context:
+
 ```ruby
 AwesomeJob.set(trace_id: "something").perform_async
 
@@ -162,6 +173,7 @@ AwesomeJob.perform_at time, 'Awesome', true
 # test with...
 expect(AwesomeJob).to have_enqueued_sidekiq_job('Awesome', true).at(time)
 ```
+
 ```ruby
 AwesomeJob.perform_in 5.minutes, 'Awesome', true
 # test with...
@@ -212,8 +224,88 @@ expect(Sidekiq::Worker).to have_enqueued_sidekiq_job(
 )
 ```
 
-### ```be_processed_in```
+### `have_job`
+
+Describes that a Sidekiq set (ScheduledSet, RetrySet, DeadSet) should contain a job. Typically used together with [`stub_named_queues`](#stub_named_queues).
+
+```ruby
+# Match any job in the set
+expect(Sidekiq::ScheduledSet.new).to have_job
+
+# Match a specific job class
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob)
+
+# With specific arguments
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).with('arg')
+
+# A specific number of times
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).once
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).twice
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).exactly(3).times
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).at_least(1).time
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).at_most(2).times
+```
+
+#### Testing retry jobs
+
+```ruby
+expect(Sidekiq::RetrySet.new)
+  .to have_job(AwesomeJob)
+  .with('arg')
+  .with_error('something went wrong')
+  .with_error_class(RuntimeError)
+  .with_retry_count(2)
+```
+
+#### Testing dead jobs
+
+```ruby
+expect(Sidekiq::DeadSet.new)
+  .to have_job(AwesomeJob)
+  .with('arg')
+  .died_within(1.hour)
+```
+
+#### Scanning with a pattern
+
+Use `.scanning(pattern)` to filter by a glob-style pattern matched against the job's JSON representation:
+
+```ruby
+expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).scanning("*some_trace_id*")
+```
+
+### `have_job_option`
+
+Describes a single Sidekiq option set on a job class:
+
+```ruby
+class AwesomeJob
+  include Sidekiq::Job
+  sidekiq_options retry: 5, queue: 'critical', dead: false
+end
+
+expect(AwesomeJob).to have_job_option(:retry, 5)
+expect(AwesomeJob).to have_job_option(:queue, 'critical')
+expect(AwesomeJob).to have_job_option(:dead, false)
+```
+
+### `have_job_options`
+
+Describes multiple Sidekiq options set on a job class:
+
+```ruby
+class AwesomeJob
+  include Sidekiq::Job
+  sidekiq_options retry: 5, queue: 'critical', backtrace: true
+end
+
+expect(AwesomeJob).to have_job_options(retry: 5, queue: 'critical', backtrace: true)
+```
+
+### `be_processed_in`
+
 *Describes the queue that a job should be processed in*
+
 ```ruby
 sidekiq_options queue: :download
 # test with...
@@ -221,12 +313,14 @@ expect(AwesomeJob).to be_processed_in :download # or
 it { is_expected.to be_processed_in :download }
 ```
 
-### ```be_retryable```
+### `be_retryable`
+
 *Describes if a job should retry when there is a failure in its execution*
 
 Note: this only tests against the `retry` option in the job's Sidekiq options.
 To test an enqueued job's retry, i.e. `AwesomeJob.set(retry: 5)`, use
 `with_context`
+
 ```ruby
 sidekiq_options retry: 5
 # test with...
@@ -240,8 +334,10 @@ expect(AwesomeJob).to be_retryable false # or
 it { is_expected.to be_retryable false }
 ```
 
-### ```save_backtrace```
+### `save_backtrace`
+
 *Describes if a job should save the error backtrace when there is a failure in its execution*
+
 ```ruby
 sidekiq_options backtrace: 5
 # test with...
@@ -257,13 +353,15 @@ it { is_expected.to_not save_backtrace } # or
 it { is_expected.to save_backtrace false }
 ```
 
-### ```be_unique```
+### `be_unique`
 
-:warning: This is intended to for Sidekiq Enterprise unique job implementation.
-There is _limited_ support for Sidekiq Unique Jobs, but compatibility is not
-guaranteed.
+> [!CAUTION]
+> This is intended to for Sidekiq Enterprise unique job implementation.
+> There is _limited_ support for Sidekiq Unique Jobs, but compatibility is not
+> guaranteed.
 
 *Describes when a job should be unique within its queue*
+
 ```ruby
 sidekiq_options unique_for: 1.hour
 # test with...
@@ -277,16 +375,18 @@ it { is_expected.to be_unique.for(1.hour) }
 
 #### `until` sub-matcher
 
-:warning: This sub-matcher only works for Sidekiq Enterprise
+> [!CAUTION]
+> This sub-matcher only works for Sidekiq Enterprise
 
 ```ruby
 sidekiq_options unique_for: 1.hour, unique_until: :start
 it { is_expected.to be_unique.until(:start) }
 ```
 
+### `be_expired_in`
 
-### ```be_expired_in```
 *Describes when a job should expire*
+
 ```ruby
 sidekiq_options expires_in: 1.hour
 # test with...
@@ -294,13 +394,14 @@ it { is_expected.to be_expired_in 1.hour }
 it { is_expected.to_not be_expired_in 2.hours }
 ```
 
-### ```be_delayed```
+### `be_delayed`
 
 **This matcher is deprecated**. Use of it with Sidekiq 7+ will raise an error.
 Sidekiq 7 [dropped Delayed
 Extensions](https://github.com/sidekiq/sidekiq/issues/5076).
 
 *Describes a method that should be invoked asynchronously (See [Sidekiq Delayed Extensions][sidekiq_wiki_delayed_extensions])*
+
 ```ruby
 Object.delay.is_nil? # delay
 expect(Object.method :is_nil?).to be_delayed
@@ -323,6 +424,7 @@ expect(MyMailer.instance_method :some_mail).to be_delayed
 ```
 
 ## Example matcher usage
+
 ```ruby
 require 'spec_helper'
 
@@ -341,9 +443,56 @@ end
 ```
 
 ## Helpers
+
+* [`stub_named_queues`](#stub_named_queues)
 * [Batches (Sidekiq Pro) _experimental_](#batches)
 * [`within_sidekiq_retries_exhausted_block`](#within_sidekiq_retries_exhausted_block)
 
+### `stub_named_queues`
+
+If you need to test jobs in Sidekiq's named sets (ScheduledSet, RetrySet, DeadSet) without
+a Redis instance, opt-in with `stub_named_queues: true`. This replaces those sets with
+in-memory implementations backed by a `JobStore`.
+
+```ruby
+RSpec.describe "Scheduled jobs", stub_named_queues: true do
+  it "schedules a job" do
+    AwesomeJob.perform_at(1.hour.from_now, 'arg')
+
+    expect(Sidekiq::ScheduledSet.new).to have_job(AwesomeJob).with('arg')
+  end
+
+  it "tracks retry jobs via the job store" do
+    store = RSpec::Sidekiq::NamedQueues.job_store
+    store.add_retry(
+      "class" => "AwesomeJob",
+      "args" => ["arg"],
+      "error_message" => "boom",
+      "error_class" => "RuntimeError",
+      "retry_count" => 1
+    )
+
+    expect(Sidekiq::RetrySet.new)
+      .to have_job(AwesomeJob)
+      .with_error('boom')
+      .with_retry_count(1)
+  end
+
+  it "tracks dead jobs via the job store" do
+    store = RSpec::Sidekiq::NamedQueues.job_store
+    store.add_dead(
+      "class" => "AwesomeJob",
+      "args" => ["arg"],
+      "failed_at" => Time.now.to_f
+    )
+
+    expect(Sidekiq::DeadSet.new)
+      .to have_job(AwesomeJob)
+      .died_within(1.minute)
+  end
+end
+```
+
 ### Batches
 
 If you are using Sidekiq Batches ([Sidekiq Pro feature][sidekiq_wiki_batches]),
@@ -351,10 +500,10 @@ You can *opt-in* with `stub_batches` to make `rspec-sidekiq` mock the
 implementation (using a NullObject pattern). This enables testing without a
 Redis instance. Mocha and RSpec stubbing is supported here.
 
-:warning: **Caution**: Opting-in to this feature, while allowing you to test without
-having Redis, _does not_ provide the exact API that `Sidekiq::Batch` does. As
-such it can cause surprises.
-
+> [!CAUTION]
+> Opting-in to this feature, while allowing you to test without
+> having Redis, _does not_ provide the exact API that `Sidekiq::Batch` does. As
+> such it can cause surprises.
 
 ```ruby
 RSpec.describe "Using mocked batches", stub_batches: true do
@@ -375,6 +524,7 @@ end
 ```
 
 ### within_sidekiq_retries_exhausted_block
+
 ```ruby
 sidekiq_retries_exhausted do |msg|
   bar('hello')
@@ -386,11 +536,13 @@ FooClass.within_sidekiq_retries_exhausted_block {
 ```
 
 ## Testing
+
 ```
 bundle exec rspec
 ```
 
 ## Maintainers
+
 * [@wspurgin]
 * [@ydah]
 
@@ -400,18 +552,17 @@ bundle exec rspec
 * [@philostler]
 
 ## Contribute
+
 Please do! If there's a feature missing that you'd love to see then get in on the action!
 
 Issues/Pull Requests/Comments all welcome...
 
+[@packrat386]: https://github.com/packrat386
+[@philostler]: https://github.com/philostler
+[@wspurgin]: https://github.com/wspurgin
+[@ydah]: https://github.com/ydah
 [github_actions]: https://github.com/wspurgin/rspec-sidekiq/actions
 [github_actions_badge]: https://github.com/wspurgin/rspec-sidekiq/actions/workflows/main.yml/badge.svg
-
 [rspec_sidekiq_wiki_faq_&_troubleshooting]: https://github.com/wspurgin/rspec-sidekiq/wiki/FAQ-&-Troubleshooting
 [sidekiq_wiki_batches]: https://github.com/sidekiq/sidekiq/wiki/Batches
 [sidekiq_wiki_delayed_extensions]: https://github.com/sidekiq/sidekiq/wiki/Delayed-Extensions
-
-[@wspurgin]: https://github.com/wspurgin
-[@ydah]: https://github.com/ydah
-[@packrat386]: https://github.com/packrat386
-[@philostler]: https://github.com/philostler

data/lib/rspec/sidekiq/batch.rb

@@ -10,6 +10,10 @@ if defined? Sidekiq::Batch
         def method_missing(*args, &block)
           self
         end
+
+        def respond_to_missing?(*_args)
+          true
+        end
       end
 
       ##

data/lib/rspec/sidekiq/helpers/within_sidekiq_retries_exhausted_block.rb

@@ -4,6 +4,10 @@ module Sidekiq
   module Worker
     module ClassMethods
       def within_sidekiq_retries_exhausted_block(user_msg = {}, exception = default_retries_exhausted_exception, &block)
+        unless sidekiq_retries_exhausted_block
+          raise ArgumentError, 'Define `sidekiq_retries_exhausted` before calling `within_sidekiq_retries_exhausted_block`'
+        end
+
         block.call
         sidekiq_retries_exhausted_block.call(default_retries_exhausted_message.merge(user_msg), exception)
       end

data/lib/rspec/sidekiq/matchers/base.rb

@@ -3,6 +3,54 @@
 module RSpec
   module Sidekiq
     module Matchers
+      # @api private
+      module CountExpectation
+        private
+
+        def set_expected_count(relativity, n)
+          n =
+            case n
+            when Integer then n
+            when :once   then 1
+            when :twice  then 2
+            when :thrice then 3
+            else raise ArgumentError, "Unsupported #{n} in '#{relativity} #{n}'. Use either an Integer, :once, :twice, or :thrice."
+            end
+          @expected_count = [relativity, n]
+        end
+
+        def count_message
+          case expected_count[0]
+          when :positive
+            "a"
+          when :exactly
+            expected_count[1]
+          else
+            "#{expected_count[0].to_s.gsub('_', ' ')} #{expected_count[1]}"
+          end
+        end
+      end
+
+      # @api private
+      module ArgumentNormalization
+        private
+
+        def normalize_arguments(args)
+          case args
+          when Array
+            args.map { |x| normalize_arguments(x) }
+          when Hash
+            args.each_with_object({}) do |(key, value), hash|
+              hash[key.to_s] = normalize_arguments(value)
+            end
+          when Symbol
+            args.to_s
+          else
+            args
+          end
+        end
+      end
+
       # @api private
       class JobOptionParser
         attr_reader :job
@@ -19,6 +67,8 @@ module RSpec
 
         def at_evaluator(value)
           return value.nil? if job["at"].to_s.empty?
+          return value.matches?(Time.at(job["at"])) if value.respond_to?(:matches?)
+
           value == Time.at(job["at"]).to_i
         end
 
@@ -50,17 +100,19 @@ module RSpec
         end
 
         def unwrapped_arguments
-          args = job["args"]
-
-          return deserialized_active_job_args if active_job?
+          @unwrapped_arguments ||= begin
+            args = job["args"]
 
-          args
+            active_job? ? deserialized_active_job_args : args
+          end
         end
 
         private
 
         def active_job?
-          if RSpec::Sidekiq.configuration.sidekiq_gte_8?
+          return @active_job if defined?(@active_job)
+
+          @active_job = if RSpec::Sidekiq.configuration.sidekiq_gte_8?
             job["class"] == "Sidekiq::ActiveJob::Wrapper"
           else
             job["class"] == "ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper"
@@ -108,12 +160,30 @@ module RSpec
           @context ||= job.except("args")
         end
 
+        def matches_arguments?(expected_args)
+          job_arguments.matches?(expected_args)
+        end
+
+        def matches_options?(expected_options)
+          job_option_parser.matches?(expected_options)
+        end
+
         def ==(other)
           super(other) unless other.is_a?(EnqueuedJob)
 
           jid == other.jid
         end
         alias_method :eql?, :==
+
+        private
+
+        def job_arguments
+          @job_arguments ||= JobArguments.new(job)
+        end
+
+        def job_option_parser
+          @job_option_parser ||= JobOptionParser.new(self)
+        end
       end
 
       class EnqueuedJobs
@@ -159,15 +229,11 @@ module RSpec
         end
 
         def arguments_matches?(job, arguments)
-          job_arguments = JobArguments.new(job)
-
-          job_arguments.matches?(arguments)
+          job.matches_arguments?(arguments)
         end
 
         def options_matches?(job, options)
-          parser = JobOptionParser.new(job)
-
-          parser.matches?(options)
+          job.matches_options?(options)
         end
 
         def unwrap_jobs(jobs)
@@ -180,6 +246,8 @@ module RSpec
       class Base
         include RSpec::Mocks::ArgumentMatchers
         include RSpec::Matchers::Composable
+        include CountExpectation
+        include ArgumentNormalization
 
         attr_reader :expected_arguments, :expected_options, :klass, :actual_jobs, :expected_count
 
@@ -195,12 +263,12 @@ module RSpec
         end
 
         def at(timestamp)
-          @expected_options["at"] = timestamp.to_time.to_i
+          @expected_options["at"] = matcher?(timestamp) ? timestamp : timestamp.to_time.to_i
           self
         end
 
         def in(interval)
-          @expected_options["at"] = (Time.now.to_f + interval.to_f).to_i
+          @expected_options["at"] = matcher?(interval) ? interval : (Time.now.to_f + interval.to_f).to_i
           self
         end
 
@@ -210,7 +278,7 @@ module RSpec
         end
 
         def on(queue)
-          @expected_options["queue"] = queue
+          @expected_options["queue"] = normalize_arguments(queue)
           self
         end
 
@@ -274,18 +342,6 @@ module RSpec
           self
         end
 
-        def set_expected_count(relativity, n)
-          n =
-            case n
-            when Integer then n
-            when :once   then 1
-            when :twice  then 2
-            when :thrice then 3
-            else raise ArgumentError, "Unsupported #{n} in '#{relativity} #{n}'. Use either an Integer, :once, :twice, or :thrice."
-            end
-          @expected_count = [relativity, n]
-        end
-
         def description
           "#{common_message} with arguments #{expected_arguments}"
         end
@@ -332,17 +388,6 @@ module RSpec
           raise NotImplementedError
         end
 
-        def count_message
-          case expected_count[0]
-          when :positive
-            "a"
-          when :exactly
-            expected_count[1]
-          else
-            "#{expected_count[0].to_s.gsub('_', ' ')} #{expected_count[1]}"
-          end
-        end
-
         def failure_message_when_negated
           message = ["expected not to #{common_message} but enqueued #{actual_jobs.count}"]
           message << "  arguments: #{expected_arguments}" if expected_arguments.any?
@@ -354,18 +399,10 @@ module RSpec
           RSpec::Support::ObjectFormatter.format(thing)
         end
 
-        def normalize_arguments(args)
-          if args.is_a?(Array)
-            args.map{ |x| normalize_arguments(x) }
-          elsif args.is_a?(Hash)
-            args.each_with_object({}) do |(key, value), hash|
-              hash[key.to_s] = normalize_arguments(value)
-            end
-          elsif args.is_a?(Symbol)
-            args.to_s
-          else
-            args
-          end
+        private
+
+        def matcher?(object)
+          object.respond_to?(:matches?)
         end
       end
     end