🧪 PHPUnit Testing Framework

Why PHPUnit?

PHPUnit, created by Sebastian Bergmann, is the de-facto standard for automated testing in PHP. An automated test is simply code that runs your code and checks that it did the right thing — so that a computer, not a human clicking through a browser, catches regressions the moment they appear.

💡 A useful analogy: PHPUnit is the quality-control station on a factory line. Every product (a function's output) is measured against a spec (an assertion) before it ships. When someone later tweaks the machinery, the same checks run again and instantly flag anything that no longer meets spec.

Tests pay for themselves in four ways: they prevent regressions, they give you confidence to refactor, they act as living documentation of how a class is meant to behave, and — because hard-to-test code is usually badly-designed code — they quietly push you toward better architecture.

Installation & Configuration

The right way to add PHPUnit is as a development dependency through Composer, so it ships with your source but never with production:

# Install PHPUnit 11 as a dev dependency
composer require --dev phpunit/phpunit ^11.0

# Confirm the version
./vendor/bin/phpunit --version

The configuration file

PHPUnit reads a phpunit.xml in your project root. This file tells it where the tests live, how to autoload code, and how to measure coverage:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         cacheDirectory=".phpunit.cache"
         failOnWarning="true"
         failOnDeprecation="true">
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory suffix=".php">src</directory>
        </include>
    </source>

    <php>
        <env name="APP_ENV" value="testing"/>
    </php>
</phpunit>

A conventional layout

Keep source and tests in mirror directories so a test's location tells you what it covers:

my-project/
├── src/
│   └── Calculator.php
├── tests/
│   ├── Unit/
│   │   └── CalculatorTest.php
│   └── Integration/
├── composer.json
└── phpunit.xml

Add a psr-4 autoload entry in composer.json so both src/ and tests/ are discoverable, then run composer dump-autoload:

{
  "autoload": { "psr-4": { "App\\": "src/" } },
  "autoload-dev": { "psr-4": { "Tests\\": "tests/" } }
}

Your First Test

Let's test a tiny Calculator. First the class under test:

<?php
// src/Calculator.php
namespace App;

class Calculator
{
    public function add(float $a, float $b): float
    {
        return $a + $b;
    }

    public function divide(float $a, float $b): float
    {
        if ($b === 0.0) {
            throw new \InvalidArgumentException('Cannot divide by zero');
        }
        return $a / $b;
    }
}

Now the test. Modern PHPUnit favours PHP 8 attributes (#[Test]) over the older "method name must start with test" convention, and over docblock annotations:

<?php
// tests/Unit/CalculatorTest.php
namespace Tests\Unit;

use App\Calculator;
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

class CalculatorTest extends TestCase
{
    private Calculator $calculator;

    protected function setUp(): void
    {
        // Arrange: a fresh instance before every test
        $this->calculator = new Calculator();
    }

    #[Test]
    public function it_adds_two_numbers(): void
    {
        $result = $this->calculator->add(5, 3);   // Act
        $this->assertSame(8.0, $result);          // Assert
    }

    #[Test]
    public function it_divides_two_numbers(): void
    {
        $this->assertSame(2.0, $this->calculator->divide(6, 3));
    }
}

Running the suite

# Everything
./vendor/bin/phpunit

# One file
./vendor/bin/phpunit tests/Unit/CalculatorTest.php

# One method by name
./vendor/bin/phpunit --filter it_adds_two_numbers

PHPUnit 11.0.0 by Sebastian Bergmann and contributors.

..                                                                  2 / 2 (100%)

Time: 00:00.012, Memory: 6.00 MB

OK (2 tests, 2 assertions)

Each dot is a passing test. When something fails you'll see an F and a diff of expected vs actual — the whole point of the exercise.

That loop is Test-Driven Development (TDD): red, green, refactor. You don't have to practise TDD strictly, but the loop shows why a fast test suite is worth the effort.

Anatomy of a Test Case

A test case is a class extending PHPUnit\Framework\TestCase. PHPUnit gives you four fixture hooks that run around your tests so each one starts from a clean, known state:

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

class DatabaseTest extends TestCase
{
    private Database $db;

    // Once, before any test in this class
    public static function setUpBeforeClass(): void { /* shared, expensive setup */ }

    // Before every test method
    protected function setUp(): void
    {
        $this->db = new Database();
        $this->db->createTable('users');
    }

    // After every test method
    protected function tearDown(): void
    {
        $this->db->dropTable('users');
    }

    // Once, after the last test in this class
    public static function tearDownAfterClass(): void { /* release shared resources */ }
}

Naming that documents behaviour

Read your test names as sentences. testDivide tells you nothing; divide_by_zero_throws_exception tells you exactly what the class promises:

#[Test]
public function find_user_by_id_returns_null_when_not_found(): void { /* ... */ }

#[Test]
public function register_with_invalid_email_throws_exception(): void { /* ... */ }

Assertions

Assertions are the checks at the heart of every test. Pick the most specific one — a precise assertion produces a precise failure message.

Everyday assertions

// Equality — assertSame uses === (type + value), assertEquals uses ==
$this->assertSame(8, $result);       // prefer this; 8 !== "8"
$this->assertEquals(8, $result);     // looser; use only when you mean it

// Booleans and null
$this->assertTrue($user->isActive());
$this->assertNull($repository->findById(999));

// Arrays and collections
$this->assertCount(3, $items);
$this->assertContains('php', $tags);
$this->assertArrayHasKey('email', $data);

// Types
$this->assertInstanceOf(User::class, $result);

String and JSON assertions

$this->assertStringContainsString('welcome', $html);
$this->assertStringStartsWith('https://', $url);
$this->assertMatchesRegularExpression('/^\d{4}-\d{2}-\d{2}$/', $date);
$this->assertJsonStringEqualsJsonString('{"ok":true}', $response->body());

Data Providers

When a method should behave correctly across many inputs, don't copy-paste the test — feed it a data provider. A provider is a static method returning rows of arguments; PHPUnit runs the test once per row and labels each with its key.

use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\DataProvider;

class CalculatorTest extends TestCase
{
    private Calculator $calculator;

    protected function setUp(): void
    {
        $this->calculator = new Calculator();
    }

    #[Test]
    #[DataProvider('additionCases')]
    public function it_adds_correctly(float $a, float $b, float $expected): void
    {
        $this->assertSame($expected, $this->calculator->add($a, $b));
    }

    public static function additionCases(): array
    {
        return [
            'positives'  => [5, 3, 8.0],
            'negatives'  => [-5, -3, -8.0],
            'mixed sign' => [5, -3, 2.0],
            'with zero'  => [0, 0, 0.0],
            'decimals'   => [1.5, 2.5, 4.0],
        ];
    }
}

The payoff is real: adding a new edge case is a one-line change, and a failure names the exact case (it_adds_correctly with data set "decimals"), so you know instantly which input broke.

Testing Exceptions

Error handling is behaviour too, and it deserves tests. Tell PHPUnit what you expect before the code that should throw:

#[Test]
public function divide_by_zero_throws_exception(): void
{
    $this->expectException(\InvalidArgumentException::class);
    $this->expectExceptionMessage('Cannot divide by zero');

    $this->calculator->divide(5, 0);
}

When you need to inspect the exception object itself, use a try/catch with an explicit fail() so a missing exception is still a failure:

#[Test]
public function division_error_carries_the_offending_values(): void
{
    try {
        $this->calculator->divide(5, 0);
        $this->fail('Expected InvalidArgumentException was not thrown');
    } catch (\InvalidArgumentException $e) {
        $this->assertStringContainsString('zero', $e->getMessage());
    }
}

Code Coverage

Code coverage reports which lines your tests actually execute. It needs a coverage driver — PCOV (fast) or Xdebug (also a debugger):

# Install a driver, then generate reports
pecl install pcov

./vendor/bin/phpunit --coverage-text          # summary in the terminal
./vendor/bin/phpunit --coverage-html coverage  # browsable HTML report

Hands-on Exercise

<?php
// src/ShoppingCart.php
namespace App;

class ShoppingCart
{
    private array $items = [];

    public function add(string $sku, float $price, int $qty = 1): void
    {
        if ($qty <= 0) {
            throw new \InvalidArgumentException('Quantity must be positive');
        }
        if (isset($this->items[$sku])) {
            $this->items[$sku]['qty'] += $qty;
        } else {
            $this->items[$sku] = ['price' => $price, 'qty' => $qty];
        }
    }

    public function count(): int
    {
        return array_sum(array_column($this->items, 'qty'));
    }

    public function total(): float
    {
        $total = 0.0;
        foreach ($this->items as $item) {
            $total += $item['price'] * $item['qty'];
        }
        return $total;
    }
}

<?php
namespace Tests\Unit;

use App\ShoppingCart;
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\DataProvider;

class ShoppingCartTest extends TestCase
{
    private ShoppingCart $cart;

    protected function setUp(): void
    {
        $this->cart = new ShoppingCart();
    }

    #[Test]
    public function a_new_cart_is_empty(): void
    {
        $this->assertSame(0, $this->cart->count());
        $this->assertSame(0.0, $this->cart->total());
    }

    #[Test]
    public function adding_the_same_sku_merges_quantities(): void
    {
        $this->cart->add('A', 10.0, 2);
        $this->cart->add('A', 10.0, 3);

        $this->assertSame(5, $this->cart->count());
        $this->assertSame(50.0, $this->cart->total());
    }

    #[Test]
    #[DataProvider('baskets')]
    public function it_totals_a_basket(array $lines, float $expected): void
    {
        foreach ($lines as [$sku, $price, $qty]) {
            $this->cart->add($sku, $price, $qty);
        }
        $this->assertSame($expected, $this->cart->total());
    }

    public static function baskets(): array
    {
        return [
            'single item'  => [[['A', 9.99, 1]], 9.99],
            'two products' => [[['A', 10.0, 2], ['B', 5.0, 1]], 25.0],
        ];
    }

    #[Test]
    public function adding_a_non_positive_quantity_throws(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->cart->add('A', 10.0, 0);
    }
}

Best Practices

Summary & Quiz

📚 Further Reading

• PHPUnit 11 official documentation
• PHPUnit — full list of assertions
• What changed in PHPUnit 10 (attributes & config)

🚀 What's Next?

PHPUnit is the engine — but WordPress adds its own testing layer on top of it. Next we'll look at how to test themes, plugins, hooks, and the REST API using the WordPress test suite.