PHPUnit Upgrades Without Surprises

What it is about

The new version of PHPUnit is out. Your test suite still runs on the old one, and you do not know what will break when you switch. Perhaps it depends on methods that no longer exist, on behaviour that has changed, or on an extension that does not support the new version yet. The longer you wait, the larger the gap becomes.

In two sessions you bring your test suite to the new version. In the first, you find out what stands in the way of your upgrade and fix it while your tests still run on the old version. In the second, you switch, understand what turns red afterwards and what has changed silently, and decide how your test suite stays free of deprecations until the next upgrade.

How you work

The two sessions are the two sides of the switch: the first works on the old version and cleans up, the second switches. What the old version already reports as a deprecation, you fix while the tests still run; after the switch, only the changes that came without a warning remain.

Sebastian first shows every step in live coding on an exercise project, then you carry it over to your own test suite or to the exercise project. Along the way you learn why PHPUnit deprecates and removes functionality and how to see early what is coming. If you are several major versions behind, you take the same path several times; this is discussed in the second session, but not practised.

Programme

1. 1

   Session 1: Taking stock and cleaning up

   What stands in the way of your upgrade, and what can you fix while still on the old version?

   • How PHPUnit deprecates and removes functionality: first in the documentation, then with a message at runtime, finally removed with the next major version; and where you can see early what is coming
   • How long a major version receives bug fixes
   • First to the latest version of last year's major version, because it reports what the next major version removes
   • Making PHPUnit deprecations visible (--display-phpunit-deprecations) and telling them apart from deprecations from PHP and from dependencies
   • Further obstacles: the PHP version the new major version requires, extensions and tools around PHPUnit, version constraints in Composer, your own extensions built on the event system
   • Fixing deprecations by hand, with Rector, and with a coding agent, and checking that a migrated test still fails when the code is wrong

   Result: A list of the obstacles to your upgrade, ordered by effort, and the first deprecations fixed, with tests that demonstrably still fail when the code is wrong

2. 2

   Session 2: The switch

   What turns red after the switch, what changes silently, and how do you stay on the current version?

   • The switch: adjusting the version constraint in Composer, migrating the XML configuration to the new schema with --migrate-configuration, running the test suite
   • What turns red afterwards, and why: removed methods and options, also in scripts and in the CI configuration
   • Changed behaviour that triggers no error, such as #[Group] on a parent class, and how to find it with --list-tests before and after the switch
   • Adapting your own extensions to changed events and constraints
   • Several major versions behind: one after the other, because only the previous version reports what the next one removes
   • Staying on the current version: fixing new deprecations during the year, adopting minor releases continuously, and letting PHPUnit deprecations fail the test suite

   Result: The exercise project on PHPUnit 14, the changed test selection found, and a roadmap for your own test suite that keeps the next upgrade small

Who it is for

• Developers and teams who need to bring a grown test suite to the new version of PHPUnit
• Tech leads who want to estimate and plan the effort of the upgrade
• Everyone who maintains extensions for PHPUnit

Prerequisites

• Experience with PHPUnit
• For the exercises: a test suite of your own on last year's version of PHPUnit or the exercise project, plus the PHP version the new version of PHPUnit requires, locally or in the container provided
• If your project still runs on a PHP version that PHPUnit 14 does not support, you work on your own test suite in the first session and on the exercise project in the second

What you take away

• You know what stands in the way of upgrading your test suite and how much work it is
• You fix deprecations deliberately, also with Rector and coding agents, and check the result
• You bring your test suite to the new version without surprises
• You have a roadmap that keeps the next upgrade small

Related training

This training is part of the learning path Staying up to date.