---

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 - Use four-phase test structure (setup, exercise, verify, teardown)
• design-behavior-over-implementation - Test observable behavior, not internal implementation
• design-one-assertion-per-test - One logical expectation per test for precise failure diagnosis
• design-descriptive-test-names - Write test names that read like specifications
• design-avoid-mystery-guest - Make all test data visible within the test itself
• design-avoid-conditional-logic - No if/else or loops in test code
• design-explicit-subject - Name subjects explicitly instead of using implicit subject

2. Test Data Management (CRITICAL)

• data-factory-traits - Use composable factory traits instead of separate factories
• data-minimal-attributes - Specify only attributes relevant to the test
• data-build-over-create - Prefer build/build_stubbed over create when persistence isn't needed
• data-avoid-fixture-coupling - Use factories instead of shared fixtures
• data-transient-attributes - Use transient attributes for complex factory setup
• data-sequence-unique-values - Use sequences for uniqueness-constrained fields

3. Model Testing (HIGH)

• model-test-validations - Test validations with boundary cases, not just happy path
• model-test-associations - Test associations explicitly including dependent behavior
• model-test-scopes - Test scopes with matching and non-matching records
• model-test-callbacks-sparingly - Test callback side effects, not callback existence
• model-test-custom-methods - Test public methods with input/output pairs across scenarios
• model-avoid-testing-framework - Don't test ActiveRecord or framework behavior
• model-test-enums - Test enum transitions and generated scopes

4. Request & Controller Testing (HIGH)

• request-over-controller-specs - Use request specs over deprecated controller specs
• request-test-response-status - Assert HTTP status codes explicitly
• request-test-authentication - Test authentication boundaries for every protected endpoint
• request-test-authorization - Test authorization for each role
• request-test-params-validation - Test parameter validation and edge cases
• request-json-response-structure - Assert JSON response structure for API endpoints

5. System & Acceptance Testing (MEDIUM-HIGH)

• system-page-objects - Encapsulate page interactions in page objects
• system-use-accessible-selectors - Use accessible selectors over CSS/XPath
• system-avoid-sleep - Never use sleep — rely on Capybara's built-in waiting
• system-test-critical-paths - Reserve system tests for critical user journeys
• system-database-state - Use truncation strategy for system test database cleanup
• system-screenshot-on-failure - Capture screenshots on system test failure

6. Async & Background Job Testing (MEDIUM)

• async-separate-enqueue-from-perform - Test enqueue and perform separately
• async-use-fake-mode-default - Default to Sidekiq fake mode globally
• async-test-job-perform - Test job perform method directly
• async-test-mailer-delivery - Test mailer delivery with enqueued mail matcher
• async-test-after-commit - Account for transaction-aware job enqueuing in Rails 7.2+

7. Test Performance & Reliability (MEDIUM)

• perf-parallel-tests - Run tests in parallel across CPU cores
• perf-database-strategy - Use transaction strategy for non-system tests
• perf-profile-slow-specs - Profile and fix the slowest specs
• perf-quarantine-flaky-tests - Quarantine flaky tests instead of retrying
• perf-avoid-before-all-mutation - Never mutate state created in before(:all)

8. Test Organization & Maintenance (LOW-MEDIUM)

• org-avoid-deep-nesting - Limit context nesting to 3 levels
• org-shared-examples-sparingly - Use shared examples only for true behavioral contracts
• org-custom-matchers - Extract custom matchers for repeated domain assertions
• org-file-structure-mirrors-app - Mirror app directory structure in spec directory

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information