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.xml: Add the extension to your PHPUnit config based on your version (see README for version-specific syntax). Example for PHPUnit 10+:

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

3. Run tests:

   ./vendor/bin/phpunit
   

   The extension will now report slow tests (default threshold: 500ms).

First Use Case

Identify slow tests in CI/CD pipelines:

• Add the package to your devDependencies and configure it in phpunit.xml.
• Run tests in CI (e.g., GitHub Actions) and fail builds if slow tests exceed thresholds.
• Example CI check:

  - name: Run PHPUnit
    run: ./vendor/bin/phpunit --stop-on-failure
  

Implementation Patterns

Workflows

1. Daily Development:

   • Run tests locally with the extension enabled to catch slow tests early.
   • Use the default maximum-duration="500" to flag tests exceeding 500ms.
   • Example config:

     <extensions>
         <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
     </extensions>
     <php>
         <server name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION" value="1000"/>
     </php>
     

     (Sets threshold to 1 second for broader detection.)

2. CI/CD Integration:

   • Configure thresholds stricter in CI (e.g., maximum-duration="200").
   • Fail builds if slow tests exceed limits:

     <extensions>
         <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
     </extensions>
     <php>
         <env name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION" value="200"/>
         <env name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_COUNT" value="0"/> <!-- Fail on any slow test -->
     </php>
     

3. Team Onboarding:

   • Add a pre-commit hook to run PHPUnit with the extension and block slow tests:

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

     (Use tools like roave/security-advisories alongside.)

Integration Tips

• Laravel-Specific: Use Laravel’s phpunit.xml in tests/ and extend it for slow-test detection:

  <testsuites>
      <testsuite name="Application Test Suite">
          <directory suffix="Test.php">./tests/Feature</directory>
      </testsuite>
  </testsuites>
  <extensions>
      <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
  </extensions>
  

• Parallel Testing: If using --parallel, configure thresholds per group:

  <extensions>
      <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
  </extensions>
  <php>
      <env name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION" value="300"/> <!-- Stricter for parallel -->
  </php>
  

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • PHPUnit 6.x uses <listeners>, while 7.x+ uses <extensions>.
   • Fix: Update phpunit.xml per README.
   • Example error:

     [PHPUnit\Configuration\Exception] Extension "Ergebnis\PHPUnit\SlowTestDetector\Extension" not found.
     

2. Threshold Overrides:

   • Environment variables (PHPUNIT_SLOW_TEST_DETECTOR_*) take precedence over XML config.
   • Debug: Check if thresholds are applied:

     ./vendor/bin/phpunit --debug
     

3. PHAR vs. Composer:

   • PHAR requires extensionsDirectory in phpunit.xml.
   • Tip: Prefer Composer for Laravel projects to avoid manual PHAR management.

Debugging

• Silent Failures: If slow tests aren’t reported, verify:

  • The extension is loaded (check phpunit --debug output).
  • Thresholds are set (default: 500ms).
  • PHPUnit version compatibility (e.g., 6.5.0 uses <listeners>).

• Custom Output: Redirect slow-test logs to a file:

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

Extension Points

1. Custom Thresholds: Override defaults via:

   • XML:

     <php>
         <env name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION" value="1000"/>
     </php>
     

   • CLI:

     PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION=1000 ./vendor/bin/phpunit
     

2. Excluding Tests: Use @skip annotations or filter test suites:

   <testsuites>
       <testsuite name="Fast Tests">
           <directory>./tests/Unit</directory>
           <exclude>*/Slow*</exclude>
       </testsuite>
   </testsuites>
   

3. CI-Specific Configs: Use Laravel’s .env to dynamically set thresholds:

   PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION=200
   

   Load in phpunit.xml:

   <php>
       <env name="PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION" value="{env('PHPUNIT_SLOW_TEST_DETECTOR_MAXIMUM_DURATION', '500')}"/>
   </php>
   

Pro Tips

• Visual Alerts: Integrate with Slack/Teams using CI logs:

  - name: Post Slow Test Alert
    if: contains(steps.run-tests.outputs.stdout, 'Detected slow tests')
    run: curl -X POST -H 'Content-type: application/json' --data '{"text":"Slow tests detected!"}' $SLACK_WEBHOOK
  

• Historical Tracking: Log slow-test durations to a database (e.g., Laravel’s logs table) for trend analysis.
• Performance Profiling: Combine with xdebug to identify bottlenecks in slow tests:

  XDEBUG_TRIGGER=1 ./vendor/bin/phpunit --filter SlowTest::testMethod