An opinionated RSpec style guide built as a single coherent framework, not a collection
of isolated tips à la Better Specs. The core of the
framework is exhaustive specification through nested contexts: the
describe / context / it tree is a decision tree over the domain — each nesting level
is one characteristic, sibling contexts are its states, leaves are the expected
behaviors. Structured this way, the suite reads as a specification of business rules,
missing cases become visible to the eye, and writing the spec actively finds bugs
instead of just pinning the happy path.
Three more ideas run through all 17 rules: cognitive load (spend the reader's working memory on the domain, not on test mechanics), tests as design feedback (code that resists a clean spec is the code's problem), and tests as documentation (every context chain reads as an English sentence).
- Style guide — the core document: philosophy and 17 rules with examples: EN | RU
- API contract testing — where RSpec stops being the right tool and what to use instead (JSON Schema, rspec-openapi, RSwag, Pact, snapshot testing): EN | RU
- Patterns — supplementary techniques that did not fit the rules
(
super().merge(), subject with lambda, shared contexts): EN | RU
Step-by-step workflows that turn the guide into a repeatable process:
- Writing a test from scratch — 16 stages from choosing the spec level to the final linter check: EN | RU
- Optimizing factories — mapping characteristic states to traits, choosing between build/create/stub, avoiding anti-patterns: EN | RU
| You want to… | Read |
|---|---|
| Understand the approach | the guide's opening philosophy sections: EN | RU |
| Write a spec right now | the algorithm: EN | RU |
| Tame your factories | EN | RU |
| Test an API contract | EN | RU |
| Enforce the rules in CI | rubocop-configs/ |
| Have an AI agent apply all of it | plugins/rspec-testing-skill/ |
The rubocop-rspec-guide gem provides custom cops that enforce key structural rules of the guide automatically (behavioral coverage, happy path first, context setup, duplicate detection). Configuration examples and setup instructions: rubocop-configs/.
- rspec-testing-skill — a single self-contained skill that teaches the agent the whole methodology: characteristic tables and context trees before any code, FactoryBot-first data preparation, test-prof-neutral, active bug-finding. The everyday path for AI-assisted test writing.
- lets-expect-testing — the same methodology
translated to Rust and the
lets_expectcrate. - rspec-testing — a heavyweight multi-agent workflow for batch test generation (slash commands, agent pipeline, metadata files). Work in progress.
Open an issue to discuss changes. Maintain both Russian and English versions — they are kept line-symmetric.
MIT — use the guide, configs, and plugins freely in your projects.