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.
Data providers / datasets
Drive many cases through one body instead of duplicating tests.
// PHPUnit
public static function discountCases(): array
{
return [
'no discount below 100' => [50, 0.0],
'5% at 100' => [100, 0.05],
'15% at 1000' => [1000, 0.15],
];
}
#[DataProvider('discountCases')]
public function test_discount_tiers(int $total, float $expected): void
{
self::assertSame($expected, discountFor($total));
}
// Pest
it('applies discount tiers', function (int $total, float $expected) {
expect(discountFor($total))->toBe($expected);
})->with([
[50, 0.0],
[100, 0.05],
[1000, 0.15],
]);
Test doubles — mock collaborators, not the SUT
public function test_it_sends_a_receipt_after_charging(): void
{
$gateway = $this->createMock(PaymentGateway::class);
$gateway->expects(self::once())
->method('charge')
->with(self::equalTo(500))
->willReturn(new Receipt('rcpt_1'));
$mailer = $this->createMock(Mailer::class);
$mailer->expects(self::once())->method('send');
$service = new CheckoutService($gateway, $mailer);
$service->checkout($order);
}
Discipline:
- Stub queries (return canned data); mock commands (assert they were called).
- Mock the collaborators of the unit under test — never mock the class you are testing.
- Don't over-specify: assert the interactions that matter, not every call.
- Prefer real value objects and in-memory fakes over mocks for simple data.
Fixtures — setUp / tearDown
protected function setUp(): void
{
parent::setUp();
$this->repository = new InMemoryUserRepository();
}
- Build fresh state per test; do not share mutable state across tests (order-dependence is a bug).
- Use
setUp() for common arrange steps; keep heavy fixtures out of unit tests.
- For DB-backed tests, the framework plugin's QA phase supplies isolation (transactions/rollback) — apply that there.
Coverage target
- Aim for ≥80% line coverage on changed code; 100% on domain/business logic.
- Coverage is a floor, not a goal — a covered line is not necessarily an asserted behaviour.
- Run
vendor/bin/phpunit --coverage-text (requires PCOV or Xdebug). Report the number; do not chase the last few percent on glue code.