Merge pull request #66 from johnkary/master-envVarDisable

Environment variable PHPUNIT_SPEEDTRAP="disabled" can disable profiling

Author: johnkary

CHANGELOG.md

@@ -7,6 +7,10 @@ https://github.com/johnkary/phpunit-speedtrap/commit/XXX where XXX is the commit
 View diff between two versions:  
 https://github.com/johnkary/phpunit-speedtrap/compare/v3.1.0...v3.2.0
 
+## 4.0 (xxxx-xx-xx)
+
+* [PR #66](https://github.com/johnkary/phpunit-speedtrap/pull/66) Environment variable PHPUNIT_SPEEDTRAP="disabled" can disable profiling
+
 ## 3.2.0 (2020-02-12)
 
 Version 3.2 introduces supports for PHPUnit 9.0+.

README.md

@@ -12,7 +12,7 @@ SpeedTrap helps **identify slow tests** but cannot explain **why** those tests a
 
 ## Installation
 
-SpeedTrap is installable via [Composer](http://getcomposer.org) and should be added as a `require-dev` dependency:
+SpeedTrap is installed using [Composer](http://getcomposer.org). Add it as a `require-dev` dependency:
 
     composer require --dev johnkary/phpunit-speedtrap
 
@@ -30,16 +30,16 @@ Enable with all defaults by adding the following code to your project's `phpunit
 </phpunit>
 ```
 
-Now run the test suite as normal. If one or more test executions exceed the slowness threshold (500ms by default), SpeedTrap will report on those tests in the console after all tests have completed.
+Now run the test suite. If one or more test executions exceed the slowness threshold (500ms by default), SpeedTrap will report on those tests in the console after all tests have completed.
 
-## Configuration
+## Config Parameters
 
-SpeedTrap has two configurable parameters:
+SpeedTrap also supports these parameters:
 
-* **slowThreshold** - Number of milliseconds a test takes to execute before being considered "slow" (Default: 500ms)
+* **slowThreshold** - Number of milliseconds when a test is considered "slow" (Default: 500ms)
 * **reportLength** - Number of slow tests included in the report (Default: 10 tests)
 
-These configuration parameters are set in `phpunit.xml` when adding the listener:
+Each parameter is set in `phpunit.xml`:
 
 ```xml
 <phpunit bootstrap="vendor/autoload.php">
@@ -62,13 +62,11 @@ These configuration parameters are set in `phpunit.xml` when adding the listener
 </phpunit>
 ```
 
-This allows customizing what the project considers a "slow" test and how many are reported on to project maintainers.
-
 ## Custom slowness threshold per-test case
 
 Some projects have a few complex tests that take a long time to run. It is possible to set a different slowness threshold for individual test cases.
 
-Use the annotation `@slowThreshold` to set a custom slowness threshold for single test cases. This number may be higher or lower than the default threshold and will be used in place of the default threshold for that specific test.
+The annotation `@slowThreshold` can set a custom slowness threshold for each test case. This number may be higher or lower than the default threshold and is used instead of the default threshold for that specific test.
 
 ```php
 class SomeTestCase extends PHPUnit\Framework\TestCase
@@ -83,9 +81,102 @@ class SomeTestCase extends PHPUnit\Framework\TestCase
 }
 ```
 
+## 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.
+
+    $ 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.
+
+```xml
+<phpunit bootstrap="vendor/autoload.php">
+...
+    <php>
+        <env name="PHPUNIT_SPEEDTRAP" value="disabled" />
+    </php>
+
+    <listeners>
+        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
+    </listeners>
+</phpunit>
+```
+
+Step 2) Configure `.travis.yml` with `PHPUNIT_SPEEDTRAP="enabled"` to profile for slow tests when running on Travis CI:
+
+```yaml
+language: php
+
+php:
+  - 7.3
+
+env:
+  - PHPUNIT_SPEEDTRAP="enabled"
+```
+
+Step 3) View the Travis CI build output and read the slowness report printed in the console.
+
+[Travis CI Documentation - Environment Variables](https://docs.travis-ci.com/user/environment-variables)
+
+#### 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.
+
+```xml
+<phpunit bootstrap="vendor/autoload.php">
+...
+    <listeners>
+        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
+    </listeners>
+</phpunit>
+```
+
+Step 2) Configure `.travis.yml` with `PHPUNIT_SPEEDTRAP="disabled"` to turn off profiling when running on Travis CI:
+
+```yaml
+language: php
+
+php:
+  - 7.3
+
+env:
+  - PHPUNIT_SPEEDTRAP="disabled"
+```
+
+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
+
+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:
+
+```xml
+<phpunit bootstrap="vendor/autoload.php">
+...
+    <php>
+        <env name="PHPUNIT_SPEEDTRAP" value="disabled" />
+    </php>
+
+    <listeners>
+        <listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener" />
+    </listeners>
+</phpunit>
+```
+
+Step 2) When executing `phpunit` from the command-line, enable slowness profiling only for this run by passing the environment variable `PHPUNIT_SPEEDTRAP="enabled"` like this:
+
+```bash
+$ PHPUNIT_SPEEDTRAP=enabled ./vendor/bin/phpunit
+```
+
 ## Inspiration
 
-This project was inspired by [RSpec's](https://github.com/rspec/rspec) `--profile` option that displays feedback about slow tests.
+SpeedTrap was inspired by [RSpec's](https://github.com/rspec/rspec) `--profile` option that displays feedback about slow tests.
 
 ## License
 

src/SpeedTrapListener.php

@@ -13,6 +13,17 @@ class SpeedTrapListener implements TestListener
 {
     use TestListenerDefaultImplementation;
 
+    /**
+     * Slowness profiling enabled by default. Set to false to disable profiling
+     * and reporting.
+     *
+     * Use environment variable "PHPUNIT_SPEEDTRAP" set to value "disabled" to
+     * disable profiling.
+     *
+     * @var boolean
+     */
+    protected $enabled = true;
+
     /**
      * Internal tracking for test suites.
      *
@@ -45,6 +56,8 @@ class SpeedTrapListener implements TestListener
 
     public function __construct(array $options = [])
     {
+        $this->enabled = getenv('PHPUNIT_SPEEDTRAP') === 'disabled' ? false : true;
+
         $this->loadOptions($options);
     }
 
@@ -56,6 +69,7 @@ public function __construct(array $options = [])
      */
     public function endTest(Test $test, float $time): void
     {
+        if (!$this->enabled) return;
         if (!$test instanceof TestCase) return;
 
         $timeInMilliseconds = $this->toMilliseconds($time);
@@ -73,6 +87,8 @@ public function endTest(Test $test, float $time): void
      */
     public function startTestSuite(TestSuite $suite): void
     {
+        if (!$this->enabled) return;
+
         $this->suites++;
     }
 
@@ -83,6 +99,8 @@ public function startTestSuite(TestSuite $suite): void
      */
     public function endTestSuite(TestSuite $suite): void
     {
+        if (!$this->enabled) return;
+
         $this->suites--;
 
         if (0 === $this->suites && $this->hasSlowTests()) {