fabiensalles / phpstan-test-practices
PHPStan rules that check the shape of PHPUnit tests: assertions last, no guard assertions, literal expected values, one verified double, spies over mocks.
Package info
github.com/FabienSalles/phpstan-test-practices
Type:phpstan-extension
pkg:composer/fabiensalles/phpstan-test-practices
Requires
- php: ^8.2
- phpstan/phpstan: ^2.1.41
Requires (Dev)
- phpspec/prophecy-phpunit: ^2.3
- phpunit/phpunit: ^11.5 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 21:16:02 UTC
README
PHPStan rules that check the shape of PHPUnit tests: assertions last, no guard assertions, literal expected values, one verified double per test, spies over mocks.
A test earns trust in two dynamic ways: it fails when the implementation is removed, and it kills mutants (Infection). Both run the suite. This extension adds a cheaper, static level in front of them: it reads the test code and rejects the shapes that make a test lie or hard to read, in seconds, before anything runs. It does not replace the dynamic checks: a well-shaped test can still assert nothing useful.
Why a PHPStan extension and not Mago, Semgrep, a PHP_CodeSniffer standard or a PHPUnit test: see docs/why-phpstan.md.
Installation
composer require --dev fabiensalles/phpstan-test-practices
With phpstan/extension-installer the extension is registered automatically. Without it, include it in your phpstan.neon:
includes: - vendor/fabiensalles/phpstan-test-practices/extension.neon
Then analyse your tests (the rules only look at classes extending PHPUnit\Framework\TestCase, so analysing src/ alongside is harmless):
parameters: paths: - tests
The rules run at any PHPStan level. Your test base classes (Symfony KernelTestCase, etc.) must be discoverable by PHPStan, otherwise the test class is not recognised as a TestCase and is silently skipped.
Errors and warnings
PHPStan 2 has no severity: every reported error fails the analysis. This extension adds two levels:
- error: reported, exit code 1.
- warning: reported, exit code 0 when no error remains.
The extension sets PHPStan's errorFormat parameter to testPractices, an error formatter that prints the findings with an inner formatter (table by default), then returns 0 when every remaining finding is a warning. Each rule attaches its severity to the error as metadata. Any other PHPStan error, an internal error, or a configuration error keeps the inner formatter's exit code.
------ ---------------------------------------------------------------------
Line WarningOnlyTest.php
------ ---------------------------------------------------------------------
19 Test testLogsWithAMock() calls expects(), which sets a verification
before the act (mock). Prefer a spy verified after the act.
🪪 testPractices.spyOverMock
------ ---------------------------------------------------------------------
[ERROR] Found 1 error
Test practices: 0 blocking error(s), 1 non-blocking warning(s).
Passing --error-format=<name> on the command line bypasses the severity formatter, and every finding then fails the build. To keep severities with another output (for instance GitHub annotations in CI), set the inner formatter instead:
parameters: testPractices: errorFormat: github
If your configuration already sets errorFormat, set it back to testPractices and move your value to testPractices.errorFormat.
Configuration
All parameters with their defaults:
parameters: testPractices: level: max errorFormat: table diffBase: null severity: assertionsLast: error noGuardAssertion: error noComputedExpectedValue: error noProductionConstantAsExpected: error oneVerifiedDoublePerTest: error spyOverMock: warning preferInMemoryDouble: warning testMethodIsDiscoverable: error testClassSuffix: error testFileInTestsuite: error noTryCatchInTest: error noControlFlowInTest: error expectExceptionBeforeAct: error noDependsBetweenTests: error noFixtureInSetUp: warning permissiveStub: warning prophecyOverCreateMockCallback: warning dontMockWhatYouDontOwn: error noStubReturnAsExpected: error noUnusedDouble: error noTestOfLogging: warning frozenClock: error dataProviderNamedKeys: error exceptionTestNamesException: error structuredAssertion: warning builtInWebAssertions: warning noKernelForPureFunction: warning noTestCaseConstructor: error noReflectionOnSut: error noRandomness: error noDoubleOfEntityOrValueObject: error phpunitConfiguration: null testClassSuffix: suffix: Test dontMockWhatYouDontOwn: classes: - Doctrine\ORM\QueryBuilder - Doctrine\ORM\EntityManagerInterface - Doctrine\ORM\Query - Doctrine\DBAL\Connection - GuzzleHttp\ClientInterface - Symfony\Contracts\HttpClient\HttpClientInterface noTestOfLogging: enabled: false noDoubleOfEntityOrValueObject: patterns: - App\Entity\* - '*\ValueObject\*' preferInMemoryDouble: threshold: 2 assertionCount: warningFrom: 3 errorFrom: 4
| Parameter | Values | Meaning |
|---|---|---|
level |
0 to 3, max |
Which rules run, see levels |
errorFormat |
any PHPStan formatter name | Formatter that prints the findings |
diffBase |
null, any git revision |
Report only the findings on lines changed since this revision, see diff mode |
severity.<rule> |
error, warning |
Severity of each rule |
phpunitConfiguration |
null, a path |
PHPUnit configuration read by testFileInTestsuite; null looks for phpunit.xml, phpunit.dist.xml, phpunit.xml.dist in the working directory |
testClassSuffix.suffix |
string | Suffix every concrete test class must end with |
dontMockWhatYouDontOwn.classes |
list of class names | Third-party types that must not be doubled (subclasses and implementations included) |
noTestOfLogging.enabled |
bool | Turns on the opt-in noTestOfLogging rule |
noDoubleOfEntityOrValueObject.patterns |
list of fnmatch() patterns |
Classes that must be built, not doubled, besides Doctrine entities, enums and readonly classes |
preferInMemoryDouble.threshold |
int ≥ 1 | Number of test methods doubling the same class before it is reported |
assertionCount.warningFrom |
int ≥ 1 | Assertions per test from which a warning is reported |
assertionCount.errorFrom |
int ≥ 1 | Assertions per test from which an error is reported |
Rules
A test method is a public, non-static method of a TestCase subclass named test*, or carrying #[Test] or @test. Data providers (static) are never treated as tests. Assertions are assert* calls through self::, static::, SomeClass:: or $this->, and Prophecy spy verifications (shouldHaveBeenCalled(), shouldHaveBeenCalledTimes(), shouldHaveBeenCalledOnce(), shouldNotHaveBeenCalled(), shouldHave()).
Each rule has its own page: what it detects, a failing example with the real PHPStan output, a passing example, the reasoning behind it, its known limits, and the skill of the Claude Code marketplace that teaches the same practice.
| Identifier | Level | Default | Rationale |
|---|---|---|---|
testPractices.testFileInTestsuite |
0 | error | A test file no <testsuite> collects never runs |
testPractices.testClassSuffix |
0 | error | PHPUnit collects *Test.php files: a test class without the suffix never runs |
testPractices.testMethodIsDiscoverable |
0 | error | A method with assertions that is neither a test nor called by one never runs |
testPractices.assertionsLast |
0 | error | Arrange, act, assert: an assertion before the act, or hidden in an arrange callback, reads as a step of the scenario and fails with a confusing message |
testPractices.noComputedExpectedValue |
0 | error | An expected value computed with the same logic as the code passes by construction |
testPractices.noStubReturnAsExpected |
0 | error | Expecting what a stub returns checks the stub, not the code |
testPractices.noTryCatchInTest |
0 | error | A try/catch passes when nothing is thrown |
testPractices.expectExceptionBeforeAct |
0 | error | Statements after a throwing act never run |
testPractices.noGuardAssertion |
1 | error | A guard (assertCount, assertInstanceOf, assertNotNull, assertIs*...) stops the test before the real assertion shows its diff |
testPractices.noProductionConstantAsExpected |
1 | error | Comparing a production constant with itself never fails when its value changes |
testPractices.noControlFlowInTest |
1 | error | A branch or a loop in a test leaves some paths unchecked |
testPractices.noDependsBetweenTests |
1 | error | A dependent test cannot run alone and is skipped when the other fails |
testPractices.frozenClock |
1 | error | A test reading the system clock depends on when it runs |
testPractices.noUnusedDouble |
1 | error | An unused double is noise, or a forgotten argument of the act |
testPractices.noTestCaseConstructor |
1 | error | PHPUnit owns the constructor of a test case |
testPractices.noRandomness |
1 | error | A test drawing random values may behave differently on every run |
testPractices.oneVerifiedDoublePerTest |
2 | error | Several verified doubles mean several intentions in one test |
testPractices.assertionCount |
2 | 3: warning, 4+: error | One structured assertion reads better and fails with a complete diff; many assertions usually hide several intentions |
testPractices.structuredAssertion |
2 | warning | Two assertions on fields of one value hide the second difference |
testPractices.dontMockWhatYouDontOwn |
2 | error | A double of a library type copies how the library is called |
testPractices.dataProviderNamedKeys |
2 | error | An unnamed data set fails as "data set #0" |
testPractices.exceptionTestNamesException |
2 | error | An exception test names the error it expects |
testPractices.noReflectionOnSut |
2 | error | Reaching private state couples the test to how the class is written |
testPractices.noDoubleOfEntityOrValueObject |
2 | error | An entity or a value object is built, not doubled |
testPractices.spyOverMock |
3 | warning | A verification set before the act (mock) breaks arrange-act-assert; a spy verifies after the act |
testPractices.preferInMemoryDouble |
3 | warning | The same dependency doubled in several tests is a sign that a reusable in-memory implementation would be shorter and sturdier |
testPractices.noFixtureInSetUp |
3 | warning | Fixtures and doubles built in setUp() hide each scenario |
testPractices.permissiveStub |
3 | warning | A stub provides data; constraining its arguments is a hidden verification |
testPractices.prophecyOverCreateMockCallback |
3 | warning | A scripted PHPUnit double reads better as Prophecy promises |
testPractices.builtInWebAssertions |
3 | warning | Symfony's web assertions read better and fail with the response |
testPractices.noKernelForPureFunction |
3 | warning | Booting a kernel for plain objects is slow and couples the test to the container |
testPractices.noTestOfLogging |
3 | warning, opt-in | Logging is rarely the behaviour under test |
Four rules can fix what they report: noProductionConstantAsExpected (the constant becomes its literal value), noGuardAssertion (the guard is removed), spyOverMock for Prophecy expectations (moved after the act as a spy verification) and builtInWebAssertions for status codes (assertResponseStatusCodeSame()). Run vendor/bin/phpstan analyse --fix, review the diff, and rerun your code style fixer: PHPStan's printer may drop a blank line around a changed statement. Each rule page says whether it is auto-fixable and why.
Levels
testPractices.level selects the rules, from the ones that catch tests passing by construction to the opinionated ones:
| Level | Adds | Why at this level |
|---|---|---|
| 0 | testFileInTestsuite, testClassSuffix, testMethodIsDiscoverable, assertionsLast, noComputedExpectedValue, noStubReturnAsExpected, noTryCatchInTest, expectExceptionBeforeAct |
A test that never runs, an expectation that passes by construction (computed, or returned by a stub), an assertion that never executes (in the arrange, after a throwing act, in a skipped catch): each makes a test lie, with almost no false positive |
| 1 | noGuardAssertion, noProductionConstantAsExpected, noControlFlowInTest, noDependsBetweenTests, frozenClock, noUnusedDouble, noTestCaseConstructor, noRandomness |
Tautologies, hidden diffs, flaky or dependent tests and noise, with a few legitimate exceptions (a constant that is the contract, a loop building a fixture) |
| 2 | oneVerifiedDoublePerTest, assertionCount, structuredAssertion, dontMockWhatYouDontOwn, dataProviderNamedKeys, exceptionTestNamesException, noReflectionOnSut, noDoubleOfEntityOrValueObject |
Heuristics about intentions, naming and design: valuable, but thresholds, interaction-heavy tests and project conventions make exceptions more common |
3 (max, default) |
spyOverMock, preferInMemoryDouble, noFixtureInSetUp, permissiveStub, prophecyOverCreateMockCallback, builtInWebAssertions, noKernelForPureFunction, noTestOfLogging |
Design preferences, warnings by default |
parameters: testPractices: level: 1
The rules do not follow PHPStan's own level. PHPStan's levels are cumulative config.levelN.neon files that the command includes (CommandHelper); the level reaches the container only as the %usedLevel% string, and conditionalTags only cast each condition to a boolean (ConditionalTagsExtension), so NEON cannot express "from level 5". Type strictness and test shape are also unrelated scales. Each rule therefore reads testPractices.level and stays silent below its own level.
Adopting on an existing suite
Baseline
PHPStan's baseline works with every identifier of this extension and with both severities: a baselined error or warning disappears, and the exit code is computed on what remains (tests/Adoption/AdoptionTest.php runs the binary to pin this).
- Start at
level: 0, generate a baseline, commit it:vendor/bin/phpstan analyse --generate-baseline. New tests are checked from now on; existing findings are listed inphpstan-baseline.neon, by message, identifier, path and count. Since the message is part of each entry, a reworded message in a new version of this extension un-ignores the finding: regenerate the baseline after upgrading, or replace themessagekeys by theidentifieralone. - Fix the baseline down over time, then raise the level and regenerate.
- Keep
reportUnmatchedIgnoredErrors(on by default) so a fixed finding has to leave the baseline.
To exclude a whole legacy directory from one rule instead, use ignoreErrors with an identifier and a path.
Diff mode
testPractices.diffBase reports only the findings on lines changed since a git revision, for instance in a pull request job:
parameters: testPractices: diffBase: origin/main
The error formatter runs git diff --unified=0 <diffBase> in the working directory and keeps the findings whose line is in a changed hunk (added or modified lines, staged or not; untracked files are not in the diff until git add -N). The filter applies to every PHPStan error printed by the formatter, not only to this extension's. The analysis itself is unchanged: PHPStan still analyses all the configured paths, so the result cache stays valid and preferInMemoryDouble still sees the whole hierarchy. A preferInMemoryDouble finding is kept as soon as its file changed, since its line points to the first creation of the dependency, not to the test that was added.
Limiting the analysed files instead is possible with plain PHPStan, at a cost:
git diff --name-only --diff-filter=AM origin/main -- tests | xargs -r vendor/bin/phpstan analyse --no-progress
It is faster on a cold cache but reports every finding of the changed files, and preferInMemoryDouble only sees the parents and traits that are among them. PHPStan has no native option for either: its result cache re-analyses only changed files and their dependents, but still reports every finding.
Ignoring a finding
Use PHPStan's usual mechanisms with the rule identifier:
self::assertSame(Config::DEFAULT_LIMIT, $limit); // @phpstan-ignore testPractices.noProductionConstantAsExpected
parameters: ignoreErrors: - identifier: testPractices.spyOverMock path: tests/Legacy/*
A baseline works as well for an existing suite, see adopting on an existing suite.
Compatibility
Tested in this repository's CI matrix and locally with Docker:
| Lowest tested | Highest tested | |
|---|---|---|
| PHP | 8.2 | 8.4 |
| PHPStan | 2.1.41 | 2.3.5 |
| PHPUnit 11 (fixtures and test suite) | 11.5.50 | 11.5.58 |
| PHPUnit 12 (fixtures and test suite, PHP 8.3+) | 12.5.8 | 12.5.44 |
Prophecy (phpspec/prophecy) |
1.19.0 | 1.26.1 |
phpspec/prophecy-phpunit |
2.3.0 | 2.5.0 |
The matrix runs PHP 8.2 with PHPUnit 11, and PHP 8.3 and 8.4 with both PHPUnit 11 and 12, each with lowest and highest dependencies. The lowest PHPUnit versions are the oldest ones Composer installs: earlier releases are blocked by a security advisory.
The rules read the syntax of PHPUnit and Prophecy calls; they do not depend on a PHPUnit or Prophecy version at runtime. PHPUnit 12 no longer reads the @test annotation, but the rules still treat a method carrying it as a test.
License
MIT, see LICENSE.