9. Error Handling

PHPUnit’s test runner registers an error handler and processes E_DEPRECATED, E_USER_DEPRECATED, E_NOTICE, E_USER_NOTICE, E_STRICT, E_WARNING, and E_USER_WARNING errors. We will use the term “issues” to refer to E_DEPRECATED, E_USER_DEPRECATED, E_NOTICE, E_USER_NOTICE, E_STRICT, E_WARNING, and E_USER_WARNING errors for the remainder of this chapter.

The error handler is only active while a test is running and only processes issues triggered by test code or code that is called from test code. It ignores issues triggered by PHPUnit’s own code as well as code from PHPUnit’s dependencies.

Other error handlers

When PHPUnit’s test runner becomes aware (after it called set_error_handler() to register its error handler) that another error handler was registered then it immediately unregisters its error handler so that the previously registered error handler remains active. Consequently, the features described in this chapter are not available when you use your own error handler.

Your own error handler should follow best practices

Your own error handler should ignore errors emitted by code it is not responsible for, for instance PHPUnit’s code.

The error handler emits events that are, for instance, subscribed to and used by the default progress and result printers as well as loggers.

Here is the code that we will use for the examples in the remainder of this chapter:

.
├── phpunit.xml
├── src
│   └── SourceClass.php
├── tests
│   └── SourceClassTest.php
└── vendor
    ├── autoload.php
    └── VendorClass.php

4 directories, 5 files
Example 9.1 tests/SourceClassTest.php
<?php declare(strict_types=1);
namespace example;

use PHPUnit\Framework\TestCase;

final class SourceClassTest extends TestCase
{
    public function testSomething(): void
    {
        (new SourceClass)->doSomething();
        (new SourceClass)->doSomething();

        $this->assertTrue(true);
    }
}
Example 9.2 src/SourceClass.php
<?php declare(strict_types=1);
namespace example;

use vendor\VendorClass;

final class SourceClass
{
    public function doSomething(): void
    {
        trigger_error('deprecation', E_USER_DEPRECATED);

        (new VendorClass)->doSomething();
    }
}
Example 9.3 vendor/VendorClass.php
<?php declare(strict_types=1);
namespace vendor;

final class VendorClass
{
    public function doSomething(): void
    {
        trigger_error('deprecation', E_USER_DEPRECATED);
    }
}
Example 9.4 phpunit.xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         cacheDirectory=".phpunit.cache"
>
    <testsuites>
        <testsuite name="default">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
</phpunit>

PHPUnit’s test runner prints D, N, and W, respectively, for tests that execute code which triggers an issue (D for deprecations, N for notices, and W for warnings).

Shown below is the default output PHPUnit’s test runner prints for the example shown above:

$ ./tools/phpunit
PHPUnit 10.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.10
Configuration: /path/to/example/phpunit.xml

D                                                                   1 / 1 (100%)

Time: 00:00.007, Memory: 4.00 MB

OK, but there were issues!
Tests: 1, Assertions: 1, Deprecations: 2.

Detailed information, for instance which issue was triggered where, is only printed when --display-deprecations, --display-notices, or --display-warnings is used:

$ ./tools/phpunit --display-deprecations
PHPUnit 10.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.10
Configuration: /path/to/example/phpunit.xml

D                                                                   1 / 1 (100%)

Time: 00:00.006, Memory: 4.00 MB

1 test triggered 2 deprecations:

1) /path/to/example/src/SourceClass.php:10
deprecation

Triggered by:

* exampleSourceClassTest::testSomething (2 times)
  /path/to/example/tests/SourceClassTest.php:8

2) /path/to/example/vendor/VendorClass.php:8
deprecation

Triggered by:

* exampleSourceClassTest::testSomething (2 times)
  /path/to/example/tests/SourceClassTest.php:8

OK, but there were issues!
Tests: 1, Assertions: 1, Deprecations: 2.

Limiting issues to “your code”

The reporting of issues can be limited to “your code”, excluding third-party code from directories such as vendor, for example. You can configure what you consider “your code” in PHPUnit’s XML configuration file (see The <source> Element):

Example 9.5 phpunit.xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         cacheDirectory=".phpunit.cache"
>
    <testsuites>
        <testsuite name="default">
            <directory>tests</directory>
        </testsuite>
    </testsuites>

    <source restrictDeprecations="true"
            restrictNotices="true"
            restrictWarnings="true">
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>

Here is what the output of PHPUnit’s test runner will look like after we configured (see above) it to restrict the reporting of issues to our own code:

$ ./tools/phpunit --display-deprecations
PHPUnit 10.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.10
Configuration: /path/to/example/phpunit.xml

D                                                                   1 / 1 (100%)

Time: 00:00.007, Memory: 4.00 MB

1 test triggered 1 deprecation:

1) /path/to/example/src/SourceClass.php:10
deprecation

Triggered by:

* exampleSourceClassTest::testSomething (2 times)
  /path/to/example/tests/SourceClassTest.php:8

OK, but there were issues!
Tests: 1, Assertions: 1, Deprecations: 1.

As you can see in the output shown above, deprecations triggered in third-party code located in the vendor directory are not reported anymore.

Ignoring issue suppression

By default, the error handler registered by PHPUnit’s test runner respects the suppression operator (@). This means that issues triggered using @trigger_error(), for example, will not be reported by the default progress and result printers.

The suppression of issues using the suppression operator (@) can be ignored by configuration settings in PHPUnit’s XML configuration file:

Ignoring previously reported issues

PHPUnit’s test runner supports declaring the currently reported list of issues. Issues that are on this so-called baseline are no longer reported. This allows you to focus on new issues that are triggered by new or changed code.

When you run your test suite using the --generate-baseline CLI option then PHPUnit’s test runner will write a list of all issues that are triggered to an XML file:

$ phpunit --generate-baseline baseline.xml
PHPUnit 10.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.10
Configuration: /path/to/example/phpunit.xml

D                                                                   1 / 1 (100%)

Time: 00:00.008, Memory: 4.00 MB

OK, but there were issues!
Tests: 1, Assertions: 1, Deprecations: 1.

Baseline written to /path/to/example/baseline.xml.

When you run your test suite using the --use-baseline CLI option (or if you have configured a baseline in your XML configuration file for PHPUnit using the The <baseline> Attribute setting) then PHPUnit’s test runner will use this list of already known issues to ignore them for the current run:

$ phpunit --use-baseline baseline.xml
PHPUnit 10.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.10
Configuration: /path/to/example/phpunit.xml

.                                                                   1 / 1 (100%)

Time: 00:00.007, Memory: 4.00 MB

OK (1 test, 1 assertion)

2 issues were ignored by baseline.

Disabling PHPUnit’s error handler

When you want to test your own error handler or want to test that unit of code under test triggers an expected issue, for instance, the error handler registered by PHPUnit’s test runner will interfere with what you want to achieve.

The #[WithoutErrorHandler] attribute can be used in such a case to disable PHPUnit’s error handler for a test method.