Tests by Design
Next date: (in German)
Book · PHPStan extension · Agent skills
PHPUnit Best Practices
The PHPUnit manual tells you what every method, attribute, and configuration setting does. This book tells you which of them to reach for, and why.
- Coming in 2027
- Ebook in English
- With an extension for PHPStan
- With skills for coding agents
The manual is the reference, this book is the argument
The manual says what PHPUnit can do. It rarely says why one option is better than another. That knowledge exists, but it is scattered across admonitions in the manual, across articles and conference presentations, and across the experience of teams that have maintained a test suite for a decade. The book collects it in one place.
Every recommendation is stated as a rule, followed by the reason behind it. The reason matters more than the rule: a rule you understand can be broken deliberately when the situation calls for it, a rule you merely follow cannot.
Where a topic is documented in the manual, the book links to it instead of repeating it. Five of its thirteen chapters have no counterpart in the manual at all: analysing tests statically, changing code that has tests, keeping the test suite fast, keeping up with PHPUnit, and using the agent skills.
Every chapter starts from a moment in your work
In the book, every rule is a heading of its own. What each chapter comes down to:
- Structuring a test Choose between Arrange, Act, Assert and Arrange, Expect, Act
- Managing the test fixture Create the fixture where it is used
- Using test doubles Decide deliberately whether a test verifies the communication with a collaborator or only needs isolation from it
- Parameterising and relating tests Decouple test code from test data
- Reporting test outcomes honestly Distinguish finding flakiness from tolerating it
- Declaring what a test covers Keep code coverage accurate and honest
- Configuring a project Decide deliberately which issues fail the build
- Analysing tests statically Fix a violation, record a decision
- Changing code that has tests Treat a required change to an existing test as a signal
- Keeping the test suite fast Treat the test pyramid as a performance budget
- Keeping up with PHPUnit Make the upgrade to a new major version a one-line change
- Running PHPUnit from an agent Take the verdict from the exit code
- Using the agent skills Verify the work, not the transcript
A rule that a machine checks holds better than one that a reviewer has to remember
The PHPStan extension
Many of the rules can be checked by reading the code, before a single test runs. The extension reports where test code departs from them. The chapter tells you why that matters, and when departing from the rule is the right decision.
It is meant to be used together with phpstan/phpstan-phpunit and phpstan/phpstan-deprecation-rules, and the book shows how to adopt its rules on an existing test suite with a ratchet.
The agent skills
The skills state the same rules in the form a coding agent can act on, so that the tests written on your behalf follow them:
-
phpunit-testingwhen tests are written or reviewed -
phpunit-upgradefor the migration to a new major version -
phpunit-performancefor a test suite that has become slow - a snippet for the file your agent loads at the start of every session, such as
AGENTS.md
Together with the configuration of PHPUnit, this makes three layers, and each of them takes work off the next. The configuration reports what only a test run can show. PHPStan reports what the code shows. The skills are left with what neither of them can decide: whether a test verifies one aspect, whether a test stub or a mock object is the right double, whether an order is part of a contract.
The skills leave to the extension what it can check, and they make sure that it is installed and loaded. They do not replace the chapters: an agent that follows a rule it cannot justify will apply it in the wrong situation.
What the first readers say
“This is the definite ‘high-speed introduction to useful test-driven development’. It’s to the point, the examples are as short as possible, and every chapter clear as glass. The whole of it helps to reflect on how you’re using PHPUnit nowadays, and where you might want to rethink your habits and improve yourself, no matter how much work agents now do for you.”
“I have written a fair number of tests for a project I develop on the side, and both the book and the Skills for Claude have been a great help. Especially when you do not work with it every day and have not built up a routine yet, being able to look things up quickly is ideal. The explanations are clear, and so far no question has been left unanswered.”
Four training courses include the book
If you take part in one of these courses, you receive the book together with the PHPStan extension and the agent skills.
Agentic PHPUnit
Next date: (in German)
Test-Driven Development with AI Agents
Next date: (in German)
Saving Time and Tokens with PHPUnit
Next date: (in German)
Coming in 2027
The book cannot be ordered or pre-ordered yet. Until it is out, many of its topics are covered in the articles and presentations on this site.
Sebastian Bergmann is the creator of PHPUnit, the de facto standard for testing PHP code, and writes its manual. Since 2001 he has been helping teams build maintainable and well-tested software as a consultant and trainer, since 2009 as a co-founder of thePHP.cc.
