Merge pull request #83 from johnkary/extension-upgrade

Use PHPUnit Extension system instead of Listener
johnkary · Oct 17, 2022 · cf1284b · cf1284b
2 parents f1cc189 + 372da42
commit cf1284b
Show file tree

Hide file tree

Showing 9 changed files with 129 additions and 89 deletions.
diff --git a/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml
@@ -19,12 +19,6 @@ jobs:
 
       matrix:
         include:
-          - php-version: "7.1"
-            phpunit-version: "7.*"
-
-          - php-version: "7.2"
-            phpunit-version: "7.*"
-
           - php-version: "7.2"
             phpunit-version: "8.*"
 
@@ -46,6 +40,12 @@ jobs:
           - php-version: "8.0"
             phpunit-version: "9.*"
 
+          - php-version: "8.1"
+            phpunit-version: "8.*"
+
+          - php-version: "8.1"
+            phpunit-version: "9.*"
+
     steps:
       - name: "Checkout"
         uses: "actions/checkout@v2"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,23 @@ CHANGELOG
 View diff for a specific commit:  
 https://github.com/johnkary/phpunit-speedtrap/commit/XXX where XXX is the commit hash
 
+View diff between two versions:  
+https://github.com/johnkary/phpunit-speedtrap/compare/v4.0.0...v5.0.0
+
+## 5.0 (xxxx-xx-xx)
+
+Version 5.0 is the largest change since v1.0. It now uses PHPUnit's Extension
+and Hook systems, which have more restrictions on what an Extension is allowed
+to do.
+
+Changes are required if you have extended SpeedTrapListener. See
+[UPGRADE.md](UPGRADE.md) for upgrading your subclass to support 5.0.
+
+* SpeedTrap now requires PHPUnit 8+ and PHP 7.2+,
+* Moved namespace from `JohnKary\PHPUnit\Listener\SpeedTrapListener` to `JohnKary\PHPUnit\Extension\SpeedTrap`
+* `phpunit.xml` requires registering using <extension> element instead of <listener> element. See README.
+* Removed option `stopOnSlow` because Extensions can no longer manipulate the Test Runner
+
 ## 4.0.1 (2022-10-16)
 
 * README documents working with Symfony Framework `simple-phpunit`

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ SpeedTrap reports on slow-running PHPUnit tests right in the console.
 
 Many factors affect test execution time. A test not properly isolated from variable latency (database, network, etc.) and even basic load on the test machine will cause test execution times to fluctuate.
 
-SpeedTrap helps **identify slow tests** but cannot explain **why** those tests are slow. For that consider using [Blackfire.io](https://blackfire.io) to profile the test suite, or another PHPUnit listener [PHPUnit\_Listener\_XHProf](https://github.com/sebastianbergmann/phpunit-testlistener-xhprof), to specifically identify slow code.
+SpeedTrap helps **identify slow tests** but cannot explain **why** those tests are slow. Consider using [Blackfire.io](https://blackfire.io) to profile the test suite to specifically identify slow code.
 
 ![Screenshot of terminal using SpeedTrap](https://i.imgur.com/xSpWL4Z.png)
 
@@ -20,13 +20,13 @@ SpeedTrap is installed using [Composer](http://getcomposer.org). Add it as a `re
 ## Usage
 
 Enable with all defaults by adding the following code to your project's `phpunit.xml` file:
-
+ 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
 ...
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
-    </listeners>
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
+    </extensions>
 </phpunit>
 ```
 
@@ -38,16 +38,15 @@ SpeedTrap also supports these parameters:
 
 * **slowThreshold** - Number of milliseconds when a test is considered "slow" (Default: 500ms)
 * **reportLength** - Number of slow tests included in the report (Default: 10 tests)
-* **stopOnSlow** - Stop execution upon first slow test (Default: false). Activate by setting "true".
 
 Each parameter is set in `phpunit.xml`:
 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
     <!-- ... other suite configuration here ... -->
 
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener">
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap">
             <arguments>
                 <array>
                     <element key="slowThreshold">
@@ -56,13 +55,10 @@ Each parameter is set in `phpunit.xml`:
                     <element key="reportLength">
                         <integer>10</integer>
                     </element>
-                    <element key="stopOnSlow">
-                        <boolean>false</boolean>
-                    </element>
                 </array>
             </arguments>
-        </listener>
-    </listeners>
+        </extension>
+    </extensions>
 </phpunit>
 ```
 
@@ -89,15 +85,15 @@ Setting `@slowThreshold 0` will never report that test as slow.
 
 ## Disable slowness profiling using an environment variable
 
-SpeedTrapListener profiles for slow tests when enabled in phpunit.xml. But using an environment variable named `PHPUNIT_SPEEDTRAP` can enable or disable the listener.
+SpeedTrap profiles for slow tests when enabled in phpunit.xml. But using an environment variable named `PHPUNIT_SPEEDTRAP` can enable or disable the extension:
 
     $ PHPUNIT_SPEEDTRAP="disabled" ./vendor/bin/phpunit
 
 #### Use case: Disable profiling in development, but profile with Travis CI
 
 Travis CI is popular for running tests in the cloud after pushing new code to a repository.
 
-Step 1) Enable SpeedTrapListener in phpunit.xml, but set `PHPUNIT_SPEEDTRAP="disabled"` to disable profiling when running tests.
+Step 1) Enable SpeedTrap in phpunit.xml, but set `PHPUNIT_SPEEDTRAP="disabled"` to disable profiling when running tests.
 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
@@ -106,9 +102,9 @@ Step 1) Enable SpeedTrapListener in phpunit.xml, but set `PHPUNIT_SPEEDTRAP="dis
         <env name="PHPUNIT_SPEEDTRAP" value="disabled" />
     </php>
 
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
-    </listeners>
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
+    </extensions>
 </phpunit>
 ```
 
@@ -130,14 +126,14 @@ Step 3) View the Travis CI build output and read the slowness report printed in
 
 #### Use case: Enable profiling in development, but disable with Travis CI
 
-Step 1) Enable SpeedTrapListener in phpunit.xml. The slowness report will output during all test suite executions.
+Step 1) Enable SpeedTrap in phpunit.xml. The slowness report will output during all test suite executions.
 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
 ...
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
-    </listeners>
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
+    </extensions>
 </phpunit>
 ```
 
@@ -155,11 +151,11 @@ env:
 
 Step 3) View the Travis CI build output and confirm the slowness report is not printed in the console.
 
-#### Use case: Only enable SpeedTrapListener on demand via command-line
+#### Use case: Only enable SpeedTrap on demand via command-line
 
 Useful when you only want to profile slow tests once in a while.
 
-Step 1) Setup phpunit.xml to enable SpeedTrapListener, but disable slowness profiling by setting `PHPUNIT_SPEEDTRAP="disabled"` like this:
+Step 1) Setup phpunit.xml to enable SpeedTrap, but disable slowness profiling by setting `PHPUNIT_SPEEDTRAP="disabled"` like this:
 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
@@ -168,9 +164,9 @@ Step 1) Setup phpunit.xml to enable SpeedTrapListener, but disable slowness prof
         <env name="PHPUNIT_SPEEDTRAP" value="disabled" />
     </php>
 
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
-    </listeners>
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
+    </extensions>
 </phpunit>
 ```
 
@@ -195,9 +191,12 @@ phpunit.xml.dist
         <env name="SYMFONY_PHPUNIT_REQUIRE" value="johnkary/phpunit-speedtrap:^4"/>
         <env name="SYMFONY_PHPUNIT_VERSION" value="9"/>
     </php>
+
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap" />
+    </extensions>
 </phpunit>
 ```
-(add the listener as described above)
 
 Using the above example, running `vendor/bin/simple-phpunit` will now install the latest PHPUnit 9 and require the latest phpunit-speedtrap v4.
 

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,3 +1,40 @@
+UPGRADE FROM 4.x to 5.0
+=======================
+
+This library's v4 core file `JohnKary\PHPUnit\Listener\SpeedTrapListener` has been
+replaced by `JohnKary\PHPUnit\Extension\SpeedTrap` in v5. This change reflects
+switching from PHPUnit's Listener system to its Hook system.
+
+The `SpeedTrap` Extension must be registered differently in `phpunit.xml`:
+
+```xml
+<phpunit bootstrap="vendor/autoload.php">
+    ...
+-    <listeners>
+-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
+-    </listeners>
++    <extensions>
++        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap">
++            <arguments>
++                <array>
++                    <element key="slowThreshold">
++                       <integer>500</integer>
++                   </element>
++                   <element key="reportLength">
++                       <integer>5</integer>
++                   </element>
++               </array>
++           </arguments>
++       </extension>
++   </extensions>
+</phpunit>
+```
+
+If you have extended the old `JohnKary\PHPUnit\Listener\SpeedTrapListener`, you
+must extend the new `JohnKary\PHPUnit\Extension\SpeedTrap`. There are various
+method name changes that may affect your custom subclass. See [PR #83](https://github.com/johnkary/phpunit-speedtrap/pull/83)
+for how the new class has changed.
+
 UPGRADE FROM 3.x to 4.0
 =======================
 

diff --git a/composer.json b/composer.json
@@ -4,6 +4,9 @@
     "description": "Find and report on slow tests in your PHPUnit test suite",
     "keywords": [
         "PHPUnit",
+        "extension",
+        "hook",
+        "listener",
         "slow",
         "profile"
     ],
@@ -16,22 +19,22 @@
         }
     ],
     "require": {
-        "php": ">=7.1",
-        "phpunit/phpunit": "^7.0 || ^8.0 || ^9.0"
+        "php": ">=7.2",
+        "phpunit/phpunit": "^8.0 || ^9.0"
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "4.0-dev"
+            "dev-master": "5.0-dev"
         }
     },
     "autoload": {
         "psr-4": {
-            "JohnKary\\PHPUnit\\Listener\\": "src/"
+            "JohnKary\\PHPUnit\\Extension\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "JohnKary\\PHPUnit\\Listener\\Tests\\": "tests/"
+            "JohnKary\\PHPUnit\\Extension\\Tests\\": "tests/"
         }
     }
 }
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -13,8 +13,8 @@
         </testsuite>
     </testsuites>
 
-    <listeners>
-        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener">
+    <extensions>
+        <extension class="JohnKary\PHPUnit\Extension\SpeedTrap">
             <arguments>
                 <array>
                     <element key="slowThreshold">
@@ -23,13 +23,10 @@
                     <element key="reportLength">
                         <integer>5</integer>
                     </element>
-                    <element key="stopOnSlow">
-                        <boolean>false</boolean>
-                    </element>
                 </array>
             </arguments>
-        </listener>
-    </listeners>
+        </extension>
+    </extensions>
 
     <filter>
         <whitelist>