phpunit-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PHPUnit Best Practices

PHPUnit最佳实践

Comprehensive testing best practices guide for PHPUnit applications, maintained by pentiminax. Contains 40 rules across 8 categories, prioritized by impact to guide automated test generation, refactoring, and code review.

适用于PHPUnit应用的综合测试最佳实践指南，由pentiminax维护。包含8个类别下的40条规则，按影响优先级排序，可用于指导自动化测试生成、重构与代码评审。

When to Apply

适用场景

Reference these guidelines when:

Writing new PHPUnit test classes or test methods
Reviewing test code for quality and consistency
Refactoring existing test suites
Configuring PHPUnit XML settings
Setting up code coverage and test organization

在以下场景中参考这些指南：

编写新的PHPUnit测试类或测试方法
评审测试代码的质量与一致性
重构现有测试套件
配置PHPUnit XML设置
搭建代码覆盖率与测试组织体系

Rule Categories by Priority

按优先级排序的规则类别


principle-
standard-
attr-
data-
doc-
mock-
integration-
config-

Priority	Category	Impact	Prefix
1	Principles & Patterns	CRITICAL	`principle-`
2	Coding Standards	CRITICAL	`standard-`
3	Test Attributes	HIGH	`attr-`
4	Data Management	HIGH	`data-`
5	Test Documentation	MEDIUM	`doc-`
6	Mocking	MEDIUM	`mock-`
7	Integration Testing	MEDIUM	`integration-`
8	Configuration	LOW-MEDIUM	`config-`


principle-
standard-
attr-
data-
doc-
mock-
integration-
config-

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

Quick Reference

快速参考

1. Principles & Patterns (CRITICAL)

1. 原则与模式（严重影响）

rules/principle-aaa-pattern.md - Structure tests with Arrange-Act-Assert
rules/principle-first-fast.md - Keep tests fast
rules/principle-first-isolated.md - Ensure tests are independent
rules/principle-first-repeatable.md - Make tests deterministic
rules/principle-first-self-validating.md - Tests must have clear pass/fail
rules/principle-first-timely.md - Write tests alongside production code
rules/principle-dry-vs-damp.md - Balance DRY and readability in tests

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. Coding Standards (CRITICAL)

2. 编码规范（严重影响）

rules/standard-strict-types.md - Declare strict_types=1 in test files
rules/standard-final-classes.md - Make test classes final
rules/standard-snake-case-methods.md - Use snake_case for test method names
rules/standard-psr4-naming.md - Follow PSR-4 naming and namespace conventions
rules/standard-psr12-formatting.md - Apply PSR-12 code formatting
rules/standard-this-over-self.md - Use $this over self:: for assertions
rules/standard-visibility-type-hints.md - Explicit visibility and type hints

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. Test Attributes (HIGH)

3. 测试属性（高影响）

rules/attr-test-attribute.md - Use #[Test] attribute with it_ prefix
rules/attr-covers-class.md - Use #[CoversClass] for coverage boundaries
rules/attr-uses-class.md - Use #[UsesClass] for dependency documentation
rules/attr-size-categories.md - Categorize tests by size
rules/attr-group.md - Use #[Group] for arbitrary categorization
rules/attr-no-annotations.md - Prefer PHP 8 attributes over PHPDoc annotations

rules/attr-test-attribute.md - 使用带it_前缀的#[Test]属性
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. Data Management (HIGH)

4. 数据管理（高影响）

rules/data-provider.md - Use #[DataProvider] for multiple scenarios
rules/data-provider-external.md - Use #[DataProviderExternal] for shared data
rules/data-test-with.md - Use #[TestWith] for inline datasets
rules/data-factory-method.md - Factory methods for SUT instantiation
rules/data-direct-instantiation.md - Direct instantiation for simple constructors

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. Test Documentation (MEDIUM)

5. 测试文档（中影响）

rules/doc-testdox.md - Use TestDox for executable specifications
rules/doc-testdox-attribute.md - #[TestDox] attribute for custom display
rules/doc-readable-names.md - Readable test names as specifications

rules/doc-testdox.md - 使用TestDox生成可执行规范
rules/doc-testdox-attribute.md - 使用#[TestDox]属性自定义展示名称
rules/doc-readable-names.md - 使用可读的测试名称作为规范说明

6. Mocking (MEDIUM)

6. Mocking（中影响）

rules/mock-chicago-vs-london.md - Chicago vs London TDD schools
rules/mock-prophecy.md - Prophecy for expressive test doubles
rules/mock-avoid-over-mocking.md - Avoid over-mocking internal dependencies

rules/mock-chicago-vs-london.md - 芝加哥派与伦敦派TDD的差异
rules/mock-prophecy.md - 使用Prophecy创建易读的测试替身
rules/mock-avoid-over-mocking.md - 避免过度Mock内部依赖

7. Integration Testing (MEDIUM)

7. 集成测试（中影响）

rules/integration-smoke-http.md - HTTP controller smoke tests
rules/integration-smoke-cli.md - CLI command smoke tests
rules/integration-performance.md - Performance-aware test setup
rules/integration-singleton.md - Singletons for stateless services
rules/integration-transactions.md - Database transactions for test cleanup

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. Configuration (LOW-MEDIUM)

8. 配置（低-中影响）

rules/config-testsuites.md - Organize tests in named suites
rules/config-strictness.md - Enable strict mode settings
rules/config-source-coverage.md - Source directory for coverage analysis
rules/config-order-by.md - Test execution ordering strategies
rules/config-cache.md - Cache directory for performance
rules/config-stop-on-failure.md - Stop on first failure for fast feedback

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 - 首次失败时停止执行以快速反馈

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单独的规则文件获取详细说明与代码示例：

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

每个规则文件包含：

规则重要性的简要说明
错误代码示例与说明
正确代码示例与说明
额外上下文与参考资料