Testing

Run the search layer offline with the default test client or a stub for assertions.

Related: Observability, DX, Client, Troubleshooting

Test-only helpers to run the search layer offline (no I/O by default) and write ergonomic assertions against unified events and compiled params.

Quick start

The engine automatically uses an offline client in test mode (Rails test environment or RACK_ENV=test). For programmable responses, enable the stub client:

# test_helper.rb or spec_helper.rb
require 'search_engine/test'

SearchEngine.configure do |c|
  c.client = SearchEngine::Test::StubClient.new
end

• Queue responses and inspect captured calls:

stub = SearchEngine.client
stub.enqueue_response(:search, { 'hits' => [], 'found' => 0, 'out_of' => 0 })

# your relation execution here ...

calls = stub.search_calls
first = calls.first
first.url        # => compiled search URL
first.redacted?  # => true
first.redacted_body # => redacted subset for safe logs

• Programmable responses via blocks or exceptions:

stub.enqueue_response(:search, ->(req) { { 'hits' => [], 'found' => 42, 'out_of' => 42 } })
stub.enqueue_response(:multi_search, RuntimeError.new('boom'))

• Use the SearchEngine.client helper to access the configured client:

client = SearchEngine.client  # Returns StubClient, OfflineClient, or Client

Event assertions

Unified events are emitted via ActiveSupport::Notifications. Capture them for a block and assert.

• RSpec matcher:

expect { rel.to_a }.to emit_event("search_engine.search").with(hash_including(collection: "books"))

• Minitest helpers:

include SearchEngine::Test::MinitestAssertions

assert_emits("search_engine.search", payload: ->(p) { p[:collection] == "books" }) { rel.to_a }

events = capture_events { rel.to_a }

• Params helpers in tests:

expect(rel.to_params_json).to include("filter_by")

See also: Relation#to_params_json, Relation#to_curl, and Relation#dry_run!.

Test mode and offline client

The engine automatically enables test mode when running in Rails test environment or when RACK_ENV=test is set. In test mode, SearchEngine.client returns a no-op SearchEngine::Test::OfflineClient that avoids network I/O and returns safe empty responses.

Environment overrides

You can control test mode via environment variables:

• SEARCH_ENGINE_TEST_MODE=1 or SEARCH_ENGINE_TEST_MODE=0 (explicit override)
• SEARCH_ENGINE_OFFLINE=1 or SEARCH_ENGINE_OFFLINE=0 (legacy alias)

When SearchEngine.config.client is explicitly set (e.g., StubClient), it always takes precedence over automatic offline mode.

OfflineClient behavior

SearchEngine::Test::OfflineClient implements all client methods but performs no network I/O:

• search returns empty results (found: 0)
• multi_search returns empty results array
• import_documents returns success JSONL
• All other operations return safe empty responses

Offline strategy & safety

• Captured bodies and event payloads are redacted via the central helper.
• No API keys, raw filter literals, or PII are stored; long strings are truncated.
• A redacted? marker is present on captured request entries.

Parallel test safety

• Internals are protected by a lightweight mutex.
• Use stub.reset! between examples if needed.

Backlinks: Observability, DX, CLI, Client