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