Skip to main content
skill CX Codex

rails-testing — Claude Code skill: what it does, how to install

rails-testing — a set of 46 rules for RSpec, FactoryBot, and Capybara in Ruby on Rails. Guides your AI agent during test generation, reviews, and test suite refactoring.

MIT 309 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill rails-testing -a claude-code
Open on GitHub

What rails-testing does

The skill organizes 46 rules across 8 priority categories for Rails test suites. It instructs the agent to focus on observable behavior rather than private implementation details. This avoids brittle tests. The agent stops writing redundant assertions against built-in ActiveRecord logic.

For test data, the rules prioritize build and build_stubbed over database persistence. System tests in Capybara forbid sleep calls because synchronization relies on built-in waiting. Background jobs separate enqueuing from running perform.

Rules also handle transaction-aware job enqueuing in Rails 7.2+. The skill complements rails-dev, ruby-optimise, and ruby-refactor.

What it helps with

  • Replace slow database records with build_stubbed in specs
  • Eliminate flaky Capybara system tests that depend on sleep
  • Verify Sidekiq job enqueuing separately from worker execution
  • Structure FactoryBot factories using composable traits and sequences
  • Migrate legacy controller tests to modern request specs

Example prompts for the agent

  • Generate a request spec for the checkout endpoint with role authorization and status checks
  • Review this model spec to remove redundant ActiveRecord checks and add validation edge cases
  • Refactor the background mailer test to handle Rails 7.2 transaction commit callbacks

How to install rails-testing

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill rails-testing -a claude-code

2Manually: put the files in place

~/.claude/skills/rails-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rails-testing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rails-testing

How do I install rails-testing in Claude Code?

Run npx skills add pproenca/dot-skills --skill rails-testing -a claude-code. The skill definition file is placed at ~/.claude/skills/rails-testing/SKILL.md.

What does the rails-testing skill do?

It provides 46 rules for writing, reviewing, and refactoring Rails tests with RSpec. The skill enforces behavior-driven assertions, cleaner factory definitions, and isolation for background jobs.

How does the skill handle background jobs?

It separates testing job enqueuing from running the perform method, using Sidekiq fake mode by default. It also accounts for transaction-aware job enqueuing introduced in Rails 7.2+.

Source text

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

### 2. Test Data Management (CRITICAL)

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

### 3. Model Testing (HIGH)

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

### 4. Request & Controller Testing (HIGH)

- [`request-over-controller-specs`](references/request-over-controller-specs.md) - Use request specs over deprecated controller specs
- [`request-test-response-status`](references/request-test-response-status.md) - Assert HTTP status codes explicitly
- [`request-test-authentication`](references/request-test-authentication.md) - Test authentication boundaries for every protected endpoint
- [`request-test-authorization`](references/request-test-authorization.md) - Test authorization for each role
- [`request-test-params-validation`](references/request-test-params-validation.md) - Test parameter validation and edge cases
- [`request-json-response-structure`](references/request-json-response-structure.md) - Assert JSON response structure for API endpoints

### 5. System & Acceptance Testing (MEDIUM-HIGH)

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

### 6. Async & Background Job Testing (MEDIUM)

- [`async-separate-enqueue-from-perform`](references/async-separate-enqueue-from-perform.md) - Test enqueue and perform separately
- [`async-use-fake-mode-default`](references/async-use-fake-mode-default.md) - Default to Sidekiq fake mode globally
- [`async-test-job-perform`](references/async-test-job-perform.md) - Test job perform method directly
- [`async-test-mailer-delivery`](references/async-test-mailer-delivery.md) - Test mailer delivery with enqueued mail matcher
- [`async-test-after-commit`](references/async-test-after-commit.md) - Account for transaction-aware job enqueuing in Rails 7.2+

### 7. Test Performance & Reliability (MEDIUM)

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

### 8. Test Organization & Maintenance (LOW-MEDIUM)

- [`org-avoid-deep-nesting`](references/org-avoid-deep-nesting.md) - Limit context nesting to 3 levels
- [`org-shared-examples-sparingly`](references/org-shared-examples-sparingly.md) - Use shared examples only for true behavioral contracts
- [`org-custom-matchers`](references/org-custom-matchers.md) - Extract custom matchers for repeated domain assertions
- [`org-file-structure-mirrors-app`](references/org-file-structure-mirrors-app.md) - Mirror app directory structure in spec directory

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Testing and QA →

From the same set139

The whole set →
tailwind-refactor tailwind-refactor — a skill for refactoring Tailwind CSS classes: migrating from v3 to v4, replacing deprecated utilities and cleaning up code without changing the visual output. CX Codex +1 321installs pulumi A skill with 46 rules for writing and refactoring Pulumi code across supported platforms. Covers state management, resource graph optimization, component design, secrets configuration, and CI/CD automation. CX Codex +1 317installs harness-engineering harness-engineering — a skill for setting up and updating repository infrastructure for AI-driven development. CX Codex +1 312installs ios-hig ios-hig — a skill with 34 Apple HIG rules for iOS 26 and Swift 6.2 apps: navigation, gestures, accessibility, loading and error states in SwiftUI. CX Codex +1 310installs ruby-refactor ruby-refactor — a refactoring skill with 45 community guidelines for Ruby projects. Helps agents simplify nested branches, decouple classes, and adopt modern Ruby 3.x patterns. CX Codex +1 307installs ios-xcode ios-xcode is a Claude Code skill for Xcode setup and iOS project tooling. It applies to App-target configuration, SwiftData, testing, debugging, profiling, and app distribution. CX Codex +1 307installs think think — a skill that shifts the AI into deep analysis mode: instead of the first reasonable answer, it finds the highest-leverage solution by connecting ideas across domains. Use it when you need strategy, not instructions. CX Codex +1 307installs restful-hateoas restful-hateoas adds 47 guidelines for building Richardson Maturity Level 3 REST APIs with HATEOAS in Ruby on Rails projects. CX Codex +1 304installs

Project sponsors

Companies that keep this analytics open