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

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