PHPUnit — Green Tests Hide Gateway Timing Bugs

Every PHP application eventually reaches a point where a single 'harmless' change in one file breaks something completely unrelated three layers deep. That's not bad luck — that's the natural consequence of untested code. PHPUnit is the industry-standard testing framework for PHP, and at an advanced level it's not just about writing a few assert statements. It's about architecting a safety net so tight that you can refactor aggressively, onboard new developers fearlessly, and deploy on a Friday afternoon without your stomach dropping.

The real problem PHPUnit solves isn't catching bugs after the fact — it's making bugs impossible to hide in the first place. Without a proper test suite, every code review is guesswork, every deployment is a gamble, and 'it works on my machine' becomes a team-wide coping mechanism. PHPUnit forces your code to be testable, which in turn forces it to be modular, loosely coupled, and honest about its dependencies. The act of writing tests often reveals design flaws that code review misses entirely.

By the end of this article you'll know how to structure a professional PHPUnit test suite from scratch, mock external dependencies so your unit tests never hit a database or API, leverage data providers to eliminate test duplication, enforce meaningful code coverage thresholds, and wire everything into a CI/CD pipeline. You'll also walk away knowing the edge cases and anti-patterns that trip up even experienced PHP developers.

Setting Up PHPUnit and Structuring Your Test Suite

PHPUnit ships via Composer: composer require --dev phpunit/phpunit. Your tests live in a tests/ directory mirroring the source structure. A typical phpunit.xml configures autoloading, coverage filters, and test suites.

Start with a base test case that extends PHPUnit\Framework\TestCase. Name your test class with the same name as the class under test, plus a Test suffix. The convention in the PHP ecosystem is SomeClassTest. Use namespaces that match the source:

```php // src/Service/PaymentProcessor.php namespace io\thecodeforge\Service;

class PaymentProcessor { ... }

// tests/Service/PaymentProcessorTest.php namespace io\thecodeforge\Test\Service;

use PHPUnit\Framework\TestCase; use io\thecodeforge\Service\PaymentProcessor;

class PaymentProcessorTest extends TestCase { ... } ```

This structure makes autoloading trivial and keeps production and test code side by side.

<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php"
         colors="true"
         cacheResult="false"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true">
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">src</directory>
        </include>
    </coverage>
</phpunit>

Writing Expressive Assertions and Organising Tests

PHPUnit provides over 100 assertion methods. Beyond assertTrue() and assertEquals(), the expressive ones reduce test reading time:

• assertCount(3, $items) — clearer than assertEquals(3, count($items))
• assertContains('apple', $fruits) — explicit intent
• assertInstanceOf(SomeInterface::class, $obj) — type checks
• assertArrayHasKey('id', $data) — avoids undefined index warnings

For order-dependent tests, use @depends to pass results between test methods. But be careful — a failed test in a chain marks all dependent tests as skipped, not failed. That masks failures.

<?php
namespace io\thecodeforge\Test\Unit;

use PHPUnit\Framework\TestCase;
use io\thecodeforge\Service\OrderCalculator;

class OrderCalculatorTest extends TestCase
{
    public function test_discount_above_threshold(): void
    {
        $calc = new OrderCalculator();
        $total = $calc->applyDiscount(200.0); // 10% off
        $this->assertEqualsWithDelta(180.0, $total, 0.01);
    }

    public function test_invalid_quantity_throws(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $calc = new OrderCalculator();
        $calc->setQuantity(-1);
    }

    /** @depends test_discount_above_threshold */
    public function test_discount_chain(): void
    {
        $this->assertTrue(true); // placeholder
    }
}

Mocks and Test Doubles — Controlling Dependencies

Unit tests must never hit external systems. That's where mocks, stubs, and spies come in. PHPUnit's built-in createMock() generates a proxy that returns default values for all methods. You configure expectations with expects() and willReturn().

Never mock what you don't own — mock interfaces, not concrete classes. This keeps tests decoupled from implementation details. If you mock a concrete class, a new __construct argument or a renamed method breaks your mock silently.

<?php
namespace io\thecodeforge\Test\Service;

use PHPUnit\Framework\TestCase;
use io\thecodeforge\Service\PaymentProcessor;
use io\thecodeforge\Client\PaymentGatewayInterface;

class PaymentProcessorTest extends TestCase
{
    public function test_charge_success(): void
    {
        $gateway = $this->createMock(PaymentGatewayInterface::class);
        $gateway->expects($this->once())
                ->method('charge')
                ->with(49.99, 'USD')
                ->willReturn('txn_abc123');

        $processor = new PaymentProcessor($gateway);
        $result = $processor->processPayment(49.99, 'USD');

        $this->assertSame('txn_abc123', $result);
    }

    public function test_retry_on_timeout(): void
    {
        $gateway = $this->createMock(PaymentGatewayInterface::class);
        $gateway->expects($this->exactly(2))
                ->method('charge')
                ->willReturnOnConsecutiveCalls(
                    $this->throwException(new \RuntimeException('timeout')),
                    'txn_def456'
                );

        $processor = new PaymentProcessor($gateway, maxRetries: 1);
        $result = $processor->processPayment(99.99, 'EUR');

        $this->assertSame('txn_def456', $result);
    }
}

Data Providers — Eliminate Test Duplication

Data providers are methods annotated with @dataProvider that return an array of arrays. Each inner array is unpacked as arguments to the test method. This lets you test the same logic across many input sets without writing separate test methods.

A common mistake: loading data providers from a file or database. Keep them static and deterministic — the test should never depend on external state. If you need a large set of test data, generate it with a helper function, but keep the provider method itself simple.

You can also chain data providers with @depends, but that's rarely useful. Prefer independent tests with clear provider names.

<?php
namespace io\thecodeforge\Test\Service;

use PHPUnit\Framework\TestCase;
use io\thecodeforge\Service\TaxCalculator;

class TaxCalculatorTest extends TestCase
{
    /** @dataProvider taxableAmountProvider */
    public function test_calculate_tax(
        float $amount,
        string $country,
        float $expectedTax
    ): void {
        $calc = new TaxCalculator();
        $tax = $calc->calculate($amount, $country);
        $this->assertEqualsWithDelta($expectedTax, $tax, 0.001);
    }

    public static function taxableAmountProvider(): array
    {
        return [
            'US standard'     => [100.00, 'US', 7.00],
            'US exempt'       => [0.00,   'US', 0.00],
            'DE standard'     => [100.00, 'DE', 19.00],
            'UK reduced'      => [100.00, 'UK', 5.00],
            'zero amount'     => [0.00,   'DE', 0.00],
            'negative amount' => [-50.00, 'US', 0.00],
        ];
    }
}

Code Coverage, CI Integration, and the Reality of 'Green' Tests

Code coverage reports show which lines you executed, not which paths you tested. A 90% coverage number doesn't mean your code is 90% bug-free — it means 90% of lines ran. The remaining 10% could hide the worst bugs.

Set coverage thresholds in phpunit.xml using <coverage><requireCoverage>true</requireCoverage></coverage>. But more important: enforce that new code must reach a minimum coverage. Use a tool like phpmd or infection (mutation testing) to go deeper.

CI integration is straightforward: run vendor/bin/phpunit in your pipeline. Upload coverage reports to services like Codecov or Coveralls. Critical: make the pipeline fail on coverage drop. Otherwise coverage drifts down sprint after sprint.

name: PHPUnit
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3
          coverage: xdebug
      - run: composer install --prefer-dist --no-progress
      - run: vendor/bin/phpunit --coverage-clover coverage.xml
      - uses: codecov/codecov-action@v4
        with:
          files: coverage.xml
          fail_ci_if_error: true