Search by

fabiensalles / phpstan-test-practices

FabienSalles

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

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-15 15:08 UTC

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).

  1. 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 in phpstan-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 the message keys by the identifier alone.
  2. Fix the baseline down over time, then raise the level and regenerate.
  3. 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.