Phpunit Slow Test Detector Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require --dev ergebnis/phpunit-slow-test-detector
   

2. Configure PHPUnit (for PHPUnit 10+): Add the extension to phpunit.xml:

   <phpunit ...>
       <extensions>
           <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
       </extensions>
   </phpunit>
   

3. Run tests:

   ./vendor/bin/phpunit
   

   The tool will now report tests exceeding the default 500ms threshold.

First Use Case

Identify slow tests in a CI/CD pipeline or local development to:

• Optimize test suites.
• Flag flaky or inefficient tests.
• Enforce performance standards.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Add the package to composer.json under require-dev.
   • Configure thresholds (e.g., maximum-duration="1000" for 1-second tests).
   • Use exit codes or annotations to fail builds on slow tests.

2. Local Development:

   • Run tests with --debug to see detailed timing:

     ./vendor/bin/phpunit --debug
     

   • Use stderr output for cleaner terminal logs (PHPUnit 6–9):

     <phpunit ... stderr="true">
     

3. Custom Thresholds:

   • Override defaults per test suite:

     <phpunit ...>
         <extensions>
             <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
         </extensions>
         <parameters>
             <parameter name="maximum-duration" value="2000" type="int"/>
             <parameter name="maximum-count" value="5" type="int"/>
         </parameters>
     </phpunit>
     

Laravel-Specific Tips

• Test Suite Isolation: Use separate phpunit.xml files for unit, feature, and integration tests with tailored thresholds. Example: phpunit.feature.xml:

  <phpunit ...>
      <extensions>
          <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
      </extensions>
      <parameters>
          <parameter name="maximum-duration" value="3000" type="int"/>
      </parameters>
  </phpunit>
  

• Artisan Integration: Extend Laravel’s phpunit Artisan command to pass custom configs:

  // app/Console/Kernel.php
  protected $commands = [
      \Illuminate\Foundation\Console\Artisan::class,
      \App\Console\Commands\RunSlowTests::class, // Custom command
  ];
  

  // app/Console/Commands/RunSlowTests.php
  public function handle()
  {
      $this->call('phpunit', [
          '--configuration' => 'phpunit.slow.xml',
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. PHPUnit Version Mismatch:

   • Error: Class not found or Invalid configuration.
   • Fix: Verify compatibility (e.g., PHPUnit 6 uses <listeners>, while 10+ uses <extensions>).
   • Debug: Check the official docs for your version.

2. Threshold Overrides:

   • Issue: Global config ignored if per-test annotations (e.g., @slow) are used.
   • Fix: Use <parameters> in phpunit.xml for global control.

3. CI Timeouts:

   • Problem: Slow tests may cause CI jobs to fail due to timeouts, not the detector.
   • Solution: Set maximum-duration conservatively (e.g., 2–3x your CI timeout).

Debugging

• Silent Failures: If no slow tests are reported, verify:
  • The extension is loaded (check phpunit --debug output).
  • Thresholds are realistic (e.g., maximum-duration="50" for fast tests).
• Output Redirection: Redirect stderr to a file for CI logs:

  ./vendor/bin/phpunit 2> slow-tests.log
  

Extension Points

1. Custom Reporters: Extend the Ergebnis\PHPUnit\SlowTestDetector\Reporter\DefaultReporter to format output (e.g., JSON for APIs):

   use Ergebnis\PHPUnit\SlowTestDetector\Reporter\DefaultReporter;
   use Ergebnis\PHPUnit\SlowTestDetector\Reporter\SlowTest;
   
   class JsonReporter extends DefaultReporter {
       public function report(SlowTest $slowTest) {
           echo json_encode($slowTest->toArray()) . PHP_EOL;
       }
   }
   

   Register it in phpunit.xml:

   <extensions>
       <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
       <service class="App\Tests\JsonReporter" method="register"/>
   </extensions>
   

2. Dynamic Thresholds: Use environment variables or Laravel’s .env to adjust thresholds:

   <parameters>
       <parameter name="maximum-duration" value="{env('TEST_SLOW_THRESHOLD')}" type="int"/>
   </parameters>
   

   Set in .env:

   TEST_SLOW_THRESHOLD=1500
   

3. Excluding Tests: Skip specific tests from detection by annotating them:

   /**
    * @slow-exclude
    */
   public function testExternalApiCall() { ... }