php-testing

PHP Testing Patterns (stack-agnostic)

Patterns for PHPUnit and Pest that apply to any PHP codebase. Detect which runner the project uses before writing tests: pestphp/pest in require-dev → Pest; otherwise PHPUnit. Both run on top of PHPUnit assertions.

Detection and running

grep -q pestphp/pest composer.json && echo pest || echo phpunit
vendor/bin/phpunit            # PHPUnit
vendor/bin/pest               # Pest
vendor/bin/phpunit --coverage-text   # coverage (needs Xdebug or PCOV)

Prefer a composer test script if one exists.

Test structure — Arrange / Act / Assert

PHPUnit (class-based):

<?php

declare(strict_types=1);

namespace App\Tests\Unit;

use App\Domain\Money;
use App\Domain\Currency;
use PHPUnit\Framework\TestCase;

final class MoneyTest extends TestCase
{
    public function test_it_adds_two_amounts_of_the_same_currency(): void
    {
        // Arrange
        $a = new Money(100, Currency::USD);
        $b = new Money(250, Currency::USD);

        // Act
        $sum = $a->add($b);

        // Assert
        self::assertSame(350, $sum->amount);
    }

    public function test_it_rejects_a_currency_mismatch(): void
    {
        $this->expectException(\InvalidArgumentException::class);

        (new Money(100, Currency::USD))->add(new Money(100, Currency::EUR));
    }
}

Pest (function-based, same engine):

<?php

declare(strict_types=1);

use App\Domain\Money;
use App\Domain\Currency;

it('adds two amounts of the same currency', function () {
    $sum = (new Money(100, Currency::USD))->add(new Money(250, Currency::USD));

    expect($sum->amount)->toBe(350);
});

it('rejects a currency mismatch', function () {
    expect(fn () => (new Money(100, Currency::USD))->add(new Money(100, Currency::EUR)))
        ->toThrow(InvalidArgumentException::class);
});

Naming and organisation

• Tests live in tests/, namespace App\Tests\... (mapped via autoload-dev).
• Mirror the source tree: src/Domain/Money.php → tests/Unit/Domain/MoneyTest.php.
• Split tests/Unit (pure, no I/O) from tests/Integration / tests/Feature (DB, HTTP, filesystem).
• PHPUnit method names: test_it_<behaviour>() or #[Test] attribute. Pest: it('<behaviour>'). Describe behaviour, not implementation.