PHPUnit

https://docs.phpunit.de/en/9.6/
Admin
PHPUnit is a programmer-oriented testing framework for PHP that provides tools for writing and...
Tokens:55,469
Snippets:611
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Create a stack fixture using setUp

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

Uses the setUp method to initialize a shared instance variable for tests, reducing redundant setup code.

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

final class StackTest extends TestCase
{
    private $stack;

    protected function setUp(): void
    {
        $this->stack = [];
    }

    public function testEmpty(): void
    {
        $this->assertTrue(empty($this->stack));
    }

    public function testPush(): void
    {
        array_push($this->stack, 'foo');

        $this->assertSame('foo', $this->stack[count($this->stack)-1]);
        $this->assertFalse(empty($this->stack));
    }

    public function testPop(): void
    {
        array_push($this->stack, 'foo');

        $this->assertSame('foo', array_pop($this->stack));
        $this->assertTrue(empty($this->stack));
    }
}
```

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

### Install PHPUnit via Composer

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

Add PHPUnit as a development-time dependency to your project.

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

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

### Usage of assertStringStartsWith()

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

Validates that a string begins with a specified prefix. The example shows a test failure when the string does not match the expected prefix.

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

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

```bash
$ phpunit StringStartsWithTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.00Mb

There was 1 failure:

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

/home/sb/StringStartsWithTest.php:6

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

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

### Define setup methods with @before

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

Use the @before annotation to mark methods that execute before every individual test method in a test 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
    {
        // ...
    }
}
```

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

### Download and verify PHPUnit PHAR

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

Download the PHAR file and verify the installation by checking the version.

```bash
$ curl -LO https://phar.phpunit.de/phpunit-9.6.phar
$ php phpunit-9.6.phar --version
PHPUnit x.y.z by Sebastian Bergmann and contributors.
```

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

### Running PHPUnit output tests

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

Example console output when running the provided test class, showing a failure when the actual output does not match the expectation.

```bash
$ phpunit OutputTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

.F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) OutputTest::testExpectBarActualBaz
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'bar'
+'baz'

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

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

### Define shared setup methods with @beforeClass

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

Use the @beforeClass annotation to mark static methods that execute once before any test methods in the class run.

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

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

### Skipping a test in PHPUnit

Source: https://docs.phpunit.de/en/9.6/incomplete-and-skipped-tests.html

Use markTestSkipped inside the setUp method to conditionally skip tests based on environment availability.

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

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

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

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

### PHPUnit Failure Output for assertObjectEquals()

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

Example output showing a failed assertion when the custom equality method returns false.

```text
$ phpunit EqualsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 00:00.017, Memory: 4.00 MB

There was 1 failure:

1) SomethingThatUsesEmailTest::testSomething
Failed asserting that two objects are equal.
The objects are not equal according to Email::equals().

/home/sb/SomethingThatUsesEmailTest.php:16

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

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

### Filter tests using patterns

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

Examples of using the --filter option to run specific tests based on class names, methods, or data set patterns.

```bash
--filter 'TestNamespace\\TestCaseClass::testMethod'
--filter 'TestNamespace\\TestCaseClass'
--filter TestNamespace
--filter TestCaseClass
--filter testMethod
--filter '/::testMethod .*"my named data"/'
--filter '/::testMethod .*#5$/'
--filter '/::testMethod .*#(5|6|7)$/'
```

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

### Usage of assertStringEqualsFile()

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

Validates that the contents of a file match a specific string. The example demonstrates a test failure when the file content differs from the expected string.

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

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

```bash
$ phpunit StringEqualsFileTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

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

/home/sb/StringEqualsFileTest.php:6

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

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

### Usage of assertEqualsIgnoringCase()

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

Compares two strings while ignoring case differences. The example demonstrates a test failure when strings do not match.

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

final class EqualsIgnoringCaseTest extends TestCase
{
    public function testFailure()
    {
        $this->assertEqualsIgnoringCase('foo', 'BAR');
    }
}
```

```bash
$ phpunit EqualsIgnoringCaseTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 51 ms, Memory: 6.00 MB

There was 1 failure:

1) EqualsIgnoringCaseTest::testFailure
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'foo'
+'BAR'

/home/sb/EqualsIgnoringCaseTest.php:8

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

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

### Display PHPUnit help and options

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

Run this command in the terminal to view the full list of available command-line options for PHPUnit.

```bash
$ phpunit --help
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

Usage:
  phpunit [options] UnitTest.php
  phpunit [options] <directory>

Code Coverage Options:
  --coverage-clover <file>    Generate code coverage report in Clover XML format
  --coverage-crap4j <file>    Generate code coverage report in Crap4J XML format
  --coverage-html <dir>       Generate code coverage report in HTML format
  --coverage-php <file>       Export PHP_CodeCoverage object to file
  --coverage-text=<file>      Generate code coverage report in text format [default: standard output]
  --coverage-xml <dir>        Generate code coverage report in PHPUnit XML format
  --coverage-cache <dir>      Cache static analysis results
  --warm-coverage-cache       Warm static analysis cache
  --coverage-filter <dir>     Include <dir> in code coverage analysis
  --path-coverage             Perform path coverage analysis
  --disable-coverage-ignore   Disable annotations for ignoring code coverage
  --no-coverage               Ignore code coverage configuration

Logging Options:
  --log-junit <file>          Log test execution in JUnit XML format to file
  --log-teamcity <file>       Log test execution in TeamCity format to file
  --testdox-html <file>       Write agile documentation in HTML format to file
  --testdox-text <file>       Write agile documentation in Text format to file
  --testdox-xml <file>        Write agile documentation in XML format to file
  --reverse-list              Print defects in reverse order
  --no-logging                Ignore logging configuration

Test Selection Options:
  --filter <pattern>          Filter which tests to run
  --testsuite <name>          Filter which testsuite to run
  --group <name>              Only runs tests from the specified group(s)
  --exclude-group <name>      Exclude tests from the specified group(s)
  --list-groups               List available test groups
  --list-suites               List available test suites
  --list-tests                List available tests
  --list-tests-xml <file>     List available tests in XML format
  --test-suffix <suffixes>    Only search for test in files with specified suffix(es). Default: Test.php,.phpt

Test Execution Options:
  --dont-report-useless-tests Do not report tests that do not test anything
  --strict-coverage           Be strict about @covers annotation usage
  --strict-global-state       Be strict about changes to global state
  --disallow-test-output      Be strict about output during tests
  --disallow-resource-usage   Be strict about resource usage during small tests
  --enforce-time-limit        Enforce time limit based on test size
  --default-time-limit <sec>  Timeout in seconds for tests without @small, @medium or @large
  --disallow-todo-tests       Disallow @todo-annotated tests

  --process-isolation         Run each test in a separate PHP process
  --globals-backup            Backup and restore $GLOBALS for each test
  --static-backup             Backup and restore static attributes for each test

  --colors <flag>             Use colors in output ("never", "auto" or "always")
  --columns <n>               Number of columns to use for progress output
  --columns max               Use maximum number of columns for progress output
  --stderr                    Write to STDERR instead of STDOUT
  --stop-on-defect            Stop execution upon first not-passed test
  --stop-on-error             Stop execution upon first error
  --stop-on-failure           Stop execution upon first error or failure
  --stop-on-warning           Stop execution upon first warning
  --stop-on-risky             Stop execution upon first risky test
  --stop-on-skipped           Stop execution upon first skipped test
  --stop-on-incomplete        Stop execution upon first incomplete test
  --fail-on-incomplete        Treat incomplete tests as failures
  --fail-on-risky             Treat risky tests as failures
  --fail-on-skipped           Treat skipped tests as failures
  --fail-on-warning           Treat tests with warnings as failures
  -v|--verbose                Output more verbose information
  --debug                     Display debugging information

  --repeat <times>            Runs the test(s) repeatedly
  --teamcity                  Report test execution progress in TeamCity format
  --testdox                  Report test execution progress in TestDox format
  --testdox-group             Only include tests from the specified group(s)
  --testdox-exclude-group     Exclude tests from the specified group(s)
  --no-interaction            Disable TestDox progress animation
  --printer <printer>         TestListener implementation to use
```

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

### assertStringStartsWith()

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

Asserts that a string begins with a specified prefix.

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

### Description
Reports an error 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 failure message.
```

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

### assertIsArray() Usage

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

Verifies that a variable is of type array. The example shows a test failure when asserting that null is an array.

```php
<?php
use PHPUnit\Framework\TestCase;

class ArrayTest extends TestCase
{
    public function testFailure()
    {
        $this->assertIsArray(null);
    }
}
```

```bash
$ phpunit ArrayTest
PHPUnit |version|.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.00Mb

There was 1 failure:

1) ArrayTest::testFailure
Failed asserting that null is of type "array".

/home/sb/ArrayTest.php:8

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

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

### Implement all available template methods

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

Demonstrates the full lifecycle of template methods including class-level and test-level hooks.

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

final class TemplateMethodsTest extends TestCase
{
    public static function setUpBeforeClass(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    protected function setUp(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    protected function assertPreConditions(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    public function testOne(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
        $this->assertTrue(true);
    }

    public function testTwo(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
        $this->assertTrue(false);
    }

    protected function assertPostConditions(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    protected function tearDown(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    public static function tearDownAfterClass(): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
    }

    protected function onNotSuccessfulTest(Throwable $t): void
    {
        fwrite(STDOUT, __METHOD__ . "\n");
        throw $t;
    }
}
```

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

### Defining an empty test method

Source: https://docs.phpunit.de/en/9.6/incomplete-and-skipped-tests.html

An example of an empty test method that would be incorrectly interpreted as a success by PHPUnit.

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

```

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

### Share a database fixture between tests

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

Uses setUpBeforeClass and tearDownAfterClass to manage a shared database connection for the entire test 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;
    }
}
```

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

### Handling multiple test dependencies

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

Illustrates how a consumer test receives fixtures from multiple producers in the order they are declared.

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

final class MultipleDependenciesTest extends TestCase
{
    public function testProducerFirst(): string
    {
        $this->assertTrue(true);

        return 'first';
    }

    public function testProducerSecond(): string
    {
        $this->assertTrue(true);

        return 'second';
    }

    /**
     * @depends testProducerFirst
     * @depends testProducerSecond
     */
    public function testConsumer(string $a, string $b): void
    {
        $this->assertSame('first', $a);
        $this->assertSame('second', $b);
    }
}
```

```bash
$ phpunit --verbose MultipleDependenciesTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

...

Time: 0 seconds, Memory: 3.25Mb

OK (3 tests, 4 assertions)
```

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

### Using assertThat() with logicalNot and equalTo

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

Demonstrates how to combine logicalNot() and equalTo() constraints to perform a negative equality check.

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

final class BiscuitTest extends TestCase
{
    public function testEquals(): void
    {
        $theBiscuit = new Biscuit('Ginger');
        $myBiscuit  = new Biscuit('Ginger');

        $this->assertThat(
          $theBiscuit,
          $this->logicalNot(
            $this->equalTo($myBiscuit)
          )
        );
    }
}
```

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

### Email Value Object with equals() Method

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

An example of a Value Object class implementing an equals() method required for assertObjectEquals().

```php
<?php declare(strict_types=1);
final class Email
{
    private string $email;

    public function __construct(string $email)
    {
        $this->ensureIsValidEmail($email);

        $this->email = $email;
    }

    public function asString(): string
    {
        return $this->email;
    }

    public function equals(self $other): bool
    {
        return $this->asString() === $other->asString();
    }

    private function ensureIsValidEmail(string $email): void
    {
        // ...
    }
}
```

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

### Import Release Manager Public Key

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

Import the release manager's public key to enable signature verification.

```bash
$ curl --silent https://sebastian-bergmann.de/gpg.asc | gpg --import
gpg: key 4AA394086372C20A: 452 signatures not checked due to missing keys
gpg: key 4AA394086372C20A: public key "Sebastian Bergmann <sb@sebastian-bergmann.de>" imported
gpg: Total number processed: 1
gpg:               imported: 1
gpg: no ultimately trusted keys found
```

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

### Usage of assertXmlFileEqualsXmlFile()

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

Demonstrates comparing two XML files for equality using assertXmlFileEqualsXmlFile.

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

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

```bash
$ phpunit XmlFileEqualsXmlFileTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

1) XmlFileEqualsXmlFileTest::testFailure
Failed asserting that two DOM documents are equal.
--- Expected
+++ Actual
@@ @@
 <?xml version="1.0"?>
 <foo>
-  <bar/>
+  <baz/>
 </foo>

/home/sb/XmlFileEqualsXmlFileTest.php:7

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

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

### Run a defined XML test suite

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

Execute a specific test suite defined in the configuration file.

```bash
$ phpunit --bootstrap src/autoload.php --testsuite money
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

..

Time: 167 ms, Memory: 3.00Mb

OK (2 test, 2 assertions)
```

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

### assertInstanceOf() Usage

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

Verifies that a variable is an instance of a specific class. The example demonstrates a test failure when the actual object is not an instance of the expected class.

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

final class InstanceOfTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertInstanceOf(RuntimeException::class, new Exception);
    }
}
```

```bash
$ phpunit InstanceOfTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.00Mb

There was 1 failure:

1) InstanceOfTest::testFailure
Failed asserting that Exception Object (...) is an instance of class "RuntimeException".

/home/sb/InstanceOfTest.php:6

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

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

### Run tests from a file

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

Executes tests defined within a specific PHP source file.

```bash
phpunit UnitTest.php
```

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

### Run tests via command line

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

Execute a specific test file using the phpunit command.

```bash
$ phpunit ArrayTest.php
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

..

Time: 0 seconds

OK (2 tests, 2 assertions)
```

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

### Verify directory readability with assertDirectoryIsReadable()

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

Checks if a directory exists and is readable. Fails if the path is not a directory or lacks read permissions.

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

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

```text
$ phpunit DirectoryIsReadableTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

1) DirectoryIsReadableTest::testFailure
Failed asserting that "/path/to/directory" is readable.

/home/sb/DirectoryIsReadableTest.php:6

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

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

### Exclude Static Attributes from Backup

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

Use the $backupStaticAttributesExcludeList property to specify static attributes to exclude from the backup process. The property must be defined as a class member and cannot be set dynamically in setUp().

```php
final class MyTest extends TestCase
{
    protected $backupStaticAttributesExcludeList = [
        'className' => ['attributeName']
    ];

    // ...
}
```

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

### Exclude Global Variables from Backup

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

Use the $backupGlobalsExcludeList property to prevent specific global variables from being backed up and restored. This property must be defined as a class member, as setting it within setUp() has no effect.

```php
final class MyTest extends TestCase
{
    protected $backupGlobalsExcludeList = ['globalVariable'];

    // ...
}
```

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

### Verify directory existence with assertDirectoryExists()

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

Checks if a specified directory exists. Fails if the path is not 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
$ phpunit DirectoryExistsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

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

/home/sb/DirectoryExistsTest.php:6

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

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

### Run all tests in a directory

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

Execute all tests found within the specified directory using a bootstrap file.

```bash
$ phpunit --bootstrap src/autoload.php tests
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

.................................

Time: 636 ms, Memory: 3.50Mb

OK (33 tests, 52 assertions)
```

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

### Testing method calls with Prophecy

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

Demonstrates creating a prophecy for an observer class, setting expectations for method calls, and revealing the mock object for use in a test.

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

final class SubjectTest extends TestCase
{
    public function testObserversAreUpdated(): void
    {
        $subject = new Subject('My subject');

        // Create a prophecy for the Observer class.
        $observer = $this->prophesize(Observer::class);

        // Set up the expectation for the update() method
        // to be called only once and with the string 'something'
        // as its parameter.
        $observer->update('something')->shouldBeCalled();

        // Reveal the prophecy and attach the mock object
        // to the Subject.
        $subject->attach($observer->reveal());

        // Call the doSomething() method on the $subject object
        // which we expect to call the mocked Observer object's
        // update() method with the string 'something'.
        $subject->doSomething();
    }
}
```

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

### Use a data provider with named datasets

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

Using string keys in the data provider array improves output verbosity when a test fails.

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

final class DataTest extends TestCase
{
    /**
     * @dataProvider additionProvider
     */
    public function testAdd(int $a, int $b, int $expected): void
    {
        $this->assertSame($expected, $a + $b);
    }

    public function additionProvider(): array
    {
        return [
            'adding zeros'  => [0, 0, 0],
            'zero plus one' => [0, 1, 1],
            'one plus zero' => [1, 0, 1],
            'one plus one'  => [1, 1, 3]
        ];
    }
}
```

```bash
$ phpunit DataTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) DataTest::testAdd with data set "one plus one" (1, 1, 3)
Failed asserting that 2 is identical to 3.

/home/sb/DataTest.php:9

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

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

### Usage of assertEmpty()

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

Demonstrates testing for empty values and the resulting failure output.

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

final class EmptyTest extends TestCase
{
    public function testFailure(): void
    {
        $this->assertEmpty(['foo']);
    }
}
```

```text
$ phpunit EmptyTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

1) EmptyTest::testFailure
Failed asserting that an array is empty.

/home/sb/EmptyTest.php:6

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

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

### Generate TestDox documentation via CLI

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

Executes PHPUnit with the --testdox flag to output test progress as readable sentences.

```bash
$ phpunit --testdox BankAccountTest.php
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

BankAccount
 ✔ Balance is initially zero
 ✔ Balance cannot become negative
```

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

### Testing function output with expectOutputString

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

Demonstrates using expectOutputString to verify that a method produces the exact expected string output.

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

final class OutputTest extends TestCase
{
    public function testExpectFooActualFoo(): void
    {
        $this->expectOutputString('foo');

        print 'foo';
    }

    public function testExpectBarActualBaz(): void
    {
        $this->expectOutputString('bar');

        print 'baz';
    }
}
```

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

### assertEquals() with scalar values

Source: https://docs.phpunit.de/en/9.6/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");
    }
}
```

```bash
$ phpunit EqualsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

FFF

Time: 0 seconds, Memory: 5.25Mb

There were 3 failures:

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

/home/sb/EqualsTest.php:6

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

/home/sb/EqualsTest.php:11

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

/home/sb/EqualsTest.php:16

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

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

### Usage of assertDirectoryIsWritable()

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

Demonstrates testing for directory writability and the resulting failure output.

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

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

```text
$ phpunit DirectoryIsWritableTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

1) DirectoryIsWritableTest::testFailure
Failed asserting that "/path/to/directory" is writable.

/home/sb/DirectoryIsWritableTest.php:6

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

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

### Usage of assertFileEquals()

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

Demonstrates the use of assertFileEquals to compare the contents of two files in a PHPUnit test case.

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

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

```bash
$ phpunit FileEqualsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

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

/home/sb/FileEqualsTest.php:6

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

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

### Configure extension arguments

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

Pass arguments to an extension's constructor using the arguments element with supported data types.

```xml
<extension class="Vendor\MyExtension">
    <arguments>
        <integer>1</integer>
        <integer>2</integer>
        <integer>3</integer>
        <string>hello world</string>
        <boolean>true</boolean>
        <double>1.23</double>
        <array>
            <element index="0">
                <string>value1</string>
            </element>
            <element index="1">
                <string>value2</string>
            </element>
        </array>
        <object class="Vendor\MyPhpClass">
            <string>constructor arg 1</string>
            <string>constructor arg 2</string>
        </object>
    </arguments>
</extension>
```

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

### Execute PHPUnit Template Methods Test

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

Displays the execution order of various template methods during a test run.

```bash
$ phpunit TemplateMethodsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

TemplateMethodsTest::setUpBeforeClass
TemplateMethodsTest::setUp
TemplateMethodsTest::assertPreConditions
TemplateMethodsTest::testOne
TemplateMethodsTest::assertPostConditions
TemplateMethodsTest::tearDown
.TemplateMethodsTest::setUp
TemplateMethodsTest::assertPreConditions
TemplateMethodsTest::testTwo
TemplateMethodsTest::tearDown
TemplateMethodsTest::onNotSuccessfulTest
FTemplateMethodsTest::tearDownAfterClass

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

1) TemplateMethodsTest::testTwo
Failed asserting that <boolean:false> is true.
/home/sb/TemplateMethodsTest.php:30

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

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

### Handling Line-Based Coverage Edge Cases

Source: https://docs.phpunit.de/en/9.6/code-coverage-analysis.html

Demonstrates how line-based coverage can incorrectly mark unreachable code as covered and how to fix it using braces.

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

// Because it is "line based" and not statement base coverage
// one line will always have one coverage status
if (false) this_function_call_shows_up_as_covered();

// Due to how code coverage works internally these two lines are special.
// This line will show up as non executable
if (false)
    // This line will show up as covered because it is actually the
    // coverage of the if statement in the line above that gets shown here!
    will_also_show_up_as_covered();

// To avoid this it is necessary that braces are used
if (false) {
    this_call_will_never_show_up_as_covered();
}
```

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

### Configure PHP ini settings

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

Set PHP configuration settings using the ini element.

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

```php
ini_set('foo', 'bar');
```

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

### Instantiate Test Listener in PHP

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

Represents the programmatic equivalent of the XML listener configuration. Note that the TestListener interface is deprecated.

```php
$listener = new MyListener(
    ['Sebastian'],
    22,
    'April',
    19.78,
    null,
    new stdClass
);
```

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

### Combine @depends and @dataProvider

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

Demonstrates how arguments from a data provider are prepended to arguments from depended-upon tests.

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

final class DependencyAndDataProviderComboTest extends TestCase
{
    public function provider(): array
    {
        return [['provider1'], ['provider2']];
    }

    public function testProducerFirst(): string
    {
        $this->assertTrue(true);

        return 'first';
    }

    public function testProducerSecond(): string
    {
        $this->assertTrue(true);

        return 'second';
    }

    /**
     * @depends testProducerFirst
     * @depends testProducerSecond
     * @dataProvider provider
     */
    public function testConsumer(): void
    {
        $this->assertSame(
            ['provider1', 'first', 'second'],
            func_get_args()
        );
    }
}
```

```bash
$ phpunit --verbose DependencyAndDataProviderComboTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 3.50Mb

There was 1 failure:

1) DependencyAndDataProviderComboTest::testConsumer with data set #1 ('provider2')
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
Array &0 (
-    0 => 'provider1'
+    0 => 'provider2'
     1 => 'first'
     2 => 'second'
)
/home/sb/DependencyAndDataProviderComboTest.php:32

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

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

### Configure php.ini for PHPUnit

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

Recommended settings for the php.ini file to ensure informative test output.

```ini
memory_limit=-1
error_reporting=-1
log_errors_max_len=0
zend.assertions=1
assert.exception=1
xdebug.show_exception_trace=0

```

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

### Use data provider placeholders in testdox

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

Placeholders in @testdox allow dynamic documentation based on data provider parameters.

```php
/**
 * @dataProvider additionProvider
 * @testdox Adding $a to $b results in $expected
 */
public function testAdd($a, $b, $expected)
{
    $this->assertSame($expected, $a + $b);
}

public function additionProvider()
{
    return [
        'data set 1' => [0, 0, 0],
        'data set 2' => [0, 1, 1],
        'data set 3' => [1, 0, 1],
        'data set 4' => [1, 1, 3]
    ];
}
```

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

### Stubbing a web service with getMockFromWsdl

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

Uses a WSDL file to generate a mock object for a web service, allowing the definition of return values for specific methods without invoking the actual service.

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

final class GoogleTest extends TestCase
{
    public function testSearch(): void
    {
        $googleSearch = $this->getMockFromWsdl(
          'GoogleSearch.wsdl', 'GoogleSearch'
        );

        $directoryCategory = new stdClass;
        $directoryCategory->fullViewableName = '';
        $directoryCategory->specialEncoding = '';

        $element = new stdClass;
        $element->summary = '';
        $element->URL = 'https://phpunit.de/';
        $element->snippet = '...';
        $element->title = '<b>PHPUnit</b>';
        $element->cachedSize = '11k';
        $element->relatedInformationPresent = true;
        $element->hostName = 'phpunit.de';
        $element->directoryCategory = $directoryCategory;
        $element->directoryTitle = '';

        $result = new stdClass;
        $result->documentFiltering = false;
        $result->searchComments = '';
        $result->estimatedTotalResultsCount = 3.9000;
        $result->estimateIsExact = false;
        $result->resultElements = [$element];
        $result->searchQuery = 'PHPUnit';
        $result->startIndex = 1;
        $result->endIndex = 1;
        $result->searchTips = '';
        $result->directoryCategories = [];
        $result->searchTime = 0.248822;

        $googleSearch->expects($this->any())
                     ->method('doGoogleSearch')
                     ->will($this->returnValue($result));

        /**
         * $googleSearch->doGoogleSearch() will now return a stubbed result and
         * the web service's doGoogleSearch() method will not be invoked.
         */
        $this->assertEquals(
          $result,
          $googleSearch->doGoogleSearch(
            '00000000000000000000000000000000',
            'PHPUnit',
            0,
            1,
            false,
            '',
            false,
            '',
            '',
            ''
          )
        );
    }
}
```

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

### Define a test case with named data sets

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

Demonstrates how to use the @dataProvider annotation to provide named data sets to a test method.

```php
<?php
namespace TestNamespace;

use PHPUnit\Framework\TestCase;

class TestCaseClass extends TestCase
{
    /**
     * @dataProvider provider
     */
    public function testMethod($data)
    {
        $this->assertTrue($data);
    }

    public function provider()
    {
        return [
            'my named data' => [true],
            'my data'       => [true]
        ];
    }
}
```

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

### Configure a test double with Mock Builder

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

Uses the Mock Builder API to configure a test double with specific constraints, mirroring the defaults of createStub.

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

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

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

### Define Test Suites in XML

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

Configures multiple test suites by mapping names to specific directories.

```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>
  </testsuite>
</testsuites>
```

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

### Configure @backupGlobals at Method Level

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

Override class-level settings by applying the annotation to individual test methods for granular control.

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

/**
 * @backupGlobals enabled
 */
final class MyTest extends TestCase
{
    public function testThatInteractsWithGlobalVariables()
    {
        // ...
    }

    /**
     * @backupGlobals disabled
     */
    public function testThatDoesNotInteractWithGlobalVariables(): void
    {
        // ...
    }
}
```

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

### Minimal XML configuration for test suites

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

Define a test suite in phpunit.xml to automatically include all *Test.php files in the tests directory.

```xml
<phpunit bootstrap="src/autoload.php">
  <testsuites>
    <testsuite name="money">
      <directory>tests</directory>
    </testsuite>
  </testsuites>
</phpunit>
```

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

### Make PHPUnit PHAR executable

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

Change file permissions to allow direct execution of the PHAR file.

```bash
$ curl -LO https://phar.phpunit.de/phpunit-9.6.phar
$ chmod +x phpunit-9.6.phar
$ ./phpunit-9.6.phar --version
PHPUnit x.y.z by Sebastian Bergmann and contributors.
```

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

### Download PHPUnit PHAR and Signature

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

Download the PHPUnit PHAR file and its corresponding detached PGP signature file.

```bash
$ curl -LO https://phar.phpunit.de/phpunit-9.6.phar
$ curl -LO https://phar.phpunit.de/phpunit-9.6.phar.asc
```

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

### Use multiple data providers for a single test

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

Shows how to stack multiple @dataProvider annotations on a single test method to aggregate test cases.

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

final class DataTest extends TestCase
{
    /**
     * @dataProvider additionWithNonNegativeNumbersProvider
     * @dataProvider additionWithNegativeNumbersProvider
     */
    public function testAdd(int $a, int $b, int $expected): void
    {
        $this->assertSame($expected, $a + $b);
    }

    public function additionWithNonNegativeNumbersProvider(): array
    {
        return [
            [0, 1, 1],
            [1, 0, 1],
            [1, 1, 3]
        ];
    }

    public function additionWithNegativeNumbersProvider(): array
    {
        return [
            [-1, 1, 0],
            [-1, -1, -2],
            [1, -1, 0]
        ];
    }
 }
```

```bash
$ phpunit DataTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

..F...                                                              6 / 6 (100%)

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

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

/home/sb/DataTest.php:12

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

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

### Usage of assertObjectEquals() in a Test Case

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

Demonstrates how to use assertObjectEquals() to compare two instances of a Value Object.

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

final class SomethingThatUsesEmailTest extends TestCase
{
    public function testSomething(): void
    {
        $a = new Email('user@example.org');
        $b = new Email('user@example.org');
        $c = new Email('user@example.com');

        // This passes
        $this->assertObjectEquals($a, $b);

        // This fails
        $this->assertObjectEquals($a, $c);
    }
}
```

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

### Usage of assertFileExists()

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

Verifies that a file exists at the specified path. Use assertFileDoesNotExist() for the inverse check.

```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
$ phpunit FileExistsTest
PHPUnit 9.6.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

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

/home/sb/FileExistsTest.php:6

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