sidekiq-tests

Overview

Sidekiq is the de facto Ruby background-job framework on Redis. The testing model per github.com/sidekiq/sidekiq/wiki/Testing:

Three test modes:

Mode	Behavior
Sidekiq::Testing.fake!	"pushes all jobs into a jobs array" (default in test env)
Sidekiq::Testing.inline!	"run jobs inline" (executes immediately, synchronously)
Sidekiq::Testing.disable!	"Enqueue jobs to Redis as normal"

Choose fake! for unit tests (assert enqueueing without execution), inline! for integration tests (test the worker itself end-to-end), disable! for tests that need real Redis (e.g., scheduled-job queries against the Sidekiq API).

When to use

• The repo has app/workers/*.rb (or app/jobs/*.rb) with Sidekiq classes.
• The user writes tests for job enqueueing logic (controllers / services).
• Tests need to assert on job count, scheduled time, or arguments.
• A test verifies retry / dead-set / unique-job behavior.

Step 1 - Configure test mode

In spec_helper.rb (RSpec) or test_helper.rb (Minitest):

require 'sidekiq/testing'

Sidekiq::Testing.fake!   # default for unit tests

Switch per-test when needed:

it "actually runs the job" do
  Sidekiq::Testing.inline! do
    create(:order)        # triggers OrderConfirmationWorker.perform_async
    expect(...).to ...
  end
end

Step 2 - Clear jobs between tests

Per sk-test, the Minitest helper:

module SidekiqMinitestSupport
  def after_teardown
    Sidekiq::Worker.clear_all
    super
  end
end

For RSpec, equivalent:

RSpec.configure do |config|
  config.before(:each) { Sidekiq::Worker.clear_all }
end

Without this, jobs accumulate across tests - order-dependent test failures result.

Step 3 - Assert enqueueing (fake! mode)

Per sk-test (verbatim RSpec example):

expect {
  HardWorker.perform_async(1, 2)
}.to change(HardWorker.jobs, :size).by(1)

Plus assertion on the basic count: assert_equal 0, HardWorker.jobs.size followed by enqueueing and verifying the count changes.

Inspect job arguments + scheduled time:

HardWorker.perform_in(1.hour, "user-123")
job = HardWorker.jobs.last
expect(job["args"]).to eq(["user-123"])
expect(job["at"]).to be_within(5.seconds).of(1.hour.from_now.to_f)

Step 4 - Drain (execute) queued fake! jobs

Without leaving fake! mode, drain executes accumulated jobs:

HardWorker.perform_async(1, 2)
HardWorker.drain   # runs all queued HardWorker jobs synchronously

Useful for integration tests that need fake! globally but selectively run a worker's jobs.

Step 5 - Test scheduled jobs

Per sk-test: "Sidekiq's API does not have a testing mode" - meaning scheduled-set queries always hit Redis, not the test harness. To test scheduled jobs in fake! mode, inspect the job's at field directly (Step 3). For integration testing of the Sidekiq scheduler API, use Sidekiq::Testing.disable! + a real Redis instance (Docker / Testcontainers).

Step 6 - Test retry behavior

Sidekiq retries failed jobs by default (25 retries, exponential backoff). To test retry logic:

it "retries on transient error" do
  Sidekiq::Testing.inline!
  expect_any_instance_of(HardWorker).to receive(:perform).and_raise(StandardError, "transient")
  expect { HardWorker.perform_async }.to raise_error(StandardError)
  # In production, Sidekiq would retry; in inline! mode, the raise propagates
end

For more realistic retry testing, switch to disable! + use the Sidekiq API (Sidekiq::RetrySet.new.size) to count retried jobs in Redis.

Step 7 - Test unique-jobs semantics

If using sidekiq-unique-jobs gem, unique-lock state lives in Redis; test in disable! mode against a real Redis instance. fake! mode does NOT enforce uniqueness (jobs all accumulate in the array regardless of unique config).

Step 8 - CI integration

- run: bundle install
- run: bundle exec rspec
# ... or for Minitest:
- run: bundle exec rake test

Sidekiq tests run in the standard Ruby test runner. For tests that need real Redis, use a service container:

services:
  redis:
    image: redis:7
    ports: [6379:6379]

Anti-patterns

Anti-pattern	Why it fails	Fix
Test code uses inline! everywhere	Slows tests; couples test to worker internals	fake! for enqueue tests; inline! only for integration
No Sidekiq::Worker.clear_all between tests	Jobs leak across tests; flaky	Add after_teardown / before(:each) hook (Step 2)
Test scheduled-set via Sidekiq::ScheduledSet.new.size in fake! mode	API hits Redis, not the fake jobs array; returns 0 unexpectedly	Inspect Worker.jobs.last["at"] instead (Step 3)
Test unique-jobs in fake! mode	Uniqueness lock isn't enforced; tests pass-by-accident	Use disable! + real Redis (Step 7)

Limitations

• Sidekiq's API queries (ScheduledSet, RetrySet, DeadSet) bypass the testing mode and always hit Redis (per sk-test).
• inline! mode runs jobs synchronously in the calling thread - hides concurrency bugs that production exhibits.
• Unique-jobs semantics need real Redis to test (Step 7).
• Sidekiq Pro / Enterprise features (batches, super-workers) have their own testing patterns not covered here - consult their docs.

References

• sk-test - testing modes, RSpec + Minitest examples, helper patterns
• github.com/sidekiq/sidekiq - repository
• celery-tests, bullmq-tests, sqs-tests, rabbitmq-tests - sister tools
• idempotency-test-author, cron-job-test-author - build-an-X authors for cross-tool patterns