Andrej PrusSenior Laravel systems
StartProject
Back to blog

Testing

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage

Comprehensive tutorial on writing unit, integration, and data-provider tests using PHPUnit, including mocking and assertion best practices.

Testing14 min read3057 words
  • PHPUnit
  • PHP
  • Testing
  • Code Coverage

SEO Metadata

SEO Title Options

  1. PHP Unit Testing With PHPUnit: From Zero to 100% Code
  2. PHP Unit Testing With PHPUnit: From Zero: Practical 2026
  3. Testing Playbook: PHP Unit Testing With PHPUnit: From Zero

Meta Description Options

  1. Learn PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage with a practical Testing framework, expert mistakes, implementation steps, examples, FAQ.
  2. Comprehensive tutorial on writing unit, integration, and data-provider tests using PHPUnit, including mocking and assertion best practices.

URL Slug

php-unit-testing-with-phpunit-code-coverage

Focus Keyword

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage

Additional LSI Keywords

  • Testing
  • PHPUnit
  • PHP
  • Code Coverage
  • PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage
  • production checklist
  • implementation guide
  • best practices
  • architecture decisions
  • testing strategy
  • performance impact
  • security review

Table of Contents

Article overview

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage is the kind of topic that looks simple until it reaches production. Teams usually discover the real cost late: unclear boundaries, weak defaults, hidden maintenance work, and decisions that seemed harmless when the codebase was small.

The problem gets worse when the article, tutorial, or implementation guide only explains the happy path. This guide closes that gap with a practical framework, a comparison table, common mistakes, and a deep technical section you can use while planning real work.

Keep reading for the non-obvious part: the safest implementation is rarely the most impressive-looking one. It is the one your team can debug, test, document, and evolve without turning every future change into archaeology.

Key Takeaways

  • PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage should be evaluated as a production decision, not only as a syntax or tooling choice.
  • The best implementation keeps responsibilities visible, with clear ownership, tests, documentation, and rollback paths.
  • Search visibility improves when practical depth, structured answers, and expert examples live on the same page.

[IMAGE: A mobile-first technical article layout showing the main concept, decision table, implementation checklist, and FAQ blocks. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage expert guide for Testing]

What PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage means

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage means applying testing knowledge to a concrete engineering decision, then turning that decision into reliable code, documentation, and operational behavior. In practice, it combines the topic's core concepts with trade-off analysis, implementation boundaries, testing strategy, and maintenance discipline.

This is the definition worth optimizing for featured snippets because it avoids hype. It tells the reader what the topic does and what a professional implementation must include.

Why it matters now

The technical web is more crowded than it was a few years ago. Thin tutorials can still get indexed, but they rarely earn trust from senior developers, buyers, AI answer systems, or teams that need production guidance.

For testing topics, the strongest content now has three layers:

  • a clear answer for fast scanning
  • a practical framework for implementation
  • expert context that explains what breaks later

That same structure helps search engines understand the page. It also helps readers decide whether the advice fits their project.

Implementation framework

Use this framework before adopting the approach described in this article.

  1. Define the user problem and the production risk.
  2. Identify the smallest reliable implementation boundary.
  3. Keep configuration, secrets, and environment-specific behavior outside the article's core logic.
  4. Add tests for the behavior that would hurt if it regressed.
  5. Document the trade-off, not only the final code.
  6. Measure the result with logs, metrics, or user-facing outcomes.
  7. Revisit the decision after real usage exposes edge cases.

The sequence is deliberately conservative. It keeps the work grounded in outcomes instead of novelty.

[IMAGE: A seven-step implementation framework with discovery, boundary design, configuration, tests, documentation, measurement, and iteration. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage implementation framework]

Practical comparison

Decision areaStrong approachWeak approachWhy it matters
ScopeSolve one clear problemMix unrelated concernsFocus improves testing and search intent
ArchitecturePut logic in explicit classes or documented boundariesHide behavior in templates or incidental callbacksFuture changes stay easier to review
Data flowPass prepared data into the view or endpointQuery or compute in presentation codeReduces regressions and performance surprises
TestingCover the risky behavior directlyTest only the happy pathCatches production failures earlier
DocumentationExplain trade-offs and limitsRepeat generic definitionsBuilds E-E-A-T and reader trust
OperationsTrack logs, metrics, and rollback stepsShip without measurementMakes the decision reversible

This table is intentionally practical. It gives a reviewer something to check before the implementation becomes expensive to change.

Expert workflow

Expert tip: "Treat PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage as a system boundary. If the next developer cannot find where the decision lives, how it is tested, and when it should be avoided, the implementation is not finished."

A useful workflow is simple:

  • Start with the smallest working example.
  • Add the constraints that exist in your real project.
  • Remove anything that only demonstrates cleverness.
  • Write down the failure modes.
  • Add links to related decisions so future readers can navigate the topic cluster.

That last point matters for both humans and search systems. A single article can answer a question; a cluster proves authority.

Common mistakes

Mistake 1: Copying a pattern without its context

A pattern that works in a small demo can fail in a real application. The missing context is usually data volume, team experience, deployment process, security requirements, or observability.

Before copying the pattern, ask what assumption made it safe in the original example.

Mistake 2: Putting business logic in the wrong layer

This is the fastest way to make future debugging expensive. In Laravel, PHP, and server-rendered websites, presentation should receive prepared data, not discover rules on its own.

Keep decision logic in models, actions, services, policies, requests, jobs, or documented helpers where it can be tested directly.

Mistake 3: Optimizing for novelty instead of maintainability

Newer tools and language features can be valuable. They can also hide simple behavior behind unfamiliar syntax.

Use the option that makes the next production incident easier to understand.

Mistake 4: Publishing without a measurement plan

If the article describes a performance, SEO, security, or architecture improvement, define how success will be checked. Logs, tests, crawl diagnostics, analytics, and user behavior are all stronger than assumptions.

[IMAGE: A common-mistakes board with context loss, wrong layer, novelty bias, and missing measurement highlighted. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage common mistakes]

Image placeholders

  • [IMAGE: A concept diagram for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage with input, decision boundary, implementation, tests, and production feedback. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage concept diagram]
  • [IMAGE: A mobile screenshot-style checklist for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage mobile checklist]
  • [IMAGE: A comparison table visualization for strong versus weak implementation choices. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage comparison table]

Video placeholder

[VIDEO: Insert a 5-8 minute YouTube walkthrough that demonstrates the main decision, the implementation boundary, the test strategy, and the production caveats for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage.]

Internal linking opportunities

Original Technical Deep Dive

Start with the real target

Code coverage is not the goal. Correct behavior is the goal.

Coverage is a measuring tool. It tells you which executable lines ran while the test suite executed. It does not prove that the assertions are meaningful, that edge cases are covered, or that the design is good.

Still, coverage is useful. A project with no tests has no safety net. A project with high coverage and weak assertions has a false sense of safety. The practical target is simple: write tests that prove behavior, then use coverage to find important branches you missed.

In 2020, PHPUnit 9 was the normal choice for PHP 7.3 and PHP 7.4 projects. For older PHP versions, use the PHPUnit version that supports your runtime instead of forcing a newer test runner into an old stack.

Install PHPUnit

Install PHPUnit as a development dependency:

composer require --dev phpunit/phpunit:^9

A small project can start with this structure:

project/
  composer.json
  phpunit.xml
  src/
    Money.php
    Order.php
  tests/
    Unit/
      MoneyTest.php
    Integration/
      OrderRepositoryTest.php

Configure Composer autoloading:

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

Then refresh the autoloader:

composer dump-autoload

Add phpunit.xml

Keep the command line boring by putting repeatable configuration in phpunit.xml:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    bootstrap="vendor/autoload.php"
    colors="true"
    stopOnFailure="false"
>
    <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>

Run the suite:

vendor/bin/phpunit

Run only one suite:

vendor/bin/phpunit --testsuite Unit

Run one test class:

vendor/bin/phpunit tests/Unit/MoneyTest.php

Write the first useful unit test

Use a tiny value object as the first example:

<?php

declare(strict_types=1);

namespace App;

final class Money
{
    public function __construct(
        private int $cents,
        private string $currency
    ) {
        if ($cents < 0) {
            throw new \InvalidArgumentException('Amount cannot be negative.');
        }
    }

    public function cents(): int
    {
        return $this->cents;
    }

    public function currency(): string
    {
        return $this->currency;
    }

    public function add(self $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new \InvalidArgumentException('Currencies must match.');
        }

        return new self($this->cents + $other->cents, $this->currency);
    }
}

Test behavior, not implementation details:

<?php

declare(strict_types=1);

namespace Tests\Unit;

use App\Money;
use InvalidArgumentException;
use PHPUnit\Framework\TestCase;

final class MoneyTest extends TestCase
{
    public function testItAddsAmountsWithTheSameCurrency(): void
    {
        $total = (new Money(1200, 'EUR'))->add(new Money(800, 'EUR'));

        self::assertSame(2000, $total->cents());
        self::assertSame('EUR', $total->currency());
    }

    public function testItRejectsNegativeAmounts(): void
    {
        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('negative');

        new Money(-1, 'EUR');
    }

    public function testItRejectsMixedCurrencies(): void
    {
        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('Currencies must match');

        (new Money(1000, 'EUR'))->add(new Money(1000, 'USD'));
    }
}

The names describe behavior. The assertions check observable results. The tests do not inspect private properties with reflection, mock the class being tested, or duplicate the implementation.

Choose precise assertions

assertEquals() is convenient, but it can be too loose. Prefer exact assertions when the value matters.

Use this:

self::assertSame(2000, $total->cents());
self::assertCount(3, $items);
self::assertTrue($user->isActive());
self::assertNull($deletedAt);
self::assertInstanceOf(Money::class, $total);

Avoid this when exact type matters:

self::assertEquals('2000', $total->cents());

That assertion can hide a string-versus-integer mistake. Tests should make bad states obvious.

Good assertion practice:

  • Prefer assertSame() for scalar values.
  • Use assertCount() for array or collection size.
  • Use assertContains() only when order does not matter.
  • Assert the result that the caller cares about.
  • Do not add meaningless assertions just to increase the assertion count.

Use data providers for rules

When one behavior has many inputs, use a data provider instead of copying the test method.

<?php

declare(strict_types=1);

namespace Tests\Unit;

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

final class MoneyFormattingTest extends TestCase
{
    /**
     * @dataProvider amountProvider
     */
    public function testItStoresAmountInCents(int $cents, string $currency): void
    {
        $money = new Money($cents, $currency);

        self::assertSame($cents, $money->cents());
        self::assertSame($currency, $money->currency());
    }

    public function amountProvider(): array
    {
        return [
            'zero euro' => [0, 'EUR'],
            'one cent euro' => [1, 'EUR'],
            'large dollar amount' => [999999, 'USD'],
        ];
    }
}

Name the data sets. When a row fails, PHPUnit reports the data set name, which makes the failing case easier to understand.

[IMAGE: Supporting visual 1 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 1]

[IMAGE: Supporting visual 1 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 1]

Keep data providers simple. PHPUnit evaluates providers before setUp() runs, so do not rely on fixtures created in setUp() from inside a provider.

Test exceptions carefully

Put expectException() immediately before the line that should throw:

public function testItRejectsMixedCurrencies(): void
{
    $euro = new Money(1000, 'EUR');
    $usd = new Money(1000, 'USD');

    $this->expectException(\InvalidArgumentException::class);
    $this->expectExceptionMessage('Currencies must match');

    $euro->add($usd);
}

This avoids a weak test where an earlier line throws the expected exception and the actual behavior is never exercised.

Also check the message or code when multiple branches can throw the same exception class.

Separate unit and integration tests

A unit test checks one small unit of behavior without external systems. It should be fast, deterministic, and easy to run repeatedly.

An integration test checks that multiple pieces work together:

  • Database queries with real schema.
  • HTTP clients against a fake or local server.
  • File storage with a temporary directory.
  • Serialization and deserialization between layers.

Do not pretend database tests are unit tests. They are useful, but they have different tradeoffs. Keep them in a separate suite so developers can run quick unit tests during normal edits and run integration tests before merging.

Write a database integration test

For plain PHP, SQLite is often enough for repository-level tests if your production SQL is portable. If your code depends on MySQL-specific behavior, use MySQL in CI.

<?php

declare(strict_types=1);

namespace Tests\Integration;

use App\OrderRepository;
use PDO;
use PHPUnit\Framework\TestCase;

final class OrderRepositoryTest extends TestCase
{
    private PDO $pdo;

    protected function setUp(): void
    {
        $this->pdo = new PDO('sqlite::memory:');
        $this->pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

        $this->pdo->exec(
            'CREATE TABLE orders (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                email TEXT NOT NULL,
                total_cents INTEGER NOT NULL
            )'
        );
    }

    public function testItStoresAnOrder(): void
    {
        $repository = new OrderRepository($this->pdo);

        $id = $repository->create('ada@example.com', 2500);

        $row = $this->pdo
            ->query('SELECT email, total_cents FROM orders WHERE id = ' . (int) $id)
            ->fetch(PDO::FETCH_ASSOC);

        self::assertSame('ada@example.com', $row['email']);
        self::assertSame(2500, (int) $row['total_cents']);
    }
}

The test owns its database. No shared state. No dependency on a developer machine having one old row in a local database.

Use mocks for boundaries

Mocking is useful when the real dependency is slow, unavailable, nondeterministic, or has side effects. Examples: email delivery, payment gateways, queues, and external APIs.

Start with an interface:

<?php

declare(strict_types=1);

namespace App;

interface Mailer
{
    public function send(string $email, string $subject, string $body): void;
}

Then test the service through that boundary:

<?php

declare(strict_types=1);

namespace Tests\Unit;

use App\Mailer;
use App\WelcomeUser;
use PHPUnit\Framework\TestCase;

final class WelcomeUserTest extends TestCase
{
    public function testItSendsAWelcomeEmail(): void
    {
        $mailer = $this->createMock(Mailer::class);

        $mailer->expects(self::once())
            ->method('send')
            ->with(
                self::equalTo('ada@example.com'),
                self::stringContains('Welcome'),
                self::stringContains('Ada')
            );

        $service = new WelcomeUser($mailer);

        $service->handle('Ada', 'ada@example.com');
    }
}

Do not mock everything. If a value object is cheap and deterministic, create the real object. If a collaborator has important behavior, consider an integration test. Mock boundaries, not the whole application.

Use stubs for input, mocks for expectations

A stub provides controlled answers:

$clock = $this->createStub(Clock::class);
$clock->method('now')->willReturn(new DateTimeImmutable('2020-07-14 10:00:00'));

A mock verifies interaction:

$mailer = $this->createMock(Mailer::class);
$mailer->expects(self::once())->method('send');

[IMAGE: Supporting visual 2 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 2]

If you only need a return value, prefer a stub. If you need to prove a side effect happened through a dependency, use a mock.

Measure coverage

PHPUnit needs a coverage driver. In 2020, the usual choices were Xdebug, PCOV, or PHPDBG.

Run a text report:

vendor/bin/phpunit --coverage-text

Generate an HTML report:

vendor/bin/phpunit --coverage-html build/coverage

Then open build/coverage/index.html.

[IMAGE: Supporting visual 2 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 2]

If PHPUnit says no coverage driver is available, your CLI PHP does not have Xdebug or PCOV loaded. Check the CLI binary, not only the web server configuration:

php -v
php -m | grep -E 'xdebug|pcov'

Coverage should be configured to include production code, not tests, vendor files, generated caches, or scripts that cannot be loaded safely.

Getting to 100% without lying

Getting to 100% line coverage is possible on small units. It is not always worth it across a whole legacy application.

Use this sequence:

  1. Add tests for the main success path.
  2. Add tests for validation failures.
  3. Add tests for boundary values.
  4. Add tests for exceptions.
  5. Add integration tests for database or filesystem behavior.
  6. Review the coverage report for untested branches.
  7. Refactor hard-to-test code behind interfaces or pure functions.

Do not fake coverage by testing private methods directly. Do not mark real code with @codeCoverageIgnore because it is inconvenient. Ignore only code that genuinely cannot or should not be covered, such as defensive process exits, framework bootstrap glue, or environment-specific branches.

A practical CI command

For a small Composer project, this is enough:

composer validate --strict
composer dump-autoload --strict-psr
vendor/bin/phpunit --testsuite Unit
vendor/bin/phpunit --testsuite Integration
vendor/bin/phpunit --coverage-text --coverage-clover build/logs/clover.xml

If the suite is slow, do not remove tests. Split suites, remove accidental network calls, replace slow fixtures, and keep integration tests focused.

What good tests look like

Good PHPUnit tests have these properties:

  • They prove behavior visible to the caller.
  • They use exact assertions.
  • They create their own data.
  • They do not depend on test order.
  • They use mocks only at boundaries.
  • They keep unit and integration concerns separate.
  • They fail with a clear reason.
  • They make refactoring safer.

[IMAGE: Supporting visual 3 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 3]

Bad tests usually know too much about implementation, share state, hide errors with loose assertions, or assert only that a method returns "something".

Final checklist

Before calling a project tested, check this:

  • Can a new developer run vendor/bin/phpunit after composer install?
  • Are test classes under tests/ and production classes under src/?
  • Does phpunit.xml define clear suites?
  • Are unit tests fast enough to run during normal development?
  • Are database tests isolated?
  • Are data providers named?
  • Are exception tests checking the exact failing branch?
  • Are mocks limited to side-effect boundaries?
  • Does coverage include production code and exclude test code?
  • Do high-coverage files also have meaningful assertions?

[IMAGE: Supporting visual 3 for PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage, showing PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage decisions, examples, and PHPUnit, PHP, Testing. Alt: PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage php-unit-testing-with-phpunit-code-coverage visual 3]

Coverage gives you a map. PHPUnit gives you the runner. The value comes from writing tests that lock down behavior clearly enough that you can change the code without guessing.

FAQ

What is PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage?

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage is a practical testing topic that should be evaluated through implementation scope, production risk, testing, documentation, and long-term maintainability.

When should a team use PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage?

Use PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage when it solves a real project constraint, improves clarity, or reduces operational risk. Avoid it when it only adds novelty or hides behavior from future maintainers.

What is the biggest risk with PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage?

The biggest risk is copying a pattern without its context. Production systems need clear boundaries, rollback options, tests, and observability before a technique becomes dependable.

How do you test PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage?

Test the smallest unit that owns the behavior, then add integration coverage for the path users or systems actually rely on. Include failure cases, configuration differences, and regression checks.

How does PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage affect SEO and AI search visibility?

It improves visibility when the article gives a direct answer, expert context, structured headings, internal links, trustworthy references, and FAQ content that matches the visible page.

Conclusion

PHP Unit Testing With PHPUnit: From Zero to 100% Code Coverage is worth doing when the implementation improves clarity, reliability, or delivery speed. It is not worth doing when it hides ownership, increases operational risk, or makes the system harder to explain.

Use the framework above as a review checklist. Then connect this topic to the rest of the project documentation so readers can move from concept to implementation without losing context.

Top