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.

Why PHPUnit Tests Can Miss Gateway Timing Bugs

PHPUnit is a unit testing framework for PHP that isolates individual units of code — typically methods or classes — and verifies their behavior against expected outputs. The core mechanic is assertion: you call a method with known inputs and assert that the return value, side effect, or exception matches a predetermined result. This works well for pure logic but breaks down when code depends on external systems like databases, APIs, or file I/O.

In practice, PHPUnit tests are fast because they run in-memory without real I/O. Developers mock or stub external dependencies to avoid network calls, which makes tests deterministic and quick — often under 100ms per test. However, this speed comes at a cost: mocks simulate perfect, zero-latency responses. Real gateways (payment processors, auth services, message queues) have variable latency, timeouts, and transient failures that mocks never reproduce.

Use PHPUnit for testing business logic, validation rules, and algorithmic correctness — things that are pure functions of their inputs. Do not rely on it to catch timing-related bugs like race conditions, deadlocks, or timeout cascades. Those require integration tests with real dependencies under realistic load. The moment your code touches a network boundary, PHPUnit's green bar gives false confidence about production behavior.

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

Installing PHPUnit the Right Way — and Why Composer Is Non-Negotiable

You don't 'download' PHPUnit. You manage it with Composer. Why? Because PHPUnit evolves fast. Your CI pipeline, teammates, and deployment scripts all need the exact same version. A global install on your laptop is a ticking time bomb — I've seen a production rollback caused by a developer running phpunit from /usr/bin while the project required 9.5 and they had 10.0. Never again.

Add it as a dev dependency with composer require --dev phpunit/phpunit. This locks the version in composer.json and composer.lock. Your CI can then run composer install and guarantee consistency. If you need a specific minor, pin it: composer require --dev phpunit/phpunit:^10.5.

Pro tip: alias ./vendor/bin/phpunit to phpunit in your shell profile. Or add a Composer script: "scripts": {"test": "phpunit"}. Now composer test does the right thing every time. No surprises.

// io.thecodeforge
composer require --dev phpunit/phpunit:^10.5

# Verify
./vendor/bin/phpunit --version
# Output: PHPUnit 10.5.20 by Sebastian Bergmann and contributors.

Integration Testing — Where Mocks Lie and Contracts Break

Unit tests verify single units. Integration tests verify they talk to each other — and to the outside world. But here's the hard truth: mocking everything under the sun makes your integration tests as useful as a chocolate teapot. I've seen a team celebrate green tests while the payment API returned a new error code that their mock never modelled.

Focus integration tests on real interactions with boundaries: databases, HTTP APIs, file systems. Use PHPUnit's createMock() only for slow or non-deterministic dependencies. For everything else, spin up a test database or use a lightweight HTTP stub like httpbin.org.

Example: test a PaymentProcessor that calls a real PaymentGateway interface. Mock the gateway only if it hits a third-party API. Otherwise, use an in-memory implementation. The goal is to catch contract mismatches — not to paint the test suite green.

<?php
// io.thecodeforge

use PHPUnit\Framework\TestCase;

class PaymentProcessingIntegrationTest extends TestCase
{
    public function testPaymentProcessesWithRealGatewayStub(): void
    {
        $gateway = $this->createStub(PaymentGateway::class);
        $gateway->method('charge')->willReturn(true);

        $processor = new PaymentProcessor($gateway);

        $result = $processor->process(100.00, 'USD');

        $this->assertTrue($result);
    }
}