PHPUnit

https://docs.phpunit.de/en/11.5
Admin
PHPUnit is a unit testing framework for PHP that enables developers to write and run automated tests...
Tokens:81,002
Snippets:993
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implement setUp and tearDown in a test class

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

Use setUp to initialize objects before each test and tearDown to clean them up afterward.

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

use PHPUnit	ypes\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;
    }
}
```

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

### Install PHPUnit with Copy Option

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

Command to install PHPUnit and copy the PHAR file directly into the project directory.

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

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

### Extend an abstract test case with setUp

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

Concrete test classes must call parent::setUp() to ensure inherited setup logic executes correctly.

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

use PHPUnit\Framework\TestCase;

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

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

### Install Phive

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

Commands to download, verify, and install the Phive PHAR manager.

```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 PHP CLI and extensions on Debian and Ubuntu

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

Use apt to install the PHP interpreter and required extensions for PHPUnit on Debian or Ubuntu systems.

```bash
sudo apt install php-cli \
                 php-json \
                 php-mbstring \
                 php-xml \
                 php-pcov \
                 php-xdebug
```

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

### Install PHP CLI and extensions on Fedora

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

Use dnf to install the PHP interpreter and required extensions for PHPUnit on Fedora.

```bash
sudo dnf install php-cli \
                 php-json \
                 php-mbstring \
                 php-process \
                 php-xml \
                 php-pecl-pcov \
                 php-pecl-xdebug
```

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

### assertStringStartsWith()

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

Reports an error if the provided string does not start with the specified prefix.

```APIDOC
## assertStringStartsWith(string $prefix, string $string[, string $message])

### Description
Reports an error identified by $message if the $string does not start with $prefix.

### Parameters
- **$prefix** (string) - Required - The expected prefix.
- **$string** (string) - Required - The string to check.
- **$message** (string) - Optional - Custom error message.
```

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

### Project directory structure

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

Shows the expected file layout after installing dependencies.

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

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

### Use setUp in an abstract test case

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

Abstract test classes can define shared setup logic that concrete test classes inherit.

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

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

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

### Install PHAR to Tools Directory

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

Download, make executable, and move the PHAR file into the project's tools directory.

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

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

### Install PHPUnit via Phive

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

Command to install PHPUnit into the project using Phive.

```bash
phive install phpunit
```

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

### Project Directory Structure

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

Example of a standard PHP project directory layout including a tools folder.

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

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

### Define static setup methods with @beforeClass

Source: https://docs.phpunit.de/en/11.5/annotations.html

Use @beforeClass to mark static methods that execute before any test methods in the class for shared fixture setup.

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

final class MyTest extends TestCase
{
    /**
     * @beforeClass
     */
    public static function setUpSomeSharedFixtures(): void
    {
        // ...
    }

    /**
     * @beforeClass
     */
    public static function setUpSomeOtherSharedFixtures(): void
    {
        // ...
    }
}
```

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

### Install PHP 8.2 on macOS

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

Install a specific version of PHP using the Homebrew formulae.

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

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

### Project Directory Structure

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

Example of a project layout where the tests/unit directory mirrors the source code structure.

```text
src                                          tests/unit
├── autoload.php                             ├── CameraTest.php
├── Camera.php                               ├── canvas
├── canvas                                   │   ├── AnsiMapperTest.php
│   ├── AnsiMapper.php                       │   ├── CanvasTest.php
│   ├── CanvasIterator.php                   │   └── PortablePixmapMapperTest.php
│   ├── Canvas.php                           ├── ColorTest.php
│   ├── PortablePixmapMapper.php             ├── intersection
│   └── WebpMapper.php                       │   ├── IntersectionCollectionTest.php
├── Color.php                                │   └── IntersectionTest.php
├── exceptions                               ├── material
│   ├── Exception.php                        │   ├── CheckersPatternTest.php
│   ├── IntersectionHasNoHitException.php    │   ├── GradientPatternTest.php
│   ├── InvalidArgumentException.php         │   ├── MaterialTest.php
│   ├── OutOfBoundsException.php             │   ├── PatternTest.php
│   ├── RuntimeException.php                 │   ├── RingPatternTest.php
│   └── WorldHasNoLightException.php         │   └── StripePatternTest.php
├── intersection                             ├── math
│   ├── IntersectionCollectionIterator.php   │   ├── MatrixTest.php
│   ├── IntersectionCollection.php           │   ├── RayTest.php
│   ├── Intersection.php                     │   ├── TransformationsTest.php
│   └── PreparedComputation.php              │   └── TupleTest.php
├── material                                 ├── PointLightTest.php
│   ├── CheckersPattern.php                  ├── shapes
│   ├── GradientPattern.php                  │   ├── PlaneTest.php
│   ├── Material.php                         │   ├── ShapeCollectionTest.php
│   ├── Pattern.php                          │   ├── ShapeTest.php
│   ├── RingPattern.php                      │   └── SphereTest.php
│   └── StripePattern.php                    └── WorldTest.php
├── math
│   ├── Matrix.php                           tests/integration
│   ├── Ray.php                              └── PuttingItTogetherTest.php
│   ├── Transformations.php
│   └── Tuple.php
├── PointLight.php
├── shapes
│   ├── Plane.php
│   ├── ShapeCollectionIterator.php
│   ├── ShapeCollection.php
│   ├── Shape.php
│   └── Sphere.php
└── World.php
```

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

### Install pcov extension on macOS

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

Install the pcov extension for code coverage collection.

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

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

### Install xdebug extension on macOS

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

Install the xdebug extension for code coverage collection.

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

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

### Define setup methods with @before

Source: https://docs.phpunit.de/en/11.5/annotations.html

Use the @before annotation to mark methods that execute before every test method in the class.

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

final class MyTest extends TestCase
{
    /**
     * @before
     */
    public function setupSomeFixtures(): void
    {
        // ...
    }

    /**
     * @before
     */
    public function setupSomeOtherFixtures(): void
    {
        // ...
    }
}
```

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

### Install PHPUnit Globally via PHAR

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

Downloads the PHPUnit PHAR, sets executable permissions, and moves it to a system-wide binary directory.

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

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

### Invoke project-local PHPUnit

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

Executes the installed PHPUnit binary to check the version.

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

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

### Example .phive/phars.xml configuration

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

Configuration file defining the PHPUnit dependency with a semantic version constraint.

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

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

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

### Invoke PHPUnit

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

Command to verify the local PHPUnit installation.

```bash
./tools/phpunit --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
```

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

### Composer configuration for PHPUnit

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

Example composer.json configuration for PHPUnit 9.6.

```json
{
    "require-dev": {
        "phpunit/phpunit": "^9.6"
    }
}
```

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

### Install PHPUnit as a development dependency

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

Adds PHPUnit to the project's composer.json file.

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

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

### Project Directory Structure

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

The file layout used for the error handling examples.

```text
.
├── phpunit.xml
├── src
│   └── FirstPartyClass.php
├── tests
│   └── FirstPartyClassTest.php
└── vendor
    ├── autoload.php
    └── ThirdPartyClass.php

4 directories, 5 files
```

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

### Project Directory Structure

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

Visual representation of the project directory after installing PHPUnit with Phive.

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

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

### PHPUnit assertFileEquals failure output

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

Example output when an assertFileEquals assertion fails.

```text
./tools/phpunit tests/FileEqualsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) FileEqualsTest::testFailure
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'expected\n
+'actual\n
 '

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

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

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

### Phive Metadata Configuration

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

Example of the generated .phive/phars.xml file containing dependency metadata.

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

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

### Invoke PHPUnit command-line runner

Source: https://docs.phpunit.de/en/11.5/textui.html

Example of running a specific test file using the PHPUnit command-line interface.

```bash
./tools/phpunit tests/ArrayTest.php
PHPUnit 11.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.2

..                                                                  2 / 2 (100%)

Time: 00:00.077, Memory: 10.00 MB

OK (2 tests, 2 assertions)
```

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

### Using the expectException() method

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

Demonstrates the basic implementation of an exception test case using the expectException method.

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

final class ExceptionTest extends TestCase
{
    public function testException(): void
    {
        $this->expectException(InvalidArgumentException::class);
    }
}
```

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

### Install specific major version

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

Explicitly install a new major version of PHPUnit when semantic constraints prevent automatic updates.

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

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

### Usage of assertStringStartsWith()

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

Validates that a string begins with a specific 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 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

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

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

### Execute PHPUnit with XML Configuration

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

Run the PHPUnit test runner using the default configuration file.

```bash
$ ./tools/phpunit
PHPUnit 11.5.0 by Sebastian Bergmann and contributors.

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

...............................................................  63 / 177 ( 35%)
............................................................... 126 / 177 ( 71%)
...................................................             177 / 177 (100%)

Time: 00:17.100, Memory: 28.27 MB

OK (177 tests, 657 assertions)
```

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

### assertEqualsCanonicalizing() failure output

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

Example output when assertEqualsCanonicalizing() fails.

```text
./tools/phpunit tests/EqualsWithArraysCanonicalizingTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) EqualsWithArraysCanonicalizingTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    0 => 1
-    1 => 2
-    2 => 3
+    0 => 0
+    1 => 1
+    2 => 2
+    3 => 3
 )

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

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

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

### Define a class under test

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

Example class that depends on an interface to be stubbed.

```php
<?php declare(strict_types=1);
final class SomeClass
{
    public function doSomething(Dependency $dependency): string
    {
        $result = '';

        // ...

        return $result . $dependency->doSomething();
    }
}
```

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

### Usage of assertEquals()

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

Demonstrates basic equality checks for integers and strings, showing how failures are reported.

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

final class EqualsTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEquals(1, 0);
    }

    public function testFailure2(): void
    {
        $this->assertEquals('bar', 'baz');
    }

    public function testFailure3(): void
    {
        $this->assertEquals("foo\nbar\nbaz\n", "foo\nbah\nbaz\n");
    }
}
```

```text
./tools/phpunit tests/EqualsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

FFF                                                                 3 / 3 (100%)

Time: 00:00, Memory: 25.40 MB

There were 3 failures:

1) EqualsTest::testFailure
Failed asserting that 0 matches expected 1.

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

2) EqualsTest::testFailure2
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'bar'
+'baz'

/path/to/tests/EqualsTest.php:13

3) EqualsTest::testFailure3
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
 'foo\n
-bar\n
+bah\n
 baz\n
 '

/path/to/tests/EqualsTest.php:18

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

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

### Create configured stub

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

Uses createConfiguredStub() to define return values for specific methods via an associative array.

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

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

### Implement a PHPUnit Extension

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

Create a class implementing the Extension interface to register subscribers and tracers via the bootstrap method.

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

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

### PHPUnit assertObjectEquals failure output

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

Example output when an assertObjectEquals assertion fails.

```text
./tools/phpunit tests/ObjectEqualsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) ObjectEqualsTest::testSomething
Failed asserting that two objects are equal.

/path/to/tests/ObjectEqualsTest.php:16

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

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

### Configure Test Suites with Directories and Files

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

Defines multiple test suites with specific directories, file inclusions, and directory exclusions.

```xml
<testsuites>
  <testsuite name="unit">
    <directory>tests/unit</directory>
  </testsuite>

  <testsuite name="integration">
    <directory>tests/integration</directory>
  </testsuite>

  <testsuite name="edge-to-edge">
    <directory>tests/edge-to-edge</directory>
    <exclude>tests/edge-to-edge/pathToIgnore</exclude>
  </testsuite>

  <testsuite name="smoke">
    <file>tests/smoke/FirstTest.php</file>
    <file>tests/smoke/SecondTest.php</file>
  </testsuite>
</testsuites>
```

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

### assertEquals() array failure output

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

Example output when assertEquals() fails for arrays.

```text
./tools/phpunit tests/EqualsWithArraysTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) EqualsWithArraysTest::testFailure
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
     0 => 'a'
-    1 => 'b'
-    2 => 'c'
+    1 => 'c'
+    2 => 'd'
 )

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

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

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

### List Defined Test Suites

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

Display all test suites defined in the XML configuration file.

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

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

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

### assertEquals() object failure output

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

Example output when assertEquals() fails for objects.

```text
./tools/phpunit tests/EqualsWithObjectsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00.001, Memory: 25.40 MB

There was 1 failure:

1) EqualsWithObjectsTest::testFailure
Failed asserting that two objects are equal.
--- Expected
+++ Actual
@@ @@
 stdClass Object (
-    'foo' => 'foo'
-    'bar' => 'bar'
+    'foo' => 'bar'
+    'baz' => 'bar'
 )

/path/to/tests/EqualsWithObjectsTest.php:16

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

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

### Generate a baseline file

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

Use the --generate-baseline CLI option to create an XML file containing all currently triggered issues.

```bash
$ phpunit --generate-baseline baseline.xml
PHPUnit 11.1.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.
```

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

### Usage of assertDirectoryExists()

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

Demonstrates testing for the existence of a directory.

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

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

```text
./tools/phpunit tests/DirectoryExistsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) DirectoryExistsTest::testFailure
Failed asserting that directory "/path/to/directory" exists.

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

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

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

### Execution output for StackTest

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

The console output generated when running the StackTest example.

```text
./tools/phpunit tests/StackTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

...                                                                 3 / 3 (100%)

Time: 00:00, Memory: 25.40 MB

OK (3 tests, 5 assertions)
```

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

### Project Directory Structure with Copy

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

Directory structure after using the --copy option.

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

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

### Run PHPUnit with Default Output

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

The default output showing summary information about triggered issues.

```bash
$ ./tools/phpunit
PHPUnit 11.1.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.4
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.
```

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

### Update composer.json for major version

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

Updated configuration to allow installation of PHPUnit 10.

```json
{
    "require-dev": {
        "phpunit/phpunit": "^10.0"
    }
}
```

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

### Execute PHPUnit test for weak comparison and view failure output

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

Command line execution and the resulting failure output for the weak comparison test.

```text
./tools/phpunit tests/ArrayWeakComparisonTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) ArrayWeakComparisonTest::testEquality
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    0 => 1
+    0 => '1'
     1 => 2
-    2 => 3
+    2 => 33
     3 => 4
     4 => 5
     5 => 6
 )

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

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

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

### Configuring Extension Parameters

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

Pass configuration parameters to an extension using the parameter element.

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

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

### Execute PHPUnit tests

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

Command line output showing the execution of the test suite.

```text
./tools/phpunit tests/GreeterTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

.                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

OK (1 test, 1 assertion)
```

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

### Output of assertFalse() failure

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

The console output generated when running the assertFalse() test example.

```text
./tools/phpunit tests/FalseTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) FalseTest::testFailure
Failed asserting that true is false.

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

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

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

### Output of assertTrue() failure

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

The console output generated when running the assertTrue() test example.

```text
./tools/phpunit tests/TrueTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) TrueTest::testFailure
Failed asserting that false is true.

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

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

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

### Usage of assertFileEquals()

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

Demonstrates comparing the contents of two files using assertFileEquals.

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

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

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

### Configure test double with Mock Builder

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

Demonstrates using the fluent interface to configure a test stub with best practice defaults.

```php
<?php declare(strict_types=1);
use PHPUnit
amework	estCase;

final class MockBuilderExampleTest extends TestCase
{
    public function testStub(): void
    {
        // Create a stub for the SomeClass class.
        $stub = $this->getMockBuilder(SomeClass::class)
            ->disableOriginalConstructor()
            ->disableOriginalClone()
            ->disableArgumentCloning()
            ->disallowMockingUnknownTypes()
            ->getMock();

        // Configure the stub.
        $stub->method('doSomething')
            ->willReturn('foo');

        // Calling $stub->doSomething() will now return
        // 'foo'.
        $this->assertSame('foo', $stub->doSomething());
    }
}
```

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

### Verify PHAR with PGP

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

Download the PHAR and its signature, then verify using GPG.

```bash
wget -O phpunit.phar https://phar.phpunit.de/phpunit-10.phar
wget -O phpunit.phar.asc https://phar.phpunit.de/phpunit-10.phar.asc
gpg --keyserver pgp.uni-mainz.de --recv-keys 0x4AA394086372C20A
gpg phpunit.phar.asc
```

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

### Usage of assertIsList()

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

Validates that an array is a list with consecutive integer keys starting from 0.

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

final class IsListTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertIsList([1 => 'foo', '3' => 'bar']);
    }
}
```

```text
./tools/phpunit tests/IsListTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) IsListTest::testFailure
Failed asserting that an array is a list.

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

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

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

### Verify PHPUnit Version

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

Check the installed version of the PHAR file using the PHP CLI.

```bash
php phpunit.phar --version
PHPUnit 10.0.0 by Sebastian Bergmann and contributors.
```

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

### Empty Test Method Placeholder

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

An example of an empty test method used as a placeholder during development.

```php
public function testSomething(): void
{
}
```

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

### Share database connection fixture

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

Uses setUpBeforeClass and tearDownAfterClass to manage a shared database connection across all tests in a test case class.

```php
<?php declare(strict_types=1);
use PHPUnitramework	estcase;

final class DatabaseTest extends TestCase
{
    private static $dbh;

    public static function setUpBeforeClass(): void
    {
        self::$dbh = new PDO('sqlite::memory:');
    }

    public static function tearDownAfterClass(): void
    {
        self::$dbh = null;
    }
}
```

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

### Check for all available updates

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

Lists all available updates including major versions.

```bash
composer outdated
Legend:
! patch or minor release available - update recommended
~ major release available - update possible

Direct dependencies required in composer.json:
phpunit/phpunit                    9.6.3  ~ 10.0.7 The PHP Unit Testing framework.
```

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

### Run PHPUnit with Detailed Output

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

Using the --display-deprecations flag to show specific locations of triggered issues.

```bash
$ ./tools/phpunit --display-deprecations
PHPUnit 11.1.0 by Sebastian Bergmann and contributors.

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

DD                                                                  1 / 1 (100%)

Time: 00:00.002, Memory: 8.00 MB

2 tests triggered 2 deprecations:

1) /path/to/vendor/ThirdPartyClass.php:10
deprecation in third-party code

Triggered by:

* exampleFirstPartyClassTest::testOne
  /path/to/tests/FirstPartyClassTest.php:17

* exampleFirstPartyClassTest::testTwo
  /path/to/tests/FirstPartyClassTest.php:22

2) /path/to/src/FirstPartyClass.php:13
deprecation in first-party code

Triggered by:

* exampleFirstPartyClassTest::testOne
  /path/to/tests/FirstPartyClassTest.php:17

* exampleFirstPartyClassTest::testTwo
  /path/to/tests/FirstPartyClassTest.php:22

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

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

### Define a Greeter class

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

A simple class implementation to be tested.

```php
<?php declare(strict_types=1);
final class Greeter
{
    public function greet(string $name): string
    {
        return 'Hello, ' . $name . '!';
    }
}
```

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

### Execute PHPUnit test with TestWith attribute

Source: https://docs.phpunit.de/en/11.5/attributes.html

Example output when running the test class containing TestWith attributes.

```text
./tools/phpunit tests/DataTest.php
PHPUnit 11.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.2

...F                                                                4 / 4 (100%)

Time: 00:00.058, Memory: 8.00 MB

There was 1 failure:

1) DataTest::testAdd with data set #3
Failed asserting that 2 is identical to 3.

/path/to/DataTest.php:10

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

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

### createConfiguredStub(string $type, array $configuration)

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

A convenience wrapper for creating a stub and configuring return values via an associative array.

```APIDOC
## createConfiguredStub(string $type, array $configuration)

### Description
Creates a stub and configures return values for specific methods using an associative array mapping method names to return values.

### Parameters
- **$type** (string) - Required - The name of the interface or class to stub.
- **$configuration** (array) - Required - An associative array where keys are method names and values are the desired return values.
```

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

### PHPUnit test execution output

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

Example output showing a test failure when an expected deprecation message is not triggered.

```text
./tools/phpunit tests/DeprecationExpectationTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) DeprecationExpectationTest::testFailure
Expected deprecation with message "the-deprecation-message" was not triggered

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

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

### Define a method with a return type declaration

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

Example showing a class method with a return type that triggers recursive stubbing.

```php
<?php declare(strict_types=1);
class C
{
    public function m(): D
    {
        // Do something.
    }
}
```

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

### Display PHAR Software Bill of Materials

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

Use the --sbom option to output dependency information in XML format.

```bash
php phpunit-10.5.1.phar --sbom
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.4">
 <components>
  <component type="library">
   <group>phpunit</group>
   <name>phpunit</name>
   <version>10.5.1</version>
   <description>The PHP Unit Testing framework.</description>
   <licenses>
    <license>
     <id>BSD-3-Clause</id>
    </license>
   </licenses>
   <purl>pkg:composer/phpunit/phpunit@10.5.1</purl>
  </component>
  .
  .
  .
```

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

### Skip a test using markTestSkipped

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

Use markTestSkipped within a setUp method to conditionally skip tests based on runtime environment checks.

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

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

### Usage of assertFileExists()

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

Demonstrates testing for the existence of a file.

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

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

```text
./tools/phpunit tests/FileExistsTest.php
PHPUnit 11.5.27 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.4.10

F                                                                   1 / 1 (100%)

Time: 00:00, Memory: 25.40 MB

There was 1 failure:

1) FileExistsTest::testFailure
Failed asserting that file "/path/to/file" exists.

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

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

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

### Setting Super-global Arrays

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

Configure values for various PHP super-global arrays including GET, POST, COOKIE, SERVER, FILES, and REQUEST.

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

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

```xml
<php>
  <post name="foo" value="bar"/>
</php>
```

```php
$_POST['foo'] = 'bar';
```

```xml
<php>
  <cookie name="foo" value="bar"/>
</php>
```

```php
$_COOKIE['foo'] = 'bar';
```

```xml
<php>
  <server name="foo" value="bar"/>
</php>
```

```php
$_SERVER['foo'] = 'bar';
```

```xml
<php>
  <files name="foo" value="bar"/>
</php>
```

```php
$_FILES['foo'] = 'bar';
```

```xml
<php>
  <request name="foo" value="bar"/>
</php>
```

```php
$_REQUEST['foo'] = 'bar';
```

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

### Configure Homebrew for PHP on macOS

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

Add the necessary Homebrew taps to access PHP and extension formulae.

```bash
brew tap shivammathur/php
brew tap shivammathur/extensions
```

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

### Include source directory

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

Configures PHPUnit to include all .php files within the src directory.

```xml
<include>
    <directory suffix=".php">src</directory>
</include>
```

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

### PHPUnit test runner output with restricted reporting

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

Example output showing how PHPUnit reports issues when configured to restrict reporting to first-party code.

```text
$ ./tools/phpunit --display-deprecations
PHPUnit 11.1.0 by Sebastian Bergmann and contributors.

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

DD                                                                  1 / 1 (100%)

Time: 00:00.002, Memory: 8.00 MB

2 tests triggered 2 deprecations:

1) /path/to/vendor/ThirdPartyClass.php:10
deprecation in third-party code

Triggered by:

* exampleFirstPartyClassTest::testOne
  /path/to/tests/FirstPartyClassTest.php:17

* exampleFirstPartyClassTest::testTwo
  /path/to/tests/FirstPartyClassTest.php:22

2) /path/to/src/FirstPartyClass.php:13
deprecation in first-party code

Triggered by:

* exampleFirstPartyClassTest::testOne
  /path/to/tests/FirstPartyClassTest.php:17

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