Phpunit Laravel Package

Getting Started

1. Install via Composer: composer require --dev phperf/phpunit
2. Bootstrap: In your phpunit.xml, ensure <php> contains a PERF_ENABLED environment variable (e.g., <env name="PERF_ENABLED" value="1" force="false"/>) to activate performance assertions (disabled by default in CI for consistency).
3. First use case: Add a simple performance assertion to an existing test:

   use Perf\PHPUnit\Assertions;
   
   public function testProcessBatchDoesNotExceedTimeLimit()
   {
       $this->assertTimeLimit(0.1, function () {
           $this->service->processBatch(1000);
       });
   }
   

   This checks that the closure runs within 100ms—failures surface in PHPUnit’s output like any other assertion.

Implementation Patterns

• Use in CI: Enable performance assertions only on critical pipelines (e.g., PERF_ENABLED=1 in a nightly job) to avoid slowing down routine PR checks.
• Assertion types:
  • assertTimeLimit($seconds, callable $test, string $message = '')
  • assertExecutionTime($callable, callable $callback) to capture and inspect raw timing data (e.g., store for trend analysis).
• Group tests: Tag performance tests with @performance and run separately via --group=performance.
• Tolerance thresholds: Wrap fragile operations (e.g., ORM hydration, file I/O) with assertTimeLimit() + assertLessThan() to allow minor variance:

  $time = $this->measureExecutionTime(fn() => $this->cache->warm());
  $this->assertLessThan(0.25, $time, 'Cache warmup must stay under 250ms');
  

• Baseline generation: Run performance tests locally once, record baseline values, then tighten thresholds incrementally as you optimize.

Gotchas and Tips

• Environment-dependent variance: Performance varies by host (CPU, I/O, CPU throttling). Always run performance tests in consistent environments (e.g., Docker containers with fixed CPU limits).
• Noise handling: Wrap non-deterministic operations in assertTimeLimit() only if test passes ≥5 times in a row with low variance; otherwise use assertExecutionTime() and validate ranges later.
• CI quirks: By default, assertions are disabled unless PERF_ENABLED=1. This avoids false CI failures on shared runners—remember to explicitly enable in your pipeline config.
• Extension point: Extend Perf\PHPUnit\TestCase to add project-specific assertion helpers (e.g., assertDbQueryCount($max)).
• Debugging: Use PERF_VERBOSE=1 to log timing details to stderr when assertions fail—helps identify hotspots without modifying tests.
• Limitation: Only measures wall-clock time; no CPU profiling or memory stats. For deeper diagnostics, pair with Xdebug or Blackfire.