Enables type-safe comparisons of objects in PHPUnit

7.11.4 2024-02-26 13:22 UTC


Enables type-safe comparisons of objects in PHPUnit.


PHPUnit has a very powerful comparison system that helps you comparing objects with expected values:

class ValueObject
    public ?string $property;
    public function __construct(?string $property)
        $this->property = $property;

$actual = new ValueObject('foo!');

self::assertEquals(new ValueObject('foo'), $actual);
// => fails with a very helpful error message

This comparison system will give you a meaningful exception that guides you precisely to the problem that caused the assertion to fail. Strings are furthermore diffed so that you see exactly which character of the string causes a mismatch.

PHPUnit compares each scalar property of an object with relaxed types. It is a little more intelligent than using just == under the hood, but still that will not always provide the results you want:

var_dump('Hi' == true);
// => true

self::assertEquals(new ValueObject('Hi'), new ValueObject(true));
// => fails

var_dump('' == null);
// => true

self::assertEquals(new ValueObject(''), new ValueObject(null));
// => succeeds


This extension enables a comparator for scalar values that fights this problem. With this extension, whenever PHPUnit finds a scalar value during assertEquals() (even recursively within objects or arrays), it will compare the value with ===.

Objects are still not checked for identity, hence you can still construct example objects to compare against.

Error messages stay meaningful.

self::assertEquals(new ValueObject(''), new ValueObject(null));
// => fails with a meaningful error

self::assertEquals(new ValueObject('foo!'), new ValueObject('foo'));
// => fails with a meaningful error

self::assertEquals(new ValueObject('foo!'), new ValueObject('foo!'));
// => succeeds


The extension can be installed with Composer:

$ composer require --dev webmozarts/strict-phpunit

Add the extension to your phpunit.xml.dist file to enable it:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    <!-- ... -->
        <extension class="Webmozarts\StrictPHPUnit\StrictPHPUnitExtension"/>
    <!-- ... -->



Contributions to the package are always welcome!

Note that this repository is a subtree-split of a monorepo and hence read only. PRs will be ported to the (internal) monorepo.


All contents of this package are licensed under the MIT license.