phpunit-best-practices

PHPUnit 最佳实践

面向 PHPUnit 应用的全面测试最佳实践指南，由 pentiminax 维护。包含 8 个类别中的 40 条规则，并按影响排序，为自动化测试生成、重构和代码审查提供指导。

适用场景

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

• 编写新的 PHPUnit 测试类或测试方法
• 审查测试代码的质量和一致性
• 重构现有测试套件
• 配置 PHPUnit XML 设置
• 设置代码覆盖率和测试组织结构

按优先级划分的规则类别

优先级	类别	影响	前缀
1	原则与模式	关键	principle-
2	编码规范	关键	standard-
3	测试属性	高	attr-
4	数据管理	高	data-
5	测试文档	中	doc-
6	模拟	中	mock-
7	集成测试	中	integration-
8	配置	低至中	config-

快速参考

1. 原则与模式（关键）

• rules/principle-aaa-pattern.md - 使用 Arrange-Act-Assert 结构组织测试
• rules/principle-first-fast.md - 保持测试快速
• rules/principle-first-isolated.md - 确保测试相互独立
• rules/principle-first-repeatable.md - 让测试结果具有确定性
• rules/principle-first-self-validating.md - 测试必须能明确判定通过或失败
• rules/principle-first-timely.md - 随生产代码一起编写测试
• rules/principle-dry-vs-damp.md - 平衡测试中的 DRY 原则与可读性

2. 编码规范（关键）

• rules/standard-strict-types.md - 在测试文件中声明 strict_types=1
• rules/standard-final-classes.md - 将测试类设为 final
• rules/standard-snake-case-methods.md - 测试方法名使用 snake_case
• rules/standard-psr4-naming.md - 遵循 PSR-4 命名和命名空间约定
• rules/standard-psr12-formatting.md - 应用 PSR-12 代码格式规范
• rules/standard-this-over-self.md - 断言使用 $this，而非 self::
• rules/standard-visibility-type-hints.md - 明确声明可见性和类型提示

3. 测试属性（高）

• rules/attr-test-attribute.md - 使用 #[Test] 属性和 it_ 前缀
• rules/attr-covers-class.md - 使用 #[CoversClass] 指定覆盖范围
• rules/attr-uses-class.md - 使用 #[UsesClass] 记录依赖项
• rules/attr-size-categories.md - 按规模对测试分类
• rules/attr-group.md - 使用 #[Group] 进行任意分类
• rules/attr-no-annotations.md - 优先使用 PHP 8 属性，而非 PHPDoc 注解

4. 数据管理（高）

• rules/data-provider.md - 使用 #[DataProvider] 覆盖多个场景
• rules/data-provider-external.md - 使用 #[DataProviderExternal] 共享数据
• rules/data-test-with.md - 使用 #[TestWith] 内联数据集
• rules/data-factory-method.md - 使用工厂方法实例化 SUT
• rules/data-direct-instantiation.md - 对简单构造函数直接实例化

5. 测试文档（中）

• rules/doc-testdox.md - 使用 TestDox 编写可执行规范
• rules/doc-testdox-attribute.md - 使用 #[TestDox] 属性自定义显示内容
• rules/doc-readable-names.md - 使用易读的测试名称作为规范

6. 模拟（中）

• rules/mock-chicago-vs-london.md - 芝加哥派与伦敦派 TDD 学说
• rules/mock-prophecy.md - 使用 Prophecy 创建表达力强的测试替身
• rules/mock-avoid-over-mocking.md - 避免过度模拟内部依赖

7. 集成测试（中）

• rules/integration-smoke-http.md - HTTP 控制器冒烟测试
• rules/integration-smoke-cli.md - CLI 命令冒烟测试
• rules/integration-performance.md - 考虑性能的测试配置
• rules/integration-singleton.md - 为无状态服务使用单例
• rules/integration-transactions.md - 使用数据库事务清理测试数据

8. 配置（低至中）

• rules/config-testsuites.md - 将测试组织到具名测试套件中
• rules/config-strictness.md - 启用严格模式设置
• rules/config-source-coverage.md - 指定用于覆盖率分析的源代码目录
• rules/config-order-by.md - 测试执行顺序策略
• rules/config-cache.md - 设置缓存目录以提升性能
• rules/config-stop-on-failure.md - 首次失败时停止，以便快速获得反馈

使用方法

阅读各条规则文件，了解详细说明和代码示例：

• rules/principle-aaa-pattern.md
• rules/standard-final-classes.md

每条规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料