PHPUnit 13: New Array Assertions and Stricter Mock Checks

Contents

With PHPUnit 13, maintainer Sebastian Bergmann has released a new major version of the widely used testing framework for PHP. The release brings functional innovations, removes long-obsolete APIs, and raises technical requirements. According to the project, the goal is to formulate tests more clearly and reduce misunderstandings.

Current PHP Version Required

PHPUnit 13 requires PHP 8.4 or newer and excludes older PHP versions. For justification, PHPUnit refers to the current state of PHP development: Currently, the PHP developers are only actively developing PHP 8.4 and 8.5.

At the same time, PHPUnit advises a considered upgrade. The switch to a new major version should be made consciously. Those who still receive deprecation warnings with PHPUnit 12.5 should fix them first before switching to version 13.

New Assertions for Arrays

PHPUnit 13 complements the existing offering with new assertions for arrays. They are aimed at use cases where the previous methods assertSame() and assertEquals() do not differentiate finely enough between comparison requirements.

The new assertions allow array comparisons to be specified more precisely. It can be determined whether values are compared strictly, including types or merely by content, whether array keys should be considered, and whether the order of elements is relevant.

This provides PHPUnit with additional tools to express specific comparison scenarios more explicitly, for example, for comparisons independent of sorting or for strictly identical associative arrays.

Changes to Mock Objects

For mock objects, PHPUnit 13 changes the verification of passed parameters and says goodbye to the withConsecutive() method, which was previously used to check different parameters for consecutive method calls. It is replaced by two special rules that allow parameter sequences to be checked across multiple calls.

The previous approach encountered known limitations, such as the close dependency on a fixed call order and increasing complexity in more complex scenarios. Especially since PHPUnit 10, additional constructs were often necessary to map corresponding call sequences. The goal of the innovation is to formulate expectations for mock objects more clearly and to keep the associated checks more transparent.

Sealed Test Doubles as a New Option

So-called sealed test doubles have been added. With them, PHPUnit deliberately closes the configuration of mock or stub objects. A stub serves as a simple placeholder for a dependency and returns predefined values without checking calls. After calling seal(), neither further expectations nor additional methods can be defined. For mock objects, this also ensures that methods that are not explicitly expected are rejected.

PHPUnit introduces this feature as an optional addition. Existing tests remain runnable unchanged but can be deliberately set to be stricter if unexpected interactions should be detected early.

any()-Matcher Shortly Before Final Removal

The any() matcher is marked as “hard deprecated” in PHPUnit 13 (hard-deprecated). According to the announcement post, this is because mock objects are primarily intended for verifying concrete interactions. Those who do not want to verify calls should use stubs instead.

Support Periods and Outlook

According to the Übersichtsplan der Versionen (overview of versions), PHPUnit 13 will be supplied with bug fixes until February 2028. PHPUnit 12 will remain in support until February 2027, and older versions will no longer receive error corrections.

Several minor releases of the 13 series are planned for 2026. PHPUnit 14 is currently announced for February 2027. More detailed information on PHPUnit 13 can be found in the announcement post as well as in the changelog.

(mdo)