RSpec Best Practices

Use this skill when the task is to write, review, or clean up RSpec tests.

Core principle: Prefer behavioral confidence over implementation coupling. Good specs are readable, deterministic, and cheap to maintain.

Quick Reference

HARD-GATE: Tests Gate Implementation

THE WORKFLOW IS: PRD → TASKS → TESTS → IMPLEMENTATION

Tests are a GATE between planning and code.
NO implementation code may be written until:
  1. The test EXISTS
  2. The test has been RUN
  3. The test FAILS for the correct reason (feature missing, not typo)

Write code before the test? Delete it. Start over.

The gate cycle for each behavior:

1. Write test: One minimal test showing what the behavior should do
2. Run test: Execute it — this is mandatory, not optional
3. Validate failure: Confirm it fails because the feature is missing
4. CHECKPOINT — Test Design Review: Present the failing test. Confirm boundary, behavior, and edge cases before writing implementation. See rails-tdd-slices for checkpoint format.
5. GATE PASSED — you may now write implementation code
6. CHECKPOINT — Implementation Proposal: Before writing code, state which classes/methods will be created or changed and the rough structure. Wait for confirmation.
7. Write minimal code: Simplest implementation to make the test pass
8. Run test again: Confirm it passes and no other tests break
9. Refactor: Clean up — tests must stay green
10. Next behavior: Return to step 1

TDD Slice Selection

Choose the first failing spec at the boundary that gives the strongest signal with the least setup:

Structure and Style

• describe for the class, module, or behavior; context for scenarios ("when valid", "when user is missing").
• Mirror source paths under spec/ (e.g. app/models/user.rb → spec/models/user_spec.rb).
• Use shared_examples / shared_context for repeated behavior; put reusable shared examples under spec/support/.
• Use let_it_be only when test-prof already exists in the project.
• Time-dependent behavior MUST use travel_to — do not set dates in the past as a shortcut, do not stub Time.now. Wrap assertions in a travel_to block to control the clock:

let(:subscription) { create(:subscription, activated_at: Time.current) }

context 'after expiration' do
  it 'is expired' do
    travel_to 31.days.from_now do
      expect(subscription).to be_expired
    end
  end
end

Minimal request spec skeleton:

# frozen_string_literal: true

RSpec.describe 'POST /orders', type: :request do
  let(:product) { create(:product, stock: 5) }

  context 'when product is in stock' do
    it 'returns 201 for an in-stock product' do
      post orders_path, params: { order: { product_id: product.id } }, as: :json
      expect(response).to have_http_status(:created)
    end
  end
end

Monolith vs engine: When the project is a Rails engine, use rails-engine-testing for dummy-app setup and engine request/routing/generator specs; keep using this skill for general RSpec style.

For more examples (model spec, service spec, shared_examples, travel_to), see EXAMPLES.md.

Pitfalls

Integration