rspec-sidekiq 3.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9521e2acad8dae8dc1c47afeb1a3f4f1052f44d2d512ae29866548f5cefdbb61
-  data.tar.gz: 4ce5c1b0a18cec884a1b023ae113f3e692afcc471c9e2dd067c762d6051a77d5
+  metadata.gz: fb94abca8e805aa88d9c84deb0ddb22746542845b48cde790c4da9ae58f48ca0
+  data.tar.gz: 646f1ee2cc023cd988f29b50250c6794cb7563a78c35a397f1f3290cbf9df97b
 SHA512:
-  metadata.gz: e3501020bc4f14f5294b1cb67483c3018f608111e4c50ec74c193927e0dadf41ad7532e5c2a695f7d107cd435094eb59751ab23743f6b97a316059f8cc77ba7f
-  data.tar.gz: 79003f53fa67a71b288a2de8d35bdc65aeb123e5dedf929e8012cff2e999aadaa5f3830d9d4dc33889ff4a270adbf9b1045a81e0b7372882b577e8d9553e8e9c
+  metadata.gz: 0d0b4a026d3e28f55e03076023b83eb11334cd2759514837f0fd37ce74d01279bf0aa53236e84185eb89e949ad429f21c40e09d1858c5a0beb622f5001617311
+  data.tar.gz: 42c83b796648b68262a689f6fabe441719347e9464505ca4ade74ebab9cad748e51896af223b441adda74fe9b6300cb9ecb1f1974843fa45cf225dcbefc996ca

data/CHANGES.md

@@ -1,3 +1,22 @@
+4.0.0
+---
+* [BREAKING] Dropped support for matching jobs on ActiveJob's private API args, (e.g. `_aj_globalid` and `_aj_ruby2_keywords`). `_aj_globalid` can be replaced with the object itself, e.g. `have_enqueued_sidekiq_job(user)`.
+* [BREAKING] Dropped support for Ruby 2.6
+* [BREAKING] Mocking Sidekiq::Batch is now _opt in_ (was opt-out) by default
+* [BREAKING] Dropped the `have_enqueued_job` matcher (deprecated since v3)
+* [BREAKING] Dropped support for Sidekiq <5
+* [BREAKING] Dropped support for Rails 5
+* Add support for Sidekiq 7 (#192)
+* Add support for builtin argument matchers from rspec mocks for
+  `have_enqueued_sidekiq_job` (#200)
+* Add `#on` to `have_enqueued_sidekiq_job` to support testing queue at enqueue time (#197)
+* Add `enqueue_sidekiq_job` for block-syntax style expectations
+* Clarified `have_enqueued_sidekiq_job` error message to make it clear that the "actual arguments" list is an array of argument-lists across all enqueued jobs. (#195)
+* Fix `in` and `at` evaluation to match Sidekiq (#194)
+* Fix `be_delayed` argument matcher (#196)
+* Fix argument matching ignoring order (#200)
+* Fix `be_delayed` time math when using `delay_for` (#198)
+
 3.1.0
 ---
 * Add support for latest ruby and Rails 5 (coding-bunny #156)

data/LICENSE

@@ -1,5 +1,17 @@
 The MIT License (MIT)
 
+Copyright (c) 2023 Will Spurgin
+
+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.
+
+Elements of this software and associated documentation files are covered by the following license:
+
+The MIT License (MIT)
+
 Copyright (c) 2014, 2015 Phil Ostler
 
 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:

data/README.md

@@ -1,23 +1,9 @@
-**Welcome @packrat386 as new maintainer for `rspec-sidekiq`!**
-
-# RSpec for Sidekiq
+**Welcome @wspurgin as new maintainer for `rspec-sidekiq`!**
 
 [![RubyGems][gem_version_badge]][ruby_gems]
-[![Code Climate][code_climate_badge]][code_climate]
-[![Travis CI][travis_ci_badge]][travis_ci]
-[![Coveralls][coveralls_badge]][coveralls]
-[![Gemnasium][gemnasium_badge]][gemnasium]
-
-***Simple testing of Sidekiq jobs via a collection of matchers and helpers***
-
-[RubyGems][ruby_gems] |
-[Code Climate][code_climate] |
-[GitHub][github] |
-[Travis CI][travis_ci] |
-[Coveralls][coveralls] |
-[Gemnasium][gemnasium] |
-[RubyDoc][ruby_doc] |
-[Ruby Toolbox][ruby_toolbox]
+[![Github Actions CI][github_actions_badge]][github_actions]
+
+Simple testing of Sidekiq jobs via a collection of matchers and helpers.
 
 [Jump to Matchers »](#matchers) | [Jump to Helpers »](#helpers)
 
@@ -48,33 +34,143 @@ end
 ```
 
 ## Matchers
-* [be_delayed](#be_delayed)
+* [enqueue_sidekiq_job](#enqueue_sidekiq_job)
+* [have_enqueued_sidekiq_job](#have_enqueued_sidekiq_job)
 * [be_processed_in](#be_processed_in)
 * [be_retryable](#be_retryable)
 * [be_unique](#be_unique)
-* [have_enqueued_sidekiq_job](#have_enqueued_sidekiq_job)
+* [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
 
-### be_delayed
-*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
-Object.delay.is_a? Object # delay with argument
-expect(Object.method :is_a?).to be_delayed(Object)
+# Basic
+expect { AwesomeJob.perform_async }.to enqueue_sidekiq_job
 
-Object.delay_for(1.hour).is_nil? # delay for
-expect(Object.method :is_nil?).to be_delayed.for 1.hour
-Object.delay_for(1.hour).is_a? Object # delay for with argument
-expect(Object.method :is_a?).to be_delayed(Object).for 1.hour
+# A specific job class
+expect { AwesomeJob.perform_async }.to enqueue_sidekiq_job(AwesomeJob)
 
-Object.delay_until(1.hour.from_now).is_nil? # delay until
-expect(Object.method :is_nil?).to be_delayed.until 1.hour.from_now
-Object.delay_until(1.hour.from_now).is_a? Object # delay until with argument
-expect(Object.method :is_a?).to be_delayed(Object).until 1.hour.from_now
+# with specific arguments
+expect { AwesomeJob.perform_async "Awesome!" }.to enqueue_sidekiq_job.with("Awesome!")
 
-#Rails Mailer
-MyMailer.delay.some_mail
-expect(MyMailer.instance_method :some_mail).to be_delayed
+# On a specific queue
+expect { AwesomeJob.set(queue: "high").perform_async }.to enqueue_sidekiq_job.on("high")
+
+# At a specific datetime
+specific_time = 1.hour.from_now
+expect { AwesomeJob.perform_at(specific_time) }.to enqueue_sidekiq_job.at(specific_time)
+
+# In a specific interval (be mindful of freezing or managing time here)
+freeze_time do
+  expect { AwesomeJob.perform_in(1.hour) }.to enqueue_sidekiq_job.in(1.hour)
+end
+
+# Combine and chain them as desired
+expect { AwesomeJob.perform_at(specific_time, "Awesome!") }.to(
+  enqueue_sidekiq_job(AwesomeJob)
+  .with("Awesome!")
+  .on("default")
+  .at(specific_time)
+)
+```
+
+### have_enqueued_sidekiq_job
+*Describes that there should be an enqueued job with the **specified
+arguments***
+
+```ruby
+AwesomeJob.perform_async 'Awesome', true
+# test with...
+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"})
+
+# using built-in matchers from rspec-mocks:
+expect(AwesomeJob).to have_enqueued_sidekiq_job(hash_including("something" => "Awesome"))
+expect(AwesomeJob).to have_enqueued_sidekiq_job(any_args)
+expect(AwesomeJob).to have_enqueued_sidekiq_job(hash_excluding("bad_stuff" => anything))
+```
+
+#### Testing scheduled jobs
+
+*Use chainable matchers `#at` and `#in`*
+
+```ruby
+time = 5.minutes.from_now
+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...
+expect(AwesomeJob).to have_enqueued_sidekiq_job('Awesome', true).in(5.minutes)
+```
+
+#### Testing queue set for job
+
+Use the chainable `#on` matcher
+
+```ruby
+class AwesomeJob
+  include Sidekiq::Job
+
+  sidekiq_options queue: :low
+end
+
+AwesomeJob.perform_async("a little awesome")
+
+# test with..
+expect(AwesomeJob).to have_enqueued_sidekiq_job("a little awesome").on("low")
+
+# Setting the queue when enqueuing
+AwesomeJob.set(queue: "high").perform_async("Very Awesome!")
+
+expect(AwesomeJob).to have_enqueued_sidekiq_job("Very Awesome!").on("high")
+```
+
+#### Testing ActiveMailer jobs
+
+```ruby
+user = User.first
+AwesomeActionMailer.invite(user, true).deliver_later
+
+expect(Sidekiq::Worker).to have_enqueued_sidekiq_job(
+  "AwesomeActionMailer",
+  "invite",
+  "deliver_now",
+  user,
+  true
+)
+```
+
+#### Testing a job is _not_ enqueued
+
+The negative case for `have_enqueued_sidekiq_job` is provided, but it's
+important to remember that `have_enqueued_sidekiq_job` is an expectation that a
+job is enqueued _with specific arguments_. In other words, passing no arguments
+to `have_enqueued_sidekiq_job` is implicitly telling the matcher to look for
+jobs _without_ arguments.
+
+In short, unless you tell the matcher that _no_ jobs with _any_ arguments should be enqueued, you'll get the wrong result:
+
+```ruby
+# example this is a test that we'd expect to fail
+AwesomeJob.perform_async "Actually not awesome"
+
+### BAD - saying there shouldn't be a job enqueued _without_ args
+expect(AwesomeJob).not_to have_enqueued_sidekiq_job
+# => passes! 😱 Our job was enqueued _with_ args so no job exists without args.
+
+### Good
+expect(AwesomeJob).not_to have_enqueued_sidekiq_job(any_args)
+# => fails
 ```
 
 ### be_processed_in
@@ -108,7 +204,7 @@ sidekiq_options backtrace: 5
 # test with...
 expect(AwesomeJob).to save_backtrace # or
 it { is_expected.to save_backtrace }
-# ...or alternatively specifiy the number of lines that should be saved
+# ...or alternatively specify the number of lines that should be saved
 expect(AwesomeJob).to save_backtrace 5 # or
 it { is_expected.to save_backtrace 5 }
 # ...or when it should not save the backtrace
@@ -136,34 +232,32 @@ it { is_expected.to be_expired_in 1.hour }
 it { is_expected.to_not be_expired_in 2.hours }
 ```
 
-### have_enqueued_sidekiq_job
-*Describes that there should be an enqueued job with the specified arguments*
+### be_delayed
 
-**Note:** When using rspec-rails >= 3.4, use `have_enqueued_sidekiq_job` instead to
-prevent a name clash with rspec-rails' ActiveJob matcher.
+**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
-AwesomeJob.perform_async 'Awesome', true
-# test with...
-expect(AwesomeJob).to have_enqueued_sidekiq_job('Awesome', true)
+Object.delay.is_nil? # delay
+expect(Object.method :is_nil?).to be_delayed
+Object.delay.is_a? Object # delay with argument
+expect(Object.method :is_a?).to be_delayed(Object)
 
-# Code written with older versions of the gem may use the deprecated
-# have_enqueued_job matcher.
-expect(AwesomeJob).to have_enqueued_job('Awesome', true)
-```
+Object.delay_for(1.hour).is_nil? # delay for
+expect(Object.method :is_nil?).to be_delayed.for 1.hour
+Object.delay_for(1.hour).is_a? Object # delay for with argument
+expect(Object.method :is_a?).to be_delayed(Object).for 1.hour
 
-#### Testing scheduled jobs
-*Use chainable matchers `#at` and `#in`*
-```ruby
-time = 5.minutes.from_now
-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...
-expect(AwesomeJob).to have_enqueued_sidekiq_job('Awesome', true).in(5.minutes)
+Object.delay_until(1.hour.from_now).is_nil? # delay until
+expect(Object.method :is_nil?).to be_delayed.until 1.hour.from_now
+Object.delay_until(1.hour.from_now).is_a? Object # delay until with argument
+expect(Object.method :is_a?).to be_delayed(Object).until 1.hour.from_now
+
+#Rails Mailer
+MyMailer.delay.some_mail
+expect(MyMailer.instance_method :some_mail).to be_delayed
 ```
 
 ## Example matcher usage
@@ -185,11 +279,38 @@ end
 ```
 
 ## Helpers
-* [Batches (Sidekiq Pro)](#batches)
+* [Batches (Sidekiq Pro) _experimental_](#batches)
 * [`within_sidekiq_retries_exhausted_block`](#within_sidekiq_retries_exhausted_block)
 
 ### Batches
-If you are using Sidekiq Batches ([Sidekiq Pro feature][sidekiq_wiki_batches]), rspec-sidekiq replaces the implementation (using the NullObject pattern) enabling testing without a Redis instance. Mocha and RSpec stubbing is supported here.
+
+If you are using Sidekiq Batches ([Sidekiq Pro feature][sidekiq_wiki_batches]),
+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.
+
+
+```ruby
+RSpec.describe "Using mocked batches", stub_batches: true do
+  it "uses mocked batches" do
+    batch = Sidekiq::Batch.new
+    batch.jobs do
+      SomeJob.perform_async 123
+    end
+
+    expect(SomeJob).to have_enqueued_sidekiq_job
+
+    # Caution, the NullObject pattern means that the mocked Batch implementation
+    # responds to anything... even if it's not on the true `Sidekiq::Batch` API
+    # For example, the following fails
+    expect { batch.foobar! }.to raise_error(NoMethodError)
+  end
+end
+```
 
 ### within_sidekiq_retries_exhausted_block
 ```ruby
@@ -203,9 +324,15 @@ FooClass.within_sidekiq_retries_exhausted_block {
 ```
 
 ## Testing
-```bundle exec rspec spec```
+```
+bundle exec rspec spec
+```
 
 ## Maintainers
+* @wspurgin
+
+### Alumni
+
 * @packrat386
 * @philostler
 
@@ -214,20 +341,14 @@ Please do! If there's a feature missing that you'd love to see then get in on th
 
 Issues/Pull Requests/Comments all welcome...
 
-[code_climate]: https://codeclimate.com/github/philostler/rspec-sidekiq
-[code_climate_badge]: https://codeclimate.com/github/philostler/rspec-sidekiq.svg
-[coveralls]: https://coveralls.io/r/philostler/rspec-sidekiq
-[coveralls_badge]: https://img.shields.io/coveralls/philostler/rspec-sidekiq.svg?branch=develop
 [gem_version_badge]: https://badge.fury.io/rb/rspec-sidekiq.svg
-[gemnasium]: https://gemnasium.com/philostler/rspec-sidekiq
-[gemnasium_badge]: https://gemnasium.com/philostler/rspec-sidekiq.svg
-[github]: http://github.com/philostler/rspec-sidekiq
+[github]: http://github.com/wspurgin/rspec-sidekiq
 [ruby_doc]: http://rubydoc.info/gems/rspec-sidekiq/frames
 [ruby_gems]: http://rubygems.org/gems/rspec-sidekiq
 [ruby_toolbox]: http://www.ruby-toolbox.com/projects/rspec-sidekiq
-[travis_ci]: http://travis-ci.org/philostler/rspec-sidekiq
-[travis_ci_badge]: https://travis-ci.org/philostler/rspec-sidekiq.svg?branch=develop
+[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/philostler/rspec-sidekiq/wiki/FAQ-&-Troubleshooting
-[sidekiq_wiki_batches]: https://github.com/mperham/sidekiq/wiki/Batches
-[sidekiq_wiki_delayed_extensions]: https://github.com/mperham/sidekiq/wiki/Delayed-Extensions
+[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

data/lib/rspec/sidekiq/batch.rb

@@ -9,6 +9,24 @@ if defined? Sidekiq::Batch
         end
       end
 
+      ##
+      # Sidekiq::Batch is a Sidekiq::Pro feature. However the general consensus is
+      # that, by defeault, you can't test without redis. RSpec::Sidekiq includes
+      # a "null object" pattern implementation to mock Batches. This will mock
+      # Sidekiq::Batch and prevent it from using Redis.
+      #
+      # This is _opt-in_ only feature.
+      #
+      #     RSpec.describe "Using mocked batches", stub_batches: true do
+      #       it "uses mocked batches" do
+      #         batch = Sidekiq::Batch.new
+      #         batch.jobs do
+      #           SomeJob.perform_async 123
+      #         end
+      #
+      #         expect(SomeJob).to have_enqueued_sidekiq_job
+      #       end
+      #     end
       class NullBatch < NullObject
         attr_accessor :description
         attr_reader :bid
@@ -49,7 +67,7 @@ if defined? Sidekiq::Batch
           @callbacks.each do |event, callback, options|
             if event != :success || failures == 0
               case callback
-              when Class    
+              when Class
                 callback.new.send("on_#{event}", self, options)
               when String
                 klass, meth = callback.split('#')
@@ -71,7 +89,7 @@ if defined? Sidekiq::Batch
   # :nocov:
   RSpec.configure do |config|
     config.before(:each) do |example|
-      next if example.metadata[:stub_batches] == false
+      next unless example.metadata[:stub_batches] == true
 
       if mocked_with_mocha?
         Sidekiq::Batch.stubs(:new) { RSpec::Sidekiq::NullBatch.new }

data/lib/rspec/sidekiq/configuration.rb

@@ -1,13 +1,24 @@
+require "rubygems"
+
 module RSpec
   module Sidekiq
     class Configuration
-      attr_accessor :clear_all_enqueued_jobs, :enable_terminal_colours, :warn_when_jobs_not_processed_by_sidekiq
+      attr_accessor :clear_all_enqueued_jobs,
+        :enable_terminal_colours,
+        :warn_when_jobs_not_processed_by_sidekiq
 
       def initialize
-        @clear_all_enqueued_jobs = true
+        # Display settings defaults
         @enable_terminal_colours = true
+
+        # Functional settings defaults
+        @clear_all_enqueued_jobs = true
         @warn_when_jobs_not_processed_by_sidekiq = true
       end
+
+      def sidekiq_gte_7?
+        Gem::Version.new(::Sidekiq::VERSION) >= Gem::Version.new("7.0.0")
+      end
     end
   end
 end