rails-testing — Claude Code skill: what it does, how to install
rails-testing — a set of 46 rules for RSpec, FactoryBot, and Capybara in Ruby on Rails. Guides your AI agent during test generation, reviews, and test suite refactoring.
MIT 309 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill rails-testing -a claude-codeWhat rails-testing does
The skill organizes 46 rules across 8 priority categories for Rails test suites. It instructs the agent to focus on observable behavior rather than private implementation details. This avoids brittle tests. The agent stops writing redundant assertions against built-in ActiveRecord logic.
For test data, the rules prioritize build and build_stubbed over database persistence. System tests in Capybara forbid sleep calls because synchronization relies on built-in waiting. Background jobs separate enqueuing from running perform.
Rules also handle transaction-aware job enqueuing in Rails 7.2+. The skill complements rails-dev, ruby-optimise, and ruby-refactor.
What it helps with
- Replace slow database records with
build_stubbedin specs - Eliminate flaky Capybara system tests that depend on
sleep - Verify Sidekiq job enqueuing separately from worker execution
- Structure FactoryBot factories using composable traits and sequences
- Migrate legacy controller tests to modern request specs
Example prompts for the agent
- Generate a request spec for the checkout endpoint with role authorization and status checks
- Review this model spec to remove redundant ActiveRecord checks and add validation edge cases
- Refactor the background mailer test to handle Rails 7.2 transaction commit callbacks
How to install rails-testing
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rails-testing -a claude-code2Manually: put the files in place
~/.claude/skills/rails-testing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rails-testing/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rails-testing -a codex2Manually: put the files in place
.agents/skills/rails-testing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rails-testing -a cursor2Manually: put the files in place
.cursor/skills/rails-testing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/rails-testing2Manually: put the files in place
.github/skills/rails-testing/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rails-testing -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/rails-testingManually: put the files in place
.devin/skills/rails-testing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rails-testing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rails-testing
How do I install rails-testing in Claude Code?
Run npx skills add pproenca/dot-skills --skill rails-testing -a claude-code. The skill definition file is placed at ~/.claude/skills/rails-testing/SKILL.md.
What does the rails-testing skill do?
It provides 46 rules for writing, reviewing, and refactoring Rails tests with RSpec. The skill enforces behavior-driven assertions, cleaner factory definitions, and isolation for background jobs.
How does the skill handle background jobs?
It separates testing job enqueuing from running the perform method, using Sidekiq fake mode by default. It also accounts for transaction-aware job enqueuing introduced in Rails 7.2+.
Source text
SKILL.md · MIT
--- name: rails-testing description: Ruby on Rails testing best practices for writing effective, maintainable test suites with RSpec. This skill should be used when writing, reviewing, or refactoring Rails tests to ensure proper test design, data management, and coverage patterns. Triggers on tasks involving RSpec specs, model tests, request specs, system tests, factory definitions, Capybara interactions, Sidekiq job tests, or test suite optimization. Complementary to rails-dev, ruby-optimise, and ruby-refactor skills. --- # Community Ruby on Rails Testing Best Practices Comprehensive testing guide for Ruby on Rails applications, maintained by Community. Contains 46 rules across 8 categories, prioritized by impact to guide automated test generation, review, and refactoring. ## When to Apply Reference these guidelines when: - Writing new RSpec specs for models, requests, system tests, or jobs - Setting up FactoryBot factories with traits and sequences - Writing Capybara system tests for user journeys - Testing background jobs with Sidekiq or Active Job - Reviewing test code for anti-patterns (mystery guests, flaky tests, slow specs) - Optimizing test suite performance and CI pipeline speed - Organizing test files, shared examples, and custom matchers ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Test Design & Structure | CRITICAL | `design-` | | 2 | Test Data Management | CRITICAL | `data-` | | 3 | Model Testing | HIGH | `model-` | | 4 | Request & Controller Testing | HIGH | `request-` | | 5 | System & Acceptance Testing | MEDIUM-HIGH | `system-` | | 6 | Async & Background Job Testing | MEDIUM | `async-` | | 7 | Test Performance & Reliability | MEDIUM | `perf-` | | 8 | Test Organization & Maintenance | LOW-MEDIUM | `org-` | ## Quick Reference ### 1. Test Design & Structure (CRITICAL) - [`design-four-phase-test`](references/design-four-phase-test.md) - Use four-phase test structure (setup, exercise, verify, teardown) - [`design-behavior-over-implementation`](references/design-behavior-over-implementation.md) - Test observable behavior, not internal implementation - [`design-one-assertion-per-test`](references/design-one-assertion-per-test.md) - One logical expectation per test for precise failure diagnosis - [`design-descriptive-test-names`](references/design-descriptive-test-names.md) - Write test names that read like specifications - [`design-avoid-mystery-guest`](references/design-avoid-mystery-guest.md) - Make all test data visible within the test itself - [`design-avoid-conditional-logic`](references/design-avoid-conditional-logic.md) - No if/else or loops in test code - [`design-explicit-subject`](references/design-explicit-subject.md) - Name subjects explicitly instead of using implicit subject ### 2. Test Data Management (CRITICAL) - [`data-factory-traits`](references/data-factory-traits.md) - Use composable factory traits instead of separate factories - [`data-minimal-attributes`](references/data-minimal-attributes.md) - Specify only attributes relevant to the test - [`data-build-over-create`](references/data-build-over-create.md) - Prefer build/build_stubbed over create when persistence isn't needed - [`data-avoid-fixture-coupling`](references/data-avoid-fixture-coupling.md) - Use factories instead of shared fixtures - [`data-transient-attributes`](references/data-transient-attributes.md) - Use transient attributes for complex factory setup - [`data-sequence-unique-values`](references/data-sequence-unique-values.md) - Use sequences for uniqueness-constrained fields ### 3. Model Testing (HIGH) - [`model-test-validations`](references/model-test-validations.md) - Test validations with boundary cases, not just happy path - [`model-test-associations`](references/model-test-associations.md) - Test associations explicitly including dependent behavior - [`model-test-scopes`](references/model-test-scopes.md) - Test scopes with matching and non-matching records - [`model-test-callbacks-sparingly`](references/model-test-callbacks-sparingly.md) - Test callback side effects, not callback existence - [`model-test-custom-methods`](references/model-test-custom-methods.md) - Test public methods with input/output pairs across scenarios - [`model-avoid-testing-framework`](references/model-avoid-testing-framework.md) - Don't test ActiveRecord or framework behavior - [`model-test-enums`](references/model-test-enums.md) - Test enum transitions and generated scopes ### 4. Request & Controller Testing (HIGH) - [`request-over-controller-specs`](references/request-over-controller-specs.md) - Use request specs over deprecated controller specs - [`request-test-response-status`](references/request-test-response-status.md) - Assert HTTP status codes explicitly - [`request-test-authentication`](references/request-test-authentication.md) - Test authentication boundaries for every protected endpoint - [`request-test-authorization`](references/request-test-authorization.md) - Test authorization for each role - [`request-test-params-validation`](references/request-test-params-validation.md) - Test parameter validation and edge cases - [`request-json-response-structure`](references/request-json-response-structure.md) - Assert JSON response structure for API endpoints ### 5. System & Acceptance Testing (MEDIUM-HIGH) - [`system-page-objects`](references/system-page-objects.md) - Encapsulate page interactions in page objects - [`system-use-accessible-selectors`](references/system-use-accessible-selectors.md) - Use accessible selectors over CSS/XPath - [`system-avoid-sleep`](references/system-avoid-sleep.md) - Never use sleep — rely on Capybara's built-in waiting - [`system-test-critical-paths`](references/system-test-critical-paths.md) - Reserve system tests for critical user journeys - [`system-database-state`](references/system-database-state.md) - Use truncation strategy for system test database cleanup - [`system-screenshot-on-failure`](references/system-screenshot-on-failure.md) - Capture screenshots on system test failure ### 6. Async & Background Job Testing (MEDIUM) - [`async-separate-enqueue-from-perform`](references/async-separate-enqueue-from-perform.md) - Test enqueue and perform separately - [`async-use-fake-mode-default`](references/async-use-fake-mode-default.md) - Default to Sidekiq fake mode globally - [`async-test-job-perform`](references/async-test-job-perform.md) - Test job perform method directly - [`async-test-mailer-delivery`](references/async-test-mailer-delivery.md) - Test mailer delivery with enqueued mail matcher - [`async-test-after-commit`](references/async-test-after-commit.md) - Account for transaction-aware job enqueuing in Rails 7.2+ ### 7. Test Performance & Reliability (MEDIUM) - [`perf-parallel-tests`](references/perf-parallel-tests.md) - Run tests in parallel across CPU cores - [`perf-database-strategy`](references/perf-database-strategy.md) - Use transaction strategy for non-system tests - [`perf-profile-slow-specs`](references/perf-profile-slow-specs.md) - Profile and fix the slowest specs - [`perf-quarantine-flaky-tests`](references/perf-quarantine-flaky-tests.md) - Quarantine flaky tests instead of retrying - [`perf-avoid-before-all-mutation`](references/perf-avoid-before-all-mutation.md) - Never mutate state created in before(:all) ### 8. Test Organization & Maintenance (LOW-MEDIUM) - [`org-avoid-deep-nesting`](references/org-avoid-deep-nesting.md) - Limit context nesting to 3 levels - [`org-shared-examples-sparingly`](references/org-shared-examples-sparingly.md) - Use shared examples only for true behavioral contracts - [`org-custom-matchers`](references/org-custom-matchers.md) - Extract custom matchers for repeated domain assertions - [`org-file-structure-mirrors-app`](references/org-file-structure-mirrors-app.md) - Mirror app directory structure in spec directory ## How to Use Read individual reference files for detailed explanations and code examples: - [Section definitions](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - Template for adding new rules ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |
© pproenca · MIT · pproenca/dot-skills