PHPUnit

https://docs.phpunit.de/en/12.4
Admin
PHPUnit is a programmer-oriented testing framework for PHP that provides assertion methods, test...
Tokens:147,015
Snippets:935
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example test class using setUp() and tearDown()

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

Shows a test class that creates a fixture in setUp() and cleans up in tearDown(). These methods run once per test method on fresh instances.

```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.4/fixtures.html

An abstract test case class that defines a setUp() method. This is used as a base for concrete test cases.

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

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

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

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

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

Use this command to write event information with resource consumption details: time since test runner start, time since previous event, and memory usage. The example uses --no-output and --log-events-verbose-text php://stdout. The output includes timestamps and memory usage for each event, and ends with a shell exit code of 1.

```bash
phpunit --no-output --log-events-verbose-text php://stdout
[00:00:00.000046482 / 00:00:00.000006987] [4194304 bytes] PHPUnit Started (PHPUnit 10.0.0 using PHP 8.2.1 (cli) on Linux)
[00:00:00.048195557 / 00:00:00.048149075] [4194304 bytes] Test Runner Configured
[00:00:00.067646038 / 00:00:00.019450481] [6291456 bytes] Test Suite Loaded (2 tests)
[00:00:00.075942220 / 00:00:00.008296182] [6291456 bytes] Event Facade Sealed
[00:00:00.076452360 / 00:00:00.000510140] [6291456 bytes] Test Runner Started
[00:00:00.084421682 / 00:00:00.007969322] [6291456 bytes] Test Suite Sorted
[00:00:00.084664485 / 00:00:00.000242803] [6291456 bytes] Test Runner Execution Started (2 tests)
[00:00:00.085240320 / 00:00:00.000575835] [6291456 bytes] Test Suite Started (ExampleTest, 2 tests)
[00:00:00.086992385 / 00:00:00.001752065] [6291456 bytes] Test Preparation Started (ExampleTest::testOne)
[00:00:00.087443560 / 00:00:00.000451175] [6291456 bytes] Test Prepared (ExampleTest::testOne)
[00:00:00.088237489 / 00:00:00.000793929] [6291456 bytes] Assertion Succeeded (Constraint: is true)
[00:00:00.089076305 / 00:00:00.000838816] [6291456 bytes] Test Passed (ExampleTest::testOne)
[00:00:00.091027624 / 00:00:00.001951319] [6291456 bytes] Test Finished (ExampleTest::testOne)
[00:00:00.091110095 / 00:00:00.000082471] [6291456 bytes] Test Preparation Started (ExampleTest::testTwo)
[00:00:00.091158739 / 00:00:00.000048644] [6291456 bytes] Test Prepared (ExampleTest::testTwo)
[00:00:00.091991799 / 00:00:00.000833060] [6291456 bytes] Assertion Failed (Constraint: is identical to 'foo', Value: 'bar')
[00:00:00.099242925 / 00:00:00.007251126] [8388608 bytes] Test Failed (ExampleTest::testTwo)
                                                          Failed asserting that two strings are identical.
[00:00:00.099386498 / 00:00:00.000143573] [8388608 bytes] Test Finished (ExampleTest::testTwo)
[00:00:00.099437634 / 00:00:00.000051136] [8388608 bytes] Test Suite Finished (ExampleTest, 2 tests)
[00:00:00.103014760 / 00:00:00.003577126] [8388608 bytes] Test Runner Execution Finished
[00:00:00.103207309 / 00:00:00.000192549] [8388608 bytes] Test Runner Finished
[00:00:00.105879902 / 00:00:00.002672593] [8388608 bytes] PHPUnit Finished (Shell Exit Code: 1)
```

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

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

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

Example 2.9: A test case class DatabaseTest that skips the test if the pgsql extension is not loaded. The markTestSkipped() method is called in the setUp() method with a message. Skipped tests are denoted by 'S' in the output.

```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
    {
        // ...
    }
}
```

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

### Install PHPUnit with Composer

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

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

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

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

### Project directory structure after Composer install

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

Shows the expected directory layout after installing PHPUnit with Composer.

```text
├── composer.json
├── composer.lock
├── public
├── src
├── tests
└── vendor
```

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

### Install PHP 8.2 via Homebrew on macOS

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

Install PHP 8.2 using the shivammathur/php formula. The extensions required by PHPUnit (dom, json, libxml, mbstring, xml, xmlwriter) are already installed and enabled by default.

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

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

### Project directory after installing PHPUnit

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

Shows the resulting project structure after running 'phive install phpunit'. The tools/phpunit entry is a symbolic link to the cached PHAR.

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

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

### assertStringEqualsFile() test example

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

Example test class demonstrating assertStringEqualsFile(). The test expects the file 'expected.txt' to contain the string 'actual', which will fail and produce the shown output.

```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',
        );
    }
}

```

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

### phars.xml with version constraint ^9.6 and installed 9.6.3

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

Example .phive/phars.xml file after updating to PHPUnit 9.6.3. Used as the starting point for considering a major version upgrade.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<phive xmlns="https://phar.io/phive">
  <phar name="phpunit"
        version="^9.6" installed="9.6.3"
        location="./tools/phpunit" copy="true"/>
</phive>
```

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

### phars.xml with version constraint ^9.6 and installed 9.6.0

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

Example .phive/phars.xml file showing a semantic version constraint for PHPUnit 9.6.0. Used as the starting point for checking and applying updates.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<phive xmlns="https://phar.io/phive">
  <phar name="phpunit"
        version="^9.6" installed="9.6.0"
        location="./tools/phpunit" copy="true"/>
</phive>
```

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

### Verify PHP installation with php --version

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

Run php --version to verify that the PHP command-line interpreter is on the path, works, and to check its version.

```bash
php --version
```

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

### assertStringStartsWith() usage example

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

Example test class demonstrating assertStringStartsWith() with a failing case where the string 'foo' does not start with 'prefix'. The expected failure message is 'Failed asserting that 'foo' starts with "prefix".'

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

final class StringStartsWithTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertStringStartsWith('prefix', 'foo');
    }
}
```

```text
./tools/phpunit tests/StringStartsWithTest.php
PHPUnit 12.3.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.12

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 MB

There was 1 failure:

1) StringStartsWithTest::testFailure
Failed asserting that 'foo' starts with "prefix".

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

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

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

### Command to run GreeterTest and its output

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

Shows the command to run the test and the expected output, including the PHPUnit version, runtime, and success message.

```bash
./tools/phpunit tests/GreeterTest.php
```

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

Runtime:       PHP 8.4.12

.                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 MB

OK (1 test, 1 assertion)
```

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

### Set $_GET value with <get>

Source: https://docs.phpunit.de/en/12.4/configuration.html

Use the <get> element to set a value in the $_GET super-global array. The XML example corresponds to the PHP code $_GET['foo'] = 'bar';.

```XML
<php>
  <get name="foo" value="bar"/>
</php>
```

```PHP
$_GET['foo'] = 'bar';
```

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

### ExampleExtension class implementing Extension interface

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

This snippet shows a complete PHPUnit extension class. It implements the Extension interface and uses the bootstrap() method to check configuration, read a 'message' parameter, and register an ExampleSubscriber and ExampleTracer. The extension returns early if no output is configured.

```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 9.4 phpunit.xml

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

PHPUnit configuration file that sets up the test suite and bootstrap. It defines a default test suite that includes the tests directory.

```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>
```

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

### Project directory after --copy install

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

Shows the project structure after using the --copy option, where tools/phpunit is a regular file rather than a symlink.

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

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

### Print composer.lock with --composer-lock

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

Invoke PHPUnit's PHAR with the --composer-lock CLI option to print the composer.lock file used to install PHPUnit's dependencies during the PHAR build. The output is truncated in the example.

```bash
php phpunit-10.5.1.phar --composer-lock
{
    "_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
        "This file is @generated automatically"
    ],
    "content-hash": "e06728e5442edec84af96f94a889b4a7",
    .
    .
    .
```

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

### Using createConfiguredStub() to create a test stub and configure return values

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

Demonstrates the createConfiguredStub() method, which is a convenience wrapper around createStub() that allows configuring return values via an associative array. The test verifies that the configured methods return the expected values.

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

final class CreateConfiguredStubExampleTest extends TestCase
{
    public function testCreateConfiguredStub(): void
    {
        $o = $this->createConfiguredStub(
            SomeInterface::class,
            [
                'doSomething'     => 'foo',
                'doSomethingElse' => 'bar',
            ],
        );

        // $o->doSomething() now returns 'foo'
        $this->assertSame('foo', $o->doSomething());

        // $o->doSomethingElse() now returns 'bar'
        $this->assertSame('bar', $o->doSomethingElse());
    }
}
```

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

### Command-line output for incomplete test

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

Example output from running PHPUnit with --display-incomplete, showing the 'I' marker and the incomplete test report.

```bash
./tools/phpunit --display-incomplete tests/WorkInProgressTest.php
PHPUnit 12.3.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.12

I                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 MB

There was 1 incomplete test:

1) WorkInProgressTest::testSomething
This test has not been implemented yet.

/path/to/tests/WorkInProgressTest.php:12

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

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

### Listing available test suites with --list-suites

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

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

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

Available test suite(s):
 - unit
 - integration
```

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

### Typical PHP project directory structure

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

Shows the recommended directory layout for a PHP project with public, src, tests, and tools directories.

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

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

### Install Phive

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

Commands to download and verify the Phive PHAR, make it executable, and move it to /usr/local/bin. Requires wget, gpg, and the Phive signing key 0x9B2D5D79.

```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
```

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

### Install xdebug extension via Homebrew on macOS

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

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

```bash
brew install xdebug@8.2
```

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

### Install pcov extension via Homebrew on macOS

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

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

```bash
brew install pcov@8.2
```

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

### Configure extension bootstrap parameters

Source: https://docs.phpunit.de/en/12.4/configuration.html

Passes parameters to the extension for bootstrapping using the parameter element with name and value attributes.

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

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

### phive install phpunit@^10.0 to upgrade to major version

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

Command and output for explicitly installing a new major version (PHPUnit 10) using the install command with an explicit version constraint. This is required because major version updates are not offered by phive outdated.

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

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

### assertJsonStringEqualsJsonFile() failure output

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

Command-line output when running the assertJsonStringEqualsJsonFile() example. Shows the diff between expected and actual JSON.

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

Runtime:       PHP 8.4.12

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 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.
```

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

### Download and move PHPUnit PHAR to tools directory

Source: https://docs.phpunit.de/en/12.4/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-10.phar
chmod +x phpunit.phar
mv phpunit.phar tools
```

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

### assertXmlStringEqualsXmlString() usage example

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

Example test that compares two XML strings. Fails if the XML documents are not equal, producing a diff of the DOM documents.

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

final class XmlStringEqualsXmlStringTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlStringEqualsXmlString(
            '<foo><bar/></foo>',
            '<foo><baz/></foo>',
        );
    }
}
```

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

### assertXmlFileEqualsXmlFile() usage example

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

Example test that compares two XML files. Fails if the XML documents are not equal, producing a diff of the DOM documents.

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

final class XmlFileEqualsXmlFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlFileEqualsXmlFile(
            __DIR__ . '/expected.xml',
            __DIR__ . '/actual.xml',
        );
    }
}
```

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

### Concrete test case class extending abstract class with setUp()

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

A concrete test case that extends an abstract test case and overrides setUp(). If parent::setUp() is not called, the parent's functionality is lost.

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

use PHPUnit\Framework\TestCase;

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

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

### assertJsonFileEqualsJsonFile() failure output

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

Command-line output when running the assertJsonFileEqualsJsonFile() example. Shows the diff between expected and actual JSON.

```text
./tools/phpunit tests/JsonFileEqualsJsonFileTest.php
PHPUnit 12.3.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.12

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 MB

There was 1 failure:

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

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

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

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

### assertXmlStringEqualsXmlFile() usage example

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

Example test that compares an XML string to an XML file. Fails if the XML documents are not equal, producing a diff of the DOM documents.

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

final class XmlStringEqualsXmlFileTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertXmlStringEqualsXmlFile(
            __DIR__ . '/expected.xml',
            '<foo><baz/></foo>',
        );
    }
}
```

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

### Configure logging with junit, teamcity, testdoxHtml, and testdoxText

Source: https://docs.phpunit.de/en/12.4/configuration.html

Example configuration for the <logging> element, enabling JUnit XML, TeamCity, TestDox HTML, and TestDox text log outputs. Each child element uses the outputFile attribute to specify the destination file.

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

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

### assertStringMatchesFormat usage example

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

Example test using assertStringMatchesFormat('%i', 'foo') which fails because 'foo' is not a signed integer. The expected output shows the failure message and diff.

```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.3.11 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.12

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 15.81 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.

```

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

### assertEquals() with arrays - test failure example

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

Example 1.11: A PHPUnit test that uses assertEquals() to compare two arrays with different values, causing a failure.

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

final class EqualsWithArraysTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEquals(['a', 'b', 'c'], ['a', 'c', 'd']);
    }
}
```

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

### Invoke project-local PHPUnit

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

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

```bash
./vendor/bin/phpunit --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
```
Tokens:
Raw