README

This project provides a composer package and a Phar archive with an extension for detecting slow tests in phpunit/phpunit.

The extension is compatible with the following versions of phpunit/phpunit:

• phpunit/phpunit:^8.5.19
• phpunit/phpunit:^9.0.0
• phpunit/phpunit:^10.0.0

Installation

Installation with composer

Run

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

to install ergebnis/phpunit-slow-test-detector as a composer package when using phpunit/phpunit:^8.5.19, phpunit/phpunit:^9.0.0, or phpunit/phpunit:^10.0.0.

Installation as Phar

Download phpunit-slow-test-detector.phar from the latest release when using phpunit/phpunit:^10.0.0.

Usage

Bootstrapping the extension

Before the extension can detect slow tests in phpunit/phpunit, you need to bootstrap it. The bootstrapping mechanism depends on the version of phpunit/phpunit you are using.

Bootstrapping the extension as a composer package when using phpunit/phpunit:^8.5.19

To bootstrap the extension as a composer package when using phpunit/phpunit:^8.5.19, adjust your phpunit.xml configuration file and configure the extensions element:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
+    <extensions>
+        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+    </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
         </testsuite>
     </testsuites>
 </phpunit>

Bootstrapping the extension as a composer package when using phpunit/phpunit:^9.0.0

To bootstrap the extension as a composer package when using phpunit/phpunit:^9.0.0, adjust your phpunit.xml configuration file and configure the extensions element:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
+    <extensions>
+        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+    </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
         </testsuite>
     </testsuites>
 </phpunit>

Bootstrapping the extension as a composer package when using phpunit/phpunit:^10.0.0

To bootstrap the extension as a composer package when using phpunit/phpunit:^10.0.0, adjust your phpunit.xml configuration file and configure the extensions element:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
+    <extensions>
+        <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+    </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
         </testsuite>
     </testsuites>
 </phpunit>

Bootstrapping the extension as a PHAR when using phpunit/phpunit:^10.0.0

To bootstrap the extension as a PHAR when using phpunit/phpunit:^10.0.0, adjust your phpunit.xml configuration file and configure the extensionsDirectory attribute of the <phpunit> element:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
+    extensionsDirectory="directory/where/you/saved/the/extension/phars"
 >
+    <extensions>
+        <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+    </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
         </testsuite>
     </testsuites>
 </phpunit>

Configuring the extension

You can configure the extension with the following options in your phpunit.xml configuration file:

• maximum-count, an int, the maximum count of slow test that should be reported, defaults to 10
• maximum-duration, an int, the maximum duration in milliseconds for a test before the extension considers it as a slow test, defaults to 500

The configuration mechanism depends on the version of phpunit/phpunit you are using.

Configuring the extension when using phpunit/phpunit:^8.5.19

The following example configures the maximum count of slow tests to three, and the maximum duration for all tests to 250 milliseconds when using phpunit/phpunit:^8.5.19:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
     <extensions>
-        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension">
+            <arguments>
+                <array>
+                    <element key="maximum-count">
+                        <integer>3</integer>
+                    </element>
+                    <element key="maximum-duration">
+                        <integer>250</integer>
+                    </element>
+                </array>
+            </arguments>
+        </extension>
     </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
        </testsuite>
     </testsuites>
 </phpunit>

Configuring the extension when using phpunit/phpunit:^9.0.0

The following example configures the maximum count of slow tests to three, and the maximum duration for all tests to 250 milliseconds when using phpunit/phpunit:^9.0.0:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
     <extensions>
-        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+        <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension">
+            <arguments>
+                <array>
+                    <element key="maximum-count">
+                        <integer>3</integer>
+                    </element>
+                    <element key="maximum-duration">
+                        <integer>250</integer>
+                    </element>
+                </array>
+            </arguments>
+        </extension>
     </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
        </testsuite>
     </testsuites>
 </phpunit>

Configuring the extension when using phpunit/phpunit:^10.0.0

The following example configures the maximum count of slow tests to three, and the maximum duration for all tests to 250 milliseconds when using phpunit/phpunit:^10.0.0:

 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
     bootstrap="vendor/autoload.php"
 >
     <extensions>
-        <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+        <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension">
+            <parameter name="maximum-count" value="3"/>
+            <parameter name="maximum-duration" value="250"/>
+        </bootstrap>
     </extensions>
     <testsuites>
         <testsuite name="unit">
             <directory>test/Unit/</directory>
        </testsuite>
     </testsuites>
 </phpunit>

Configuring the maximum duration per test case

You can configure the maximum duration for a single test case with

• an Attribute\MaximumDuration attribute when using phpunit/phpunit:^10.0.0
• a @maximumDuration annotation in the DocBlock when using phpunit/phpunit:^8.5.19 or phpunit/phpunit:^9.0.0
• a @slowThreshold annotation in the DocBlock when using phpunit/phpunit:^8.5.19 or phpunit/phpunit:^9.0.0

The following example configures the maximum durations for single test cases to 5.000 ms, 4.000 ms, and 3.000 ms:

<?php

declare(strict_types=1);

use PHPUnit\Framework;
use Ergebnis\PHPUnit\SlowTestDetector;

final class ExtraSlowTest extends Framework\TestCase
{
    /**
     */
    #[SlowTestDetector\Attribute\MaximumDuration(5000)]
    public function testExtraExtraSlow(): void
    {
        // ...
    }

    /**
     * @maximumDuration 4000
     */
    public function testAlsoQuiteSlow(): void
    {
        // ...
    }

    /**
     * @slowThreshold 3000
     */
    public function testQuiteSlow(): void
    {
        // ...
    }
}

Note

Support for the @slowThreshold annotation exists only to help you move from johnkary/phpunit-speedtrap. It will be deprecated and removed in the near future.

Running tests

When you have bootstrapped the extension, you can run your tests as usually:

vendor/bin/phpunit

When the extension has detected slow tests, it will report them:

PHPUnit 10.0.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.1.0
Configuration: test/EndToEnd/Default/phpunit.xml
Random Seed:   1676103726

.............                                                                                                                                                                                                                                                                                                   13 / 13 (100%)

Detected 11 tests that took longer than expected (500 ms).

 1. 1.604 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#9
 2. 1.505 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#8
 3. 1.403 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#7
 4. 1.303 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#6
 5. 1.205 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#5
 6. 1.103 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#4
 7. 1.005 s Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#3
 8.  905 ms Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#2
 9.  805 ms Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#1
10.  705 ms Ergebnis\PHPUnit\SlowTestDetector\Test\EndToEnd\Default\SleeperTest::testSleeperSleepsLongerThanDefaultMaximumDurationWithDataProvider#0

There is 1 additional slow test that is not listed here.

Time: 00:12.601, Memory: 8.00 MB

OK (13 tests, 13 assertions)

Understanding measured test durations

A duration of invoking PHPUnit\Framework\TestCase::runBare() method is measured.

The measured duration includes time spent in PHPUnit\Framework\TestCase::setUp() and PHPUnit\Framework\TestCase::tearDown() methods and respective before and after PHPUnit test hooks.

A duration if invoking PHPUnit\Framework\TestCase::setUpBeforeClass() and PHPUnit\Framework\TestCase::tearDownAfterClass() methods is NOT measured as it is not per test, but per test class. An exception are tests run in a separate process, in this case, TestCase::setUpBeforeClass() and TestCase::tearDownAfterClass() durations are measured as the methods are executed for each test in the TestCase::runBare()](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestRunner.php#L101) method.

Changelog

The maintainers of this project record notable changes to this project in a changelog.

Contributing

The maintainers of this project suggest following the contribution guide.

Code of Conduct

The maintainers of this project ask contributors to follow the code of conduct.

General Support Policy

The maintainers of this project provide limited support.

You can support the maintenance of this project by sponsoring @localheinz or requesting an invoice for services related to this project.

PHP Version Support Policy

This project supports PHP versions with active and security support.

The maintainers of this project add support for a PHP version following its initial release and drop support for a PHP version when it has reached the end of security support.

Security Policy

This project has a security policy.

License

This project uses the MIT license.

Credits

This package is inspired by johnkary/phpunit-speedtrap, originally licensed under MIT by John Kary.

Social

Follow @localheinz and @ergebnis on Twitter.