Skip to content

Readme: re-order instruction from recent to old PHPUnit versions #722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Readme: re-order instruction from recent to old PHPUnit versions #722

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 95 additions & 91 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ This project provides a [`composer`](https://getcomposer.org) package and a [Pha

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

- [`phpunit/phpunit:^6.5.0`](https://github.com/sebastianbergmann/phpunit/tree/6.5.0)
- [`phpunit/phpunit:^7.5.0`](https://github.com/sebastianbergmann/phpunit/tree/7.5.0)
- [`phpunit/phpunit:^8.5.19`](https://github.com/sebastianbergmann/phpunit/tree/8.5.19)
- [`phpunit/phpunit:^9.0.0`](https://github.com/sebastianbergmann/phpunit/tree/9.0.0)
- [`phpunit/phpunit:^10.0.0`](https://github.com/sebastianbergmann/phpunit/tree/10.0.0)
- [`phpunit/phpunit:^11.0.0`](https://github.com/sebastianbergmann/phpunit/tree/11.0.0)
- [`phpunit/phpunit:^12.0.0`](https://github.com/sebastianbergmann/phpunit/tree/12.0.0)
- [`phpunit/phpunit:^11.0.0`](https://github.com/sebastianbergmann/phpunit/tree/11.0.0)
- [`phpunit/phpunit:^10.0.0`](https://github.com/sebastianbergmann/phpunit/tree/10.0.0)
- [`phpunit/phpunit:^9.0.0`](https://github.com/sebastianbergmann/phpunit/tree/9.0.0)
- [`phpunit/phpunit:^8.5.19`](https://github.com/sebastianbergmann/phpunit/tree/8.5.19)
- [`phpunit/phpunit:^7.5.0`](https://github.com/sebastianbergmann/phpunit/tree/7.5.0)
- [`phpunit/phpunit:^6.5.0`](https://github.com/sebastianbergmann/phpunit/tree/6.5.0)

## Installation

Expand Down Expand Up @@ -49,21 +49,25 @@ Before the extension can detect slow tests in `phpunit/phpunit`, you need to boo

To bootstrap the extension as a `composer` package when using

- `phpunit/phpunit:^6.5.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^10.0.0`

adjust your `phpunit.xml` configuration file and configure the

- [`listeners` element](https://phpunit.de/manual/6.5/en/appendixes.configuration.html#appendixes.configuration.test-listeners) on [`phpunit/phpunit:^6.5.0`](https://phpunit.de/manual/6.5/en/)
- [`extensions` element](https://docs.phpunit.de/en/10.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`extensions` element](https://docs.phpunit.de/en/11.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`extensions` element](https://docs.phpunit.de/en/12.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)

```diff
<phpunit
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
>
+ <listeners>
+ <listener class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ </listeners>
+ <extensions>
+ <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ </extensions>
<testsuites>
<testsuite name="unit">
<directory>test/Unit/</directory>
Expand All @@ -76,9 +80,9 @@ adjust your `phpunit.xml` configuration file and configure the

To bootstrap the extension as a `composer` package when using

- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`

adjust your `phpunit.xml` configuration file and configure the

Expand Down Expand Up @@ -107,25 +111,21 @@ adjust your `phpunit.xml` configuration file and configure the

To bootstrap the extension as a `composer` package when using

- `phpunit/phpunit:^10.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^6.5.0`

adjust your `phpunit.xml` configuration file and configure the

- [`extensions` element](https://docs.phpunit.de/en/10.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`extensions` element](https://docs.phpunit.de/en/11.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`extensions` element](https://docs.phpunit.de/en/12.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)
- [`listeners` element](https://phpunit.de/manual/6.5/en/appendixes.configuration.html#appendixes.configuration.test-listeners) on [`phpunit/phpunit:^6.5.0`](https://phpunit.de/manual/6.5/en/)

```diff
<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>
+ <listeners>
+ <listener class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ </listeners>
<testsuites>
<testsuite name="unit">
<directory>test/Unit/</directory>
Expand All @@ -134,19 +134,23 @@ adjust your `phpunit.xml` configuration file and configure the
</phpunit>
```



### Bootstrapping the extension as a PHAR

---

To bootstrap the extension as a PHAR when using

- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^10.0.0`

adjust your `phpunit.xml` configuration file and configure the

- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/7.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/7.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^7.5.0`](https://docs.phpunit.de/en/7.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/8.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/8.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^8.5.19`](https://docs.phpunit.de/en/8.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/9.6/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/9.6/configuration.html#the-extensions-element) on [`phpunit/phpunit:^9.0.0`](https://docs.phpunit.de/en/9.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/10.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/10.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/11.0/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/11.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/12.0/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/12.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)

```diff
<phpunit
Expand All @@ -156,7 +160,7 @@ adjust your `phpunit.xml` configuration file and configure the
+ extensionsDirectory="directory/where/you/saved/the/extension/phars"
>
+ <extensions>
+ <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ </extensions>
<testsuites>
<testsuite name="unit">
Expand All @@ -170,15 +174,15 @@ adjust your `phpunit.xml` configuration file and configure the

To bootstrap the extension as a PHAR when using

- `phpunit/phpunit:^10.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`

adjust your `phpunit.xml` configuration file and configure the

- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/10.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/10.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/11.0/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/11.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/12.0/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/12.0/configuration.html#the-extensions-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/7.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/7.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^7.5.0`](https://docs.phpunit.de/en/7.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/8.5/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/8.5/configuration.html#the-extensions-element) on [`phpunit/phpunit:^8.5.19`](https://docs.phpunit.de/en/8.5/)
- [`extensionsDirectory` attribute](https://docs.phpunit.de/en/9.6/configuration.html#the-extensionsdirectory-attribute) and the [`extensions` element](https://docs.phpunit.de/en/9.6/configuration.html#the-extensions-element) on [`phpunit/phpunit:^9.0.0`](https://docs.phpunit.de/en/9.5/)

```diff
<phpunit
Expand All @@ -188,7 +192,7 @@ adjust your `phpunit.xml` configuration file and configure the
+ extensionsDirectory="directory/where/you/saved/the/extension/phars"
>
+ <extensions>
+ <extension class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ <bootstrap class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ </extensions>
<testsuites>
<testsuite name="unit">
Expand All @@ -211,11 +215,15 @@ The configuration mechanism depends on the version of `phpunit/phpunit` you are

To configure the extension when using

- `phpunit/phpunit:^6.5.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^10.0.0`

adjust your `phpunit.xml` configuration file and configure the
adjust your `phpunit.xml` configuration file and configure one or more

- [`arguments` element](https://phpunit.de/manual/6.5/en/appendixes.configuration.html#appendixes.configuration.test-listeners) on [`phpunit/phpunit:^6.5.0`](https://phpunit.de/manual/6.5/en/)
- [`parameter` elements](https://docs.phpunit.de/en/10.5/configuration.html#the-parameter-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`parameter` elements](https://docs.phpunit.de/en/11.0/configuration.html#the-parameter-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`parameter` elements](https://docs.phpunit.de/en/12.0/configuration.html#the-parameter-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)

The following example configures the maximum count of slow tests to three, and the maximum duration for all tests to 250 milliseconds:

Expand All @@ -225,21 +233,13 @@ The following example configures the maximum count of slow tests to three, and t
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
>
<listeners>
- <listener class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ <listener 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>
+ </listener>
</listeners>
<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>
Expand All @@ -252,9 +252,9 @@ The following example configures the maximum count of slow tests to three, and t

To configure the extension when using

- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`

adjust your `phpunit.xml` configuration file and configure the

Expand Down Expand Up @@ -297,15 +297,11 @@ The following example configures the maximum count of slow tests to three, and t

To configure the extension when using

- `phpunit/phpunit:^10.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^6.5.0`

adjust your `phpunit.xml` configuration file and configure one or more
adjust your `phpunit.xml` configuration file and configure the

- [`parameter` elements](https://docs.phpunit.de/en/10.5/configuration.html#the-parameter-element) on [`phpunit/phpunit:^10.0.0`](https://docs.phpunit.de/en/10.5/)
- [`parameter` elements](https://docs.phpunit.de/en/11.0/configuration.html#the-parameter-element) on [`phpunit/phpunit:^11.0.0`](https://docs.phpunit.de/en/11.0/)
- [`parameter` elements](https://docs.phpunit.de/en/12.0/configuration.html#the-parameter-element) on [`phpunit/phpunit:^12.0.0`](https://docs.phpunit.de/en/12.0/)
- [`arguments` element](https://phpunit.de/manual/6.5/en/appendixes.configuration.html#appendixes.configuration.test-listeners) on [`phpunit/phpunit:^6.5.0`](https://phpunit.de/manual/6.5/en/)

The following example configures the maximum count of slow tests to three, and the maximum duration for all tests to 250 milliseconds:

Expand All @@ -315,13 +311,21 @@ The following example configures the maximum count of slow tests to three, and t
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>
<listeners>
- <listener class="Ergebnis\PHPUnit\SlowTestDetector\Extension"/>
+ <listener 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>
+ </listener>
</listeners>
<testsuites>
<testsuite name="unit">
<directory>test/Unit/</directory>
Expand All @@ -335,19 +339,19 @@ The following example configures the maximum count of slow tests to three, and t
You can configure the maximum duration for a single test case with

- an `Attribute\MaximumDuration` attribute when using
- `phpunit/phpunit:^10.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^10.0.0`
- a `@maximumDuration` annotation in the DocBlock when using
- `phpunit/phpunit:^6.5.0`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^9.0.0`
- a `@slowThreshold` annotation in the DocBlock when using
- `phpunit/phpunit:^6.5.0`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^6.5.0`
- a `@slowThreshold` annotation in the DocBlock when using
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^6.5.0`

The following example configures the maximum durations for single test cases to 5,000 ms, 4,000 ms, and 3,000 ms:

Expand Down Expand Up @@ -430,30 +434,30 @@ OK (13 tests, 13 assertions)

### Understanding measured test durations

#### Understanding measured test durations when using the new event system

When using

- `phpunit/phpunit:^12.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^10.0.0`

the extension uses the new event system of `phpunit/phpunit`, and measures the duration between the points in time when the [`PHPUnit\Event\Test\PreparationStarted`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Lifecycle/PreparationStarted.php#L22-L50) and [`PHPUnit\Event\Test\Finished`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Lifecycle/Finished.php#L22-L57) are emitted.

#### Understanding measured test durations when using the hooks event system

When using

- `phpunit/phpunit:^6.5.0`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^9.0.0`
- `phpunit/phpunit:^8.5.19`
- `phpunit/phpunit:^7.5.0`
- `phpunit/phpunit:^6.5.0`

the extension uses the hooks event system of `phpunit/phpunit`, and measures the duration that is passed to the [`PHPUnit\Runner\AfterTestHook`](https://github.com/sebastianbergmann/phpunit/blob/7.5.0/src/Runner/Hook/AfterTestHook.php#L12-L21). This is the [duration of invoking `PHPUnit\Framework\TestCase::runBare()` and more](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestResult.php#L671-L754).

> [!NOTE]
> Because of this behavior, the measured test durations can and will vary depending on the order in which `phpunit/phpunit` executes tests.

#### Understanding measured test durations when using the new event system

When using

- `phpunit/phpunit:^10.0.0`
- `phpunit/phpunit:^11.0.0`
- `phpunit/phpunit:^12.0.0`

the extension uses the new event system of `phpunit/phpunit`, and measures the duration between the points in time when the [`PHPUnit\Event\Test\PreparationStarted`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Lifecycle/PreparationStarted.php#L22-L50) and [`PHPUnit\Event\Test\Finished`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Lifecycle/Finished.php#L22-L57) are emitted.

## Changelog

The maintainers of this project record notable changes to this project in a [changelog](CHANGELOG.md).
Expand Down
Loading