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

Aspect	Rule
Spec types	Model: domain logic; Request: HTTP endpoints (prefer over controller); Job: background processing; Service/PORO: no Rails helpers; System: critical E2E only (slow)
Assertions	Test behavior, not implementation
Factories	Minimal — only attributes needed; use traits for optional states; prefer `build`/`build_stubbed` over `create`
Mocking	Stub external boundaries, not internal code
Isolation	Each example independent; no shared mutable state
Naming	`describe` for class/method, `context` for scenario
Service specs	Required: `describe '.call'` and `subject(:result)` for the primary invocation
`let` vs `let!`	Default to `let`; `let!` ONLY when object must exist before example runs
External service mocking	`allow(ServiceClass).to receive(:method)` — not `instance_double`; `instance_double` only for injected collaborators