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

design-

data-

model-

request-

system-

async-

perf-

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