rails-testing

Ruby on Rails 测试最佳实践社区指南

面向 Ruby on Rails 应用的综合测试指南，由社区维护。涵盖 8 个类别中的 46 条规则，并按影响程度排序，为自动生成测试、代码审查和重构提供指导。

适用场景

在以下情况下参考这些指南：

• 为模型、请求、系统测试或任务编写新的 RSpec 规格
• 使用 traits 和序列设置 FactoryBot 工厂
• 为用户旅程编写 Capybara 系统测试
• 使用 Sidekiq 或 Active Job 测试后台任务
• 审查测试代码中的反模式（神秘访客、易出错的测试、耗时的规格）
• 优化测试套件性能和 CI 流水线速度
• 组织测试文件、共享示例和自定义匹配器

按优先级划分的规则类别

优先级	类别	影响	前缀
1	测试设计与结构	CRITICAL	design-
2	测试数据管理	CRITICAL	data-
3	模型测试	HIGH	model-
4	请求与控制器测试	HIGH	request-
5	系统与验收测试	MEDIUM-HIGH	system-
6	异步与后台任务测试	MEDIUM	async-
7	测试性能与可靠性	MEDIUM	perf-
8	测试组织与维护	LOW-MEDIUM	org-

快速参考

1. 测试设计与结构（CRITICAL）

• design-four-phase-test - 使用四阶段测试结构（准备、执行、验证、清理）
• design-behavior-over-implementation - 测试可观察到的行为，而非内部实现
• design-one-assertion-per-test - 每个测试只设定一个逻辑预期，以便精确诊断失败原因
• design-descriptive-test-names - 编写读起来像规格说明的测试名称
• design-avoid-mystery-guest - 在测试本身中清晰展示所有测试数据
• design-avoid-conditional-logic - 测试代码中不使用 if/else 或循环
• design-explicit-subject - 明确命名 subject，而不是使用隐式 subject

2. 测试数据管理（CRITICAL）

• data-factory-traits - 使用可组合的工厂 traits，而不是单独的工厂
• data-minimal-attributes - 只指定与测试相关的属性
• data-build-over-create - 无需持久化时，优先使用 build/build_stubbed，而非 create
• data-avoid-fixture-coupling - 使用工厂而不是共享 fixtures
• data-transient-attributes - 使用 transient 属性完成复杂的工厂设置
• data-sequence-unique-values - 对要求唯一的字段使用序列

3. 模型测试（HIGH）

• model-test-validations - 使用边界情况测试验证，而不只是测试正常路径
• model-test-associations - 明确测试关联，包括 dependent 行为
• model-test-scopes - 使用匹配和不匹配的记录测试 scopes
• model-test-callbacks-sparingly - 测试回调的副作用，而非回调是否存在
• model-test-custom-methods - 针对不同场景，使用输入和输出组合测试公共方法
• model-avoid-testing-framework - 不要测试 ActiveRecord 或框架的行为
• model-test-enums - 测试枚举转换和生成的 scopes

4. 请求与控制器测试（高）

• request-over-controller-specs - 使用请求测试，而非已弃用的控制器测试
• request-test-response-status - 明确断言 HTTP 状态码
• request-test-authentication - 测试每个受保护端点的身份验证边界
• request-test-authorization - 测试每种角色的授权情况
• request-test-params-validation - 测试参数验证和边缘情况
• request-json-response-structure - 断言 API 端点的 JSON 响应结构

5. 系统与验收测试（中高）

• system-page-objects - 使用页面对象封装页面交互
• system-use-accessible-selectors - 使用易于访问的选择器，而非 CSS/XPath
• system-avoid-sleep - 绝不使用 sleep，依靠 Capybara 内置的等待机制
• system-test-critical-paths - 仅将系统测试用于关键用户旅程
• system-database-state - 使用截断策略清理系统测试数据库
• system-screenshot-on-failure - 系统测试失败时截取屏幕截图

6. 异步与后台作业测试（中）

• async-separate-enqueue-from-perform - 分别测试入队和执行
• async-use-fake-mode-default - 全局默认使用 Sidekiq fake 模式
• async-test-job-perform - 直接测试作业的执行方法
• async-test-mailer-delivery - 使用入队邮件匹配器测试邮件发送
• async-test-after-commit - 适配 Rails 7.2+ 中支持事务的作业入队

7. 测试性能与可靠性（中）

• perf-parallel-tests - 在多个 CPU 核心上并行运行测试
• perf-database-strategy - 在非系统测试中使用事务策略
• perf-profile-slow-specs - 分析并修复最慢的测试
• perf-quarantine-flaky-tests - 隔离不稳定的测试，而非重试
• perf-avoid-before-all-mutation - 绝不修改在 before(:all) 中创建的状态

8. 测试组织与维护（低中）

• org-avoid-deep-nesting - 将 context 嵌套限制在 3 层以内
• org-shared-examples-sparingly - 仅在确有行为契约时使用共享示例
• org-custom-matchers - 将重复的领域断言提取为自定义匹配器
• org-file-structure-mirrors-app - 让 spec 目录结构与 app 目录结构保持一致

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息