PHPUnit — The Standard Testing Framework for PHP

Introduction

PHPUnit is the most widely adopted testing framework in the PHP ecosystem. Created by Sebastian Bergmann, it brings xUnit-style testing to PHP with a comprehensive assertion library, built-in mocking, and code coverage reporting. Almost every major PHP framework and CMS integrates with PHPUnit out of the box.

What PHPUnit Does

• Provides over 60 assertion methods for values, arrays, strings, exceptions, and output
• Includes a built-in mock object framework for stubs, spies, and expectations
• Generates code coverage reports in HTML, Clover XML, and Cobertura formats
• Supports data providers for parameterized test methods
• Integrates with CI pipelines via JUnit XML output

Architecture Overview

PHPUnit runs as a CLI tool that discovers test classes extending TestCase. The runner reflects on each class to find methods prefixed with test or annotated with #[Test]. Each test method executes in an isolated instance so that object state does not persist between tests. Coverage collection uses either Xdebug, PCOV, or php-code-coverage as the driver, instrumenting source files to track executed lines and branches.

Self-Hosting & Configuration

• Install globally via Composer or as a project-level dev dependency
• Configure with phpunit.xml for test suites, bootstrap files, and coverage filters
• Use --filter to run specific test methods or classes by name pattern
• Enable --testdox for human-readable output that documents behavior
• Set XDEBUG_MODE=coverage when collecting coverage with Xdebug 3+

Key Features

• Rich assertion API covers types, arrays, JSON, XML, files, and regular expressions
• Data providers generate multiple test runs from arrays or generators
• Mock builder supports interface mocking, method stubbing, and invocation counting
• Code coverage with line, branch, and path-level granularity
• Attributes (PHP 8.1+) replace docblock annotations for cleaner metadata

Comparison with Similar Tools

• Pest — a wrapper around PHPUnit with a more concise syntax; PHPUnit offers the underlying engine and full API
• Codeception — higher-level acceptance and functional testing; PHPUnit focuses on unit and integration tests
• PHPSpec — spec-driven development approach; PHPUnit follows the classic xUnit pattern
• Behat — BDD with Gherkin syntax; PHPUnit provides assertion-based tests without a domain language layer
• SimpleTest — an older PHP testing library now largely superseded by PHPUnit

FAQ

Q: Which PHP versions does PHPUnit support? A: PHPUnit 11 requires PHP 8.2+. Older PHPUnit branches support earlier PHP versions.

Q: How do I run PHPUnit tests in parallel? A: Use the paratest package, which wraps PHPUnit and distributes tests across multiple processes.

Q: Can PHPUnit test Laravel applications? A: Yes. Laravel ships with PHPUnit pre-configured and provides helper traits for HTTP, database, and queue testing.

Q: Does PHPUnit support snapshot testing? A: Not natively. Use the spatie/phpunit-snapshot-assertions package for snapshot comparisons.

Sources

• https://github.com/sebastianbergmann/phpunit
• https://docs.phpunit.de/