Testing with Sidekiq Unique Jobs

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• spec/spec_helper.rb
• spec/sidekiq_unique_jobs/sidekiq_unique_jobs_spec.rb
• lib/sidekiq_unique_jobs/rspec/matchers.rb
• BENCHMARKING.md

Testing applications that utilize sidekiq-unique-jobs requires a strategic approach to ensure that uniqueness constraints do not interfere with test isolation while still allowing for the validation of job configurations. The gem provides specialized utilities and configuration hooks to manage lock behavior within a test suite, primarily through RSpec integration and global configuration toggles.

Developers are generally advised not to test the gem's internal uniqueness behavior within their own application tests. Instead, the focus should be on verifying that workers have valid Sidekiq options and that the application logic remains functional when uniqueness is either enabled or disabled.

Sources: CLAUDE.md:144-147, README.md:162-164

Test Environment Configuration

To prevent side effects during testing, such as locks persisting across different test examples or blocking job execution, the gem allows for global and block-level configuration adjustments.

Disabling Uniqueness Globally

The most common pattern for application testing is to disable uniqueness globally in the test helper (e.g., spec_helper.rb or rails_helper.rb). This ensures that multiple jobs with the same arguments can be enqueued without being dropped by the middleware.

# spec/spec_helper.rb
SidekiqUniqueJobs.configure do |config|
  config.enabled = false
end

Sources: README.md:162-164, spec/spec_helper.rb:69-74

Temporary Configuration Overrides

For specific tests where uniqueness behavior must be verified, SidekiqUniqueJobs.use_config provides a way to temporarily override settings. This is useful for changing the lock_prefix or enabling the gem for a specific context.

it "changes configuration temporary" do
  described_class.use_config(lock_prefix: "bogus") do
    expect(described_class.config.lock_prefix).to eq("bogus")
  end
end

Sources: spec/sidekiq_unique_jobs/sidekiq_unique_jobs_spec.rb:14-20, CLAUDE.md:120-121

Manual Toggling

The gem provides helper methods .enable! and .disable! which can accept blocks to control the active state of the middleware dynamically.

Method	Description
enable!	Enables unique jobs globally or within a block.
disable!	Disables unique jobs globally or within a block.
enabled?	Returns true if uniqueness enforcement is active.

Sources: spec/sidekiq_unique_jobs/sidekiq_unique_jobs_spec.rb:71-99

RSpec Integration

The project includes built-in RSpec support, offering custom matchers and helper modules to streamline the testing process.

Custom Matchers

The gem provides a matcher have_valid_sidekiq_options to ensure that worker configurations (like lock types and TTLs) are correctly defined and won't fail at runtime.

require "sidekiq_unique_jobs/rspec/matchers"

RSpec.describe MyWorker do
  it { is_expected.to have_valid_sidekiq_options }
end

Sources: lib/sidekiq_unique_jobs/rspec/matchers.rb:1-25

Sidekiq Testing Modes

The gem is compatible with standard Sidekiq::Testing modes. When using Sidekiq::Testing.inline!, jobs execute immediately, but uniqueness is still enforced by the middleware if enabled.

Sources: README.md:166-168, CLAUDE.md:122-123

Performance and Benchmarking

The repository includes a suite of benchmarking tools to measure the impact of uniqueness on job processing throughput and memory usage.

Available Benchmark Tools

Command	Purpose
bin/benchmark	Comprehensive suite covering lock acquisition, contention, and memory.
bin/bench	Specific benchmarks for the orphan reaper (Ruby vs Lua).
bin/benchmark_improvements	Targeted tests for non-blocking locks and TTL calculations.
bin/compare_performance	Compares performance between two git branches.

Sources: BENCHMARKING.md:7-40

Benchmarking Workflow

The benchmarking system uses benchmark-ips for iterations per second and benchmark-memory for allocation tracking. The compare_performance tool automates the process of checking out branches and generating comparative metrics.

Observability in Tests (Reflections)

Testing can leverage the Reflection system to observe lock lifecycle events without altering the execution flow. This is particularly useful for verifying that locks are acquired or released during complex workflows.

Summary

Testing with sidekiq-unique-jobs is centered on controlling the middleware state through SidekiqUniqueJobs.config.enabled. By disabling uniqueness in general test suites and utilizing temporary configuration overrides for edge cases, developers can maintain fast, isolated tests while ensuring their lock configurations remain valid via custom RSpec matchers.