PHPUnit

https://docs.phpunit.de/en/12.5
Admin
PHPUnit is a unit testing framework for PHP that helps developers write and run automated tests for...
Tokens:171,622
Snippets:1,350
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example test class using setUp() and tearDown()

Source: https://docs.phpunit.de/en/12.5/fixtures.html

Shows a PHPUnit test class that creates a test fixture in setUp() and cleans it up in tearDown(). The setUp() method instantiates an Example object with a stub Collaborator, and tearDown() sets the property to null. These methods run once for each test method on fresh instances of the test case class.

```php
<?php declare(strict_types=1);
namespace example;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase
{
    private ?Example $example;

    public function testSomething(): void
    {
        $this->assertSame(
            'the-result',
            $this->example->doSomething()
        );
    }

    protected function setUp(): void
    {
        $this->example = new Example(
            $this->createStub(Collaborator::class)
        );
    }

    protected function tearDown(): void
    {
        $this->example = null;
    }
}

```

--------------------------------

### Abstract Test Case Class with setUp() Method

Source: https://docs.phpunit.de/en/12.5/fixtures.html

Example of an abstract test case class that defines a setUp() method. This is the base class that concrete test cases can extend.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

abstract class MyTestCase extends TestCase
{
    protected function setUp(): void
    {
        // ...
    }
}

```

--------------------------------

### Concrete Test Case Class Extending Abstract Class with setUp() Method

Source: https://docs.phpunit.de/en/12.5/fixtures.html

Example of a concrete test case class that extends an abstract test case class and overrides the setUp() method. If parent::setUp() is not called, the functionality provided by the abstract class will not work.

```php
<?php declare(strict_types=1);
namespace example;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends MyTestCase
{
    protected function setUp(): void
    {
        // ...
    }
}

```

--------------------------------

### Example of the <report> element with all report types

Source: https://docs.phpunit.de/en/12.5/xml-configuration-file.html

Shows a complete <report> element configuration with all supported report types and their attributes. This is the only code example on the page.

```XML
<report>
    <clover outputFile="clover.xml"/>
    <cobertura outputFile="cobertura.xml"/>
    <crap4j outputFile="crap4j.xml" threshold="50"/>
    <html outputDirectory="html-coverage" lowUpperBound="50" highLowerBound="90"/>
    <openclover outputFile="openclover.xml"/>
    <php outputFile="coverage.php"/>
    <text outputFile="coverage.txt" showUncoveredFiles="false" showOnlySummary="true"/>
    <xml outputDirectory="xml-coverage" includeSource="true"/>
</report>
```

--------------------------------

### Project directory after --copy install

Source: https://docs.phpunit.de/en/12.5/installation.html

Shows the project directory structure after installing PHPUnit with the --copy option. The tools/phpunit is a regular file, not a symbolic link.

```text
├── .phive
|   └── phars.xml
├── public
├── src
├── tests
└── tools
    └── phpunit
```

--------------------------------

### Install PHPUnit with Composer

Source: https://docs.phpunit.de/en/12.5/installation.html

Adds PHPUnit as a development-time dependency using Composer. Assumes Composer is installed and its executable is on $PATH.

```bash
composer require --dev phpunit/phpunit

```

--------------------------------

### assertJsonFileEqualsJsonFile() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.68: Test that compares two JSON files. Fails when the actual file does not match the expected file.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonFileEqualsJsonFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJsonFileEqualsJsonFile(
            __DIR__ . '/expected.json',
            __DIR__ . '/actual.json',
        );
    }
}

```

--------------------------------

### Skipping a test with markTestSkipped() in setUp()

Source: https://docs.phpunit.de/en/12.5/writing-tests-for-phpunit.html

Shows a test case class that skips the test if the pgsql extension is not loaded. The test is skipped by calling markTestSkipped() in the setUp() method.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class DatabaseTest extends TestCase
{
    protected function setUp(): void
    {
        if (!extension_loaded('pgsql')) {
            $this->markTestSkipped(
                'The PostgreSQL extension is not available',
            );
        }
    }

    public function testConnection(): void
    {
        // ...
    }
}

```

--------------------------------

### Default output for example

Source: https://docs.phpunit.de/en/12.5/error-handling.html

The default output from PHPUnit's test runner for the example, showing deprecation markers and summary.

```text
$ ./tools/phpunit
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

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

DD                                                                  1 / 1 (100%)

Time: 00:00.002, Memory: 8.00 MB

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

```

--------------------------------

### Install PHPUnit with Phive

Source: https://docs.phpunit.de/en/12.5/installation.html

Installs PHPUnit using Phive. After running this command, the project directory will contain a tools/phpunit symbolic link to the cached PHAR.

```bash
phive install phpunit
```

--------------------------------

### Plain Text TestDox Output Example

Source: https://docs.phpunit.de/en/12.5/testdox.html

Example output from the --testdox-text option, showing successful tests marked with [x] and defective tests with [ ].

```text
Greeter
 [x] Greets with name
 [x] Greets with good morning before noon
 [x] Greets with good afternoon after noon
 [x] Greets with good evening after 6 pm

```

--------------------------------

### Global installation of PHPUnit via PHAR

Source: https://docs.phpunit.de/en/12.5/installation.html

Downloads PHPUnit 12 PHAR, makes it executable, moves it to /usr/local/bin, and verifies the installation with --version. The output shows PHPUnit 12.5.0.

```bash
wget -O phpunit.phar https://phar.phpunit.de/phpunit-12.phar
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

```

--------------------------------

### createConfiguredStub() reference example

Source: https://docs.phpunit.de/en/12.5/test-doubles.html

Creates a test stub with methods already configured to return specific values. A convenience method for simple cases.

```php
$stub = $this->createConfiguredStub(
    InterfaceName::class,
    [
        'methodOne' => 'return value one',
        'methodTwo' => 'return value two',
    ]
);

// $stub->methodOne() will return "return value one"
// $stub->methodTwo() will return "return value two"

```

--------------------------------

### Example 10.4 phpunit.xml

Source: https://docs.phpunit.de/en/12.5/error-handling.html

PHPUnit configuration file that sets up the test suite and bootstrap.

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

```

--------------------------------

### Example extension registering an ExampleSubscriber and an ExampleTracer

Source: https://docs.phpunit.de/en/12.5/extending-phpunit.html

Shows a PHPUnit extension class implementing the Extension interface. The bootstrap method receives Configuration, Facade, and ParameterCollection. It checks noOutput, reads a 'message' parameter, and registers an ExampleSubscriber and ExampleTracer.

```php
<?php declare(strict_types=1);
namespace Vendor\ExampleExtensionForPhpunit;

use PHPUnit\Runner\Extension\Extension;
use PHPUnit\Runner\Extension\Facade;
use PHPUnit\Runner\Extension\ParameterCollection;
use PHPUnit\TextUI\Configuration\Configuration;

final class ExampleExtension implements Extension
{
    public function bootstrap(
        Configuration $configuration,
        Facade $facade,
        ParameterCollection $parameters
    ): void {
        if ($configuration->noOutput()) {
            return;
        }

        $message = 'the-default-message';

        if ($parameters->has('message')) {
            $message = $parameters->get('message');
        }

        $facade->registerSubscriber(new ExampleSubscriber($message));
        $facade->registerTracer(new ExampleTracer);
    }
}

```

--------------------------------

### Example 11.13: A test registering and using a custom comparator

Source: https://docs.phpunit.de/en/12.5/extending-phpunit.html

A PHPUnit test case that registers the MoneyComparator in setUp() and unregisters it in tearDown(). It includes a test method that uses assertEquals() to compare two Money objects with the same amount and currency.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;
use SebastianBergmann\Comparator\Factory;

final class MoneyComparatorTest extends TestCase
{
    private MoneyComparator $comparator;

    protected function setUp(): void
    {
        $this->comparator = new MoneyComparator;

        Factory::getInstance()->register($this->comparator);
    }

    protected function tearDown(): void
    {
        Factory::getInstance()->unregister($this->comparator);
    }

    public function testMoneyObjectsWithSameAmountAndCurrencyAreEqual(): void
    {
        $this->assertEquals(
            new Money(100, 'EUR'),
            new Money(100, 'EUR'),
        );
    }
}

```

--------------------------------

### Run PHPUnit with --log-events-verbose-text to include resource consumption in event log

Source: https://docs.phpunit.de/en/12.5/extending-phpunit.html

Use this command to write event logs with additional resource consumption details: time since test runner start, time since previous event, and memory usage. The output format includes these metrics in brackets before each event. The example shows a failing test with the assertion failure message.

```bash
phpunit --no-output --log-events-verbose-text php://stdout
[00:00:00.000009375 / 00:00:00.000009375] [26671776 bytes] PHPUnit Started (PHPUnit 12.5.34 using PHP 8.5.10 (cli) on Darwin)
[00:00:00.000231875 / 00:00:00.000222500] [26671776 bytes] Test Runner Configured
[00:00:00.000344292 / 00:00:00.000112417] [26671776 bytes] Event Facade Sealed
[00:00:00.000605500 / 00:00:00.000261208] [26671776 bytes] Test Suite Loaded (2 tests)
[00:00:00.000628875 / 00:00:00.000023375] [26671776 bytes] Test Runner Started
[00:00:00.000643083 / 00:00:00.000014208] [26671776 bytes] Test Suite Sorted
[00:00:00.000655000 / 00:00:00.000011917] [26671776 bytes] Test Runner Execution Started (2 tests)
[00:00:00.000666750 / 00:00:00.000011750] [26671776 bytes] Test Suite Started (ExampleTest, 2 tests)
[00:00:00.000716083 / 00:00:00.000049333] [26671776 bytes] Test Preparation Started (ExampleTest::testOne)
[00:00:00.000746167 / 00:00:00.000030084] [26267176 bytes] Test Prepared (ExampleTest::testOne)
[00:00:00.000933000 / 00:00:00.000186833] [26288088 bytes] Test Passed (ExampleTest::testOne)
[00:00:00.000974000 / 00:00:00.000041000] [26288088 bytes] Test Finished (ExampleTest::testOne)
[00:00:00.000991625 / 00:00:00.000017625] [26288088 bytes] Test Preparation Started (ExampleTest::testTwo)
[00:00:00.001014792 / 00:00:00.000023167] [26267984 bytes] Test Prepared (ExampleTest::testTwo)
[00:00:00.001171292 / 00:00:00.000156500] [26308432 bytes] Test Failed (ExampleTest::testTwo)
                                                           Failed asserting that two strings are identical.
[00:00:00.001201083 / 00:00:00.000029791] [26308432 bytes] Test Finished (ExampleTest::testTwo)
[00:00:00.001213375 / 00:00:00.000012292] [26308432 bytes] Test Suite Finished (ExampleTest, 2 tests)
[00:00:00.001223625 / 00:00:00.000010250] [26308432 bytes] Test Runner Execution Finished
[00:00:00.001231333 / 00:00:00.000007708] [26308432 bytes] Test Runner Finished
[00:00:00.001253292 / 00:00:00.000021959] [26308432 bytes] PHPUnit Finished (Shell Exit Code: 1)
```

--------------------------------

### assertStringEqualsFile() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Shows a PHPUnit test that calls assertStringEqualsFile() with an expected file and an actual string. When the string does not match the file contents, the test fails with a diff. The example is from Example 1.66.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringEqualsFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringEqualsFile(
            __DIR__ . '/expected.txt',
            'actual',
        );
    }
}

```

--------------------------------

### Example of <logging> element configuration

Source: https://docs.phpunit.de/en/12.5/xml-configuration-file.html

Shows how to configure multiple logging formats in the PHPUnit XML configuration file. Each child element specifies an output file for the respective format.

```xml
<logging>
    <junit outputFile="junit.xml"/>
    <otr outputFile="otr.xml" includeGitInformation="false"/>
    <teamcity outputFile="teamcity.txt"/>
    <testdoxHtml outputFile="testdox.html"/>
    <testdoxText outputFile="testdox.txt"/>
</logging>

```

--------------------------------

### Typical PHP project directory structure

Source: https://docs.phpunit.de/en/12.5/installation.html

Shows a typical directory layout with public, src, tests, and tools directories.

```text
├── public
├── src
├── tests
└── tools

```

--------------------------------

### Install PHP 8.3 via Homebrew

Source: https://docs.phpunit.de/en/12.5/installation.html

Install PHP 8.3 on macOS using Homebrew.

```bash
brew install shivammathur/php/php@8.3
```

--------------------------------

### Creating the system under test (PHPUnit)

Source: https://docs.phpunit.de/en/12.5/test-doubles.html

Instantiates the Service class with the test stub as its dependency, satisfying the Database type requirement.

```php
$service = new Service($database);

```

--------------------------------

### phive install phpunit@^12.5 for major update

Source: https://docs.phpunit.de/en/12.5/installation.html

Explicitly installs a new major version of PHPUnit using the install command with a new version constraint. This is required because major version updates are not offered by phive outdated.

```bash
phive install phpunit@^12.5
Phive 0.15.2 - Copyright (C) 2015-2024 by Arne Blankerts, Sebastian Heuer and Contributors
Linking /home/sb/.phive/phars/phpunit-12.5.34.phar to /path/to/tools/phpunit

```

--------------------------------

### Install xdebug extension via Homebrew

Source: https://docs.phpunit.de/en/12.5/installation.html

Install and enable the xdebug extension for code coverage on macOS.

```bash
brew install xdebug@8.3
```

--------------------------------

### Install pcov extension via Homebrew

Source: https://docs.phpunit.de/en/12.5/installation.html

Install and enable the pcov extension for code coverage on macOS.

```bash
brew install pcov@8.3
```

--------------------------------

### List available test suites with --list-suites

Source: https://docs.phpunit.de/en/12.5/organizing-tests.html

Uses the --list-suites option to print all test suites defined in the XML configuration file. The output lists the suite names, here 'unit' and 'integration'.

```bash
$ ./tools/phpunit --list-suites
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

Available test suite(s):
 - unit
 - integration

```

--------------------------------

### Install Phive

Source: https://docs.phpunit.de/en/12.5/installation.html

Downloads and verifies the Phive PHAR, then moves it to /usr/local/bin/phive. The commands use wget and gpg to download and verify the signature.

```bash
wget https://phar.io/releases/phive.phar
wget https://phar.io/releases/phive.phar.asc
gpg --keyserver hkps.pool.sks-keyservers.net --recv-keys 0x9B2D5D79
gpg --verify phive.phar.asc phive.phar
chmod +x phive.phar
mv phive.phar /usr/local/bin/phive
```

--------------------------------

### assertJsonStringEqualsJsonFile() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.69: Test that compares a JSON string to a JSON file. Fails when the string does not match the file content.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class JsonStringEqualsJsonFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertJsonStringEqualsJsonFile(
            __DIR__ . '/expected.json',
            json_encode(['mascot' => 'elephant']),
        );
    }
}

```

--------------------------------

### Subclass does not need to call parent::setUp()

Source: https://docs.phpunit.de/en/12.5/fixtures.html

Shows a concrete test class extending MyTestCase that defines its own #[Before] method. The test runner calls both setUpLogger() and setUpFixture() before testSomething() runs, without requiring an explicit parent::setUp() call.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\Attributes\Before;

final class MyTest extends MyTestCase
{
    #[Before]
    protected function setUpFixture(): void
    {
        // Set up the fixture for this test class ...
    }

    public function testSomething(): void
    {
        // Both setUpLogger() and setUpFixture() have been called at this point
        // ...
    }
}

```

--------------------------------

### Configure extension bootstrap parameters

Source: https://docs.phpunit.de/en/12.5/xml-configuration-file.html

Passes parameters to the extension during bootstrapping using the `parameter` element.

```XML
<extensions>
    <bootstrap class="Vendor\ExampleExtensionForPhpunit\Extension">
        <parameter name="message" value="the-message"/>
    </bootstrap>
</extensions>

```

--------------------------------

### Verify PHPUnit installation

Source: https://docs.phpunit.de/en/12.5/installation.html

Runs ./tools/phpunit --version to verify the installation. The output shows PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

```bash
./tools/phpunit --version
```

```text
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.
```

--------------------------------

### Install PHPUnit with --copy option

Source: https://docs.phpunit.de/en/12.5/installation.html

Installs PHPUnit using Phive's --copy option to copy the PHP archive from the cache into the project's tools directory, keeping it under version control.

```bash
phive install --copy phpunit
```

--------------------------------

### assertStringMatchesFormat() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.64 shows a test that fails because 'foo' does not match the format string '%i'. The output includes the diff between expected and actual.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class StringMatchesFormatTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringMatchesFormat('%i', 'foo');
    }
}

```

```text
./tools/phpunit tests/StringMatchesFormatTest.php
PHPUnit 12.5.34 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 28.00 MB

There was 1 failure:

1) StringMatchesFormatTest::testFailure
Failed asserting that string matches format description.
--- Expected
+++ Actual
@@ @@
-%i
+foo

/path/to/tests/StringMatchesFormatTest.php:8

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

```

--------------------------------

### assertObjectHasProperty() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.37: Shows a test that fails because the stdClass object does not have the property 'propertyName'. The test uses assertObjectHasProperty() and expects a failure.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class ObjectHasPropertyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertObjectHasProperty('propertyName', new stdClass);
    }
}

```

--------------------------------

### Creating the system under test

Source: https://docs.phpunit.de/en/12.5/test-doubles.html

Instantiates ServiceImplementation with the mock error handler injected, allowing isolated testing of the service.

```php
$service = new ServiceImplementation($errorHandler);

```

--------------------------------

### Download and move PHPUnit PHAR to tools directory

Source: https://docs.phpunit.de/en/12.5/installation.html

Downloads the PHAR, makes it executable, and moves it into the tools directory for per-project use.

```bash
wget -O phpunit.phar https://phar.phpunit.de/phpunit-12.phar
chmod +x phpunit.phar
mv phpunit.phar tools

```

--------------------------------

### any() example and equivalent stub configuration

Source: https://docs.phpunit.de/en/12.5/test-doubles.html

Sets an expectation that a method may be called zero or more times. The any() matcher is deprecated and will be removed in PHPUnit 14; use createStub() instead when you do not need to verify method calls. The second block shows the equivalent test stub configuration.

```php
$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->any())
    ->method('doSomething')
    ->willReturn('value');

```

```php
$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('value');

```

--------------------------------

### Project directory after installing PHPUnit

Source: https://docs.phpunit.de/en/12.5/installation.html

Shows the resulting project directory structure after installing PHPUnit with Phive. The tools/phpunit is a symbolic link to the cached PHAR.

```text
├── .phive
|   └── phars.xml
├── public
├── src
├── tests
└── tools
    └── phpunit -> ~/.phive/phars/phpunit-12.5.0.phar
```

--------------------------------

### Invoke project-local PHPUnit

Source: https://docs.phpunit.de/en/12.5/installation.html

Runs the project-local PHPUnit binary and shows its version output.

```bash
./vendor/bin/phpunit --version
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

```

--------------------------------

### assertFileExists() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.77: A PHPUnit test that fails because the file '/path/to/file' does not exist. The test class extends TestCase and uses strict types.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class FileExistsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertFileExists('/path/to/file');
    }
}

```

--------------------------------

### Run a specific test suite with --testsuite

Source: https://docs.phpunit.de/en/12.5/organizing-tests.html

Uses the --testsuite option to run only the tests of a specific suite declared in the XML configuration. The example runs the 'unit' suite and shows the corresponding output.

```bash
$ ./tools/phpunit --testsuite unit
PHPUnit 12.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.2
Configuration: /path/to/raytracer/phpunit.xml

...............................................................  63 / 172 ( 36%)
............................................................... 126 / 172 ( 73%)
..............................................                  172 / 172 (100%)

Time: 00:00.213, Memory: 24.27 MB

OK (172 tests, 637 assertions)

```

--------------------------------

### assertJsonStringEqualsJsonFile() failure output

Source: https://docs.phpunit.de/en/12.5/assertions.html

Output from running the assertJsonStringEqualsJsonFile() example. Shows the diff between expected and actual JSON.

```text
./tools/phpunit tests/JsonStringEqualsJsonFileTest.php
PHPUnit 12.5.34 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 28.00 MB

There was 1 failure:

1) JsonStringEqualsJsonFileTest::testFailure
Failed asserting that '{"mascot":"elephant"}' matches JSON string "{"mascot":"elePHPant"}
".
--- Expected
+++ Actual
@@ @@
{
-    "mascot": "elePHPant"
+    "mascot": "elephant"
}

/path/to/tests/JsonStringEqualsJsonFileTest.php:8

FAILURES!
Tests: 1, Assertions: 5, Failures: 1.

```

--------------------------------

### assertDirectoryIsReadable() usage example

Source: https://docs.phpunit.de/en/12.5/assertions.html

Example 1.75: A PHPUnit test that fails because the directory '/path/to/directory' is not readable. The test class extends TestCase and uses strict types.

```php
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class DirectoryIsReadableTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertDirectoryIsReadable('/path/to/directory');
    }
}

```
Tokens:
Raw