twada/phpunit-size-distribution

A PHPUnit extension that measures and reports test size distribution (Small/Medium/Large)

dev-main 2026-01-14 07:53 UTC

Requires

• php: ^8.1
• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.65
• phpstan/phpstan: ^2.1
• phpunit/phpcov: ^9.0 || ^10.0 || ^11.0
• stolt/lean-package-validator: ^5.2

MIT

• Takuto WADA

• testing
• phpunit
• extension
• Metrics
• test-size
• test-pyramid

README

A PHPUnit extension that measures and reports test size distribution (Small/Medium/Large).

Overview

PHPUnit supports test size classification through #[Small], #[Medium], and #[Large] attributes. This extension analyzes your test suite and reports the distribution of test sizes, helping you maintain a healthy test pyramid.

Requirements

• PHP 8.1+
• PHPUnit 10.5+ / 11.x / 12.x

Installation

composer require --dev twada/phpunit-size-distribution

Configuration

Register the extension in your phpunit.xml:

<phpunit>
    <!-- ... -->
    <extensions>
        <bootstrap class="Twada\PHPUnitSizeDistribution\TestSizeReporterExtension"/>
    </extensions>
</phpunit>

Usage

Run your tests as usual:

vendor/bin/phpunit

After test execution, you'll see a report like this:

Test Size Distribution
======================
Small:   5 tests ( 62.5%)
Medium:  1 tests ( 12.5%)
Large:   1 tests ( 12.5%)
None:    1 tests ( 12.5%)
----------------------
Total:   8 tests

Test Size Categories

Category	Description
Small	Tests marked with #[Small] attribute
Medium	Tests marked with #[Medium] attribute
Large	Tests marked with #[Large] attribute
None	Tests without any size attribute

Example

<?php

use PHPUnit\Framework\Attributes\Small;
use PHPUnit\Framework\TestCase;

#[Small]
final class UserTest extends TestCase
{
    public function testName(): void
    {
        // This test is counted as "Small"
    }
}

Counting Rules

• Counted: Passed, Failed, and Errored tests
• Not counted: Skipped and Incomplete tests

Limitations

• Class-level attributes only: PHPUnit's size attributes (#[Small], #[Medium], #[Large]) can only be applied at the class level, not on individual test methods. All test methods in a class inherit the class's size.

• DataProvider inheritance: Test cases generated by DataProviders inherit the size attribute from their test class.

• No runtime detection: This extension reads PHPUnit's metadata attributes. It does not measure actual execution time or resource usage.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.

Author

Takuto Wada