kaniosx/phpunit-performance-profiler

A lightweight memory and execution time profiler for PHPUnit and Pest.

v1.0.0 2026-08-05 09:38 UTC

Requires

• php: >=8.2
• phpunit/phpunit: ^10.0 || ^11.0

MIT

Published on Packagist.org on 2026-08-05 09:44 UTC

README

A lightweight memory and execution time profiler for PHPUnit and Pest. Turn performance budgets into simple, first-class assertions inside your existing test suite — no external profiling tools or infrastructure required.

Requirements

• PHP >= 8.2
• PHPUnit ^10.0 || ^11.0

Installation

composer require kaniosx/phpunit-performance-profiler

Usage

Add the AssertsPerformance trait to your test case (or a shared base test case) and call the assertion methods with the code you want to measure:

use Kaniosx\PhpunitPerformanceProfiler\AssertsPerformance;
use PHPUnit\Framework\TestCase;

final class ReportGeneratorTest extends TestCase
{
    use AssertsPerformance;

    public function testGeneratingTheReportStaysWithinTheMemoryBudget(): void
    {
        $this->assertMemoryPeakUnder(64, function (): void {
            (new ReportGenerator())->generate();
        });
    }

    public function testGeneratingTheReportStaysWithinTheTimeBudget(): void
    {
        $this->assertExecutionTimeUnder(200, function (): void {
            (new ReportGenerator())->generate();
        });
    }
}

assertMemoryPeakUnder(float $maxMegabytes, callable $callback, string $message = '')

Fails if peak memory usage while running $callback exceeds $maxMegabytes.

assertExecutionTimeUnder(float $maxMilliseconds, callable $callback, string $message = '')

Fails if $callback takes longer than $maxMilliseconds to run.

Both methods throw InvalidArgumentException if the given budget is not a positive number, and accept an optional custom $message to override the default failure message.

Using the profiler directly

If you need raw metrics instead of an assertion (e.g. to log them, or to assert on both memory and time from a single execution), call Profiler::run() directly:

use Kaniosx\PhpunitPerformanceProfiler\Profiler;

$result = Profiler::run(function (): void {
    (new ReportGenerator())->generate();
});

echo $result->getFormattedDuration();     // e.g. "12.345 ms"
echo $result->getFormattedMemoryPeak();   // e.g. "3.42 MB"

Profiler::run() returns a ProfileResult with:

Property	Type	Description
durationSeconds	float	Wall-clock execution time of the callback, in seconds.
memoryUsageBytes	int	Net memory retained after the callback ran.
memoryPeakBytes	int	Peak memory usage recorded since process start (see note below).

Note: memoryPeakBytes reflects PHP's process-wide peak memory usage (memory_get_peak_usage()), not just the peak during the callback. If something earlier in the same process allocated more memory than your callback does, that earlier peak is what you'll see. Run performance-sensitive tests in isolation (e.g. @runInSeparateProcess) if you need a clean baseline.

Running the tests

composer install
vendor/bin/phpunit

License

This package is licensed under the MIT License.