PHPUnit Best Practices
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.
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
Rule Categories by Priority
| 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- |
Quick Reference
1. Principles & Patterns (CRITICAL)
- 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
2. Coding Standards (CRITICAL)
- 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
3. Test Attributes (HIGH)
- 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
4. Data Management (HIGH)
- 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
5. Test Documentation (MEDIUM)
- 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
6. Mocking (MEDIUM)
- 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
7. Integration Testing (MEDIUM)
- 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
8. Configuration (LOW-MEDIUM)
- 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
How to Use
Read individual rule files for detailed explanations and code examples:
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references