rails-testing

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