11. Extending PHPUnit

PHPUnit can be extended in various ways to make the writing of tests easier and customize the feedback you get from running tests. Here are common starting points to extend PHPUnit.

Subclass PHPUnit\Framework\TestCase

Write custom assertions and utility methods in an abstract subclass of PHPUnit\Framework\TestCase and derive your test case classes from that class. This is one of the easiest ways to extend PHPUnit.

Write custom assertions

When writing custom assertions it is the best practice to follow how PHPUnit’s own assertions are implemented. As you can see in Example 11.1, the assertTrue() method is a wrapper around the isTrue() and assertThat() methods: isTrue() creates a matcher object that is passed on to assertThat() for evaluation.

Example 11.1 The assertTrue() and isTrue() methods of the PHPUnit\Framework\Assert class

  1. <?php declare(strict_types=1);
  2. namespace PHPUnit\Framework;
  4. use PHPUnit\Framework\Constraint\IsTrue;
  6. abstract class Assert
  7. {
  8.     // ...
  10.     public static function assertTrue($condition, string $message = ''): void
  11.     {
  12.         static::assertThat($condition, static::isTrue(), $message);
  13.     }
  15.     // ...
  17.     public static function isTrue(): IsTrue
  18.     {
  19.         return new IsTrue;
  20.     }
  22.     // ...
  23. }

Example 11.2 shows how PHPUnit\Framework\Constraint\IsTrue extends the abstract base class for matcher objects (or constraints), PHPUnit\Framework\Constraint.

Example 11.2 The PHPUnit\FrameworkConstraint\IsTrue class

  1. <?php declare(strict_types=1);
  2. namespace PHPUnit\Framework\Constraint;
  4. use PHPUnit\Framework\Constraint;
  6. final class IsTrue extends Constraint
  7. {
  8.     public function toString(): string
  9.     {
  10.         return 'is true';
  11.     }
  13.     protected function matches($other): bool
  14.     {
  15.         return $other === true;
  16.     }
  17. }

The effort of implementing the assertTrue() and isTrue() methods as well as the PHPUnit\Framework\Constraint\IsTrue class yields the benefit that assertThat() automatically takes care of evaluating the assertion and bookkeeping tasks such as counting it for statistics. Furthermore, the isTrue() method can be used as a matcher when configuring mock objects.

Extending the TestRunner

PHPUnit’s test runner can be extended by registering objects that implement one or more of the following interfaces:

  • AfterIncompleteTestHook
  • AfterLastTestHook
  • AfterRiskyTestHook
  • AfterSkippedTestHook
  • AfterSuccessfulTestHook
  • AfterTestErrorHook
  • AfterTestFailureHook
  • AfterTestWarningHook
  • AfterTestHook
  • BeforeFirstTestHook
  • BeforeTestHook

Each “hook”, meaning each of the interfaces listed above, represents an event that can occur while the tests are being executed.

See The <extensions> Element for details on how to register extensions in PHPUnit’s XML configuration.

Example 11.3 shows an example for an extension implementing BeforeFirstTestHook and AfterLastTestHook:

Example 11.3 TestRunner Extension Example

  1. <?php declare(strict_types=1);
  2. namespace Vendor;
  4. use PHPUnit\Runner\BeforeFirstTestHook;
  5. use PHPUnit\Runner\AfterLastTestHook;
  7. final class MyExtension implements BeforeFirstTestHook, AfterLastTestHook
  8. {
  9.     public function executeBeforeFirstTest(): void
  10.     {
  11.         // called before the first test is being run
  12.     }
  14.     public function executeAfterLastTest(): void
  15.     {
  16.         // called after the last test has been run
  17.     }
  18. }

Configuring extensions

You can configure PHPUnit extensions, assuming the extension accepts configuration values.

Example 11.4 shows an example how to make an extension configurable, by adding an __constructor() definition to the extension class:

Example 11.4 TestRunner Extension with constructor

  1. <?php declare(strict_types=1);
  2. namespace Vendor;
  4. use PHPUnit\Runner\BeforeFirstTestHook;
  5. use PHPUnit\Runner\AfterLastTestHook;
  7. final class MyConfigurableExtension implements BeforeFirstTestHook, AfterLastTestHook
  8. {
  9.     protected $config_value_1 = '';
  11.     protected $config_value_2 = 0;
  13.     public function __construct(string $value1 = '', int $value2 = 0)
  14.     {
  15.         $this->config_value_1 = $config_1;
  16.         $this->config_value_2 = $config_2;
  17.     }
  19.     public function executeBeforeFirstTest(): void
  20.     {
  21.         if (strlen($this-config_value_1) {
  22.             echo 'Testing with configuration value: ' . $this->config_value_1;
  23.         }
  24.     }
  26.     public function executeAfterLastTest(): void
  27.     {
  28.         if ($this->config_value_2 > 10) {
  29.             echo 'Second config value is OK!';
  30.         }
  31.     }
  32. }

To input configuration to the extension via XML, the XML configuration file’s extensions section needs to be updated to have configuration values, as shown in Example 11.5:

Example 11.5 TestRunner Extension configuration

  1. <extensions>
  2.     <extension class="Vendor\MyUnconfigurableExtension" />
  3.     <extension class="Vendor\MyConfigurableExtension">
  4.         <arguments>
  5.             <string>Hello world!</string>
  6.             <int>15</int>
  7.         </arguments>
  8.     </extension>
  9. </extensions>

See The <arguments> Element for details on how to use the arguments configuration.

Remember: all configuration is optional, so make sure your extension either has sane defaults in place, or that it disables itself in case configuration is missing.