Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mvorisek committed Dec 14, 2023
1 parent 033250c commit 945837c
Show file tree
Hide file tree
Showing 3 changed files with 7 additions and 35 deletions.
37 changes: 4 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,42 +316,13 @@ Time: 00:12.601, Memory: 8.00 MB
OK (13 tests, 13 assertions)
```

### Understanding measured test durations when using `phpunit/phpunit:^8.5.19` or `phpunit/phpunit:^9.4.3`
### Understanding measured test durations

When using `phpunit/phpunit:^8.5.19` or `phpunit/phpunit:^9.4.3`, the extension uses the hooks event system of `phpunit/phpunit`.
A duration of invoking [`PHPUnit\Framework\TestCase::runBare()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestRunner.php#L101) method is measured.

The hooks event system supports eleven hook methods that `phpunit/phpunit` invokes during the execution of tests.
The measured duration includes time spent in [`PHPUnit\Framework\TestCase::setUp()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L313) and [`PHPUnit\Framework\TestCase::tearDown()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L338) methods and respective [`before`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L1932) and [`after`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L1962) PHPUnit test hooks.

When the extension uses the hooks event system, it uses the [`PHPUnit\Runner\AfterSuccessfulTestHook`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Runner/Hook/AfterSuccessfulTestHook.php#L12-L15), which receives 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).

When `phpunit/phpunit` invokes `PHPUnit\Framework\TestCase::runBare()`, it will invoke the following methods before the first test method in the class:

- [`PHPUnit\Framework\TestCase::setUpBeforeClass()` and methods annotated with `@beforeClass`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1078-L1082)

When `phpunit/phpunit` invokes `PHPUnit\Framework\TestCase::runBare()`, it will invoke the following methods before every test method in the class:

- [`PHPUnit\Framework\TestCase::setUp()` and methods annotated with `@before`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1087-L1089)
- [`PHPUnit\Framework\TestCase::assertPreConditions()`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1091C20-L1091C39)

When `phpunit/phpunit` invokes `PHPUnit\Framework\TestCase::runBare()`, it will invoke the following methods after every test method in the class:

- [`PHPUnit\Framework\TestCase::assertPostConditions()`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1094)
- [`PHPUnit\Framework\TestCase::tearDown()` and methods annotated with `@after`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1134-L1136)

When phpunit/phpunit invokes `PHPUnit\Framework\TestCase::runBare()`, it will invoke the following methods after the last test method in the class:

- [`PHPUnit\Framework\TestCase::tearDownAfterClass()` and methods annotated with `@afterClass`](https://github.com/sebastianbergmann/phpunit/blob/8.5.19/src/Framework/TestCase.php#L1138-L1142)

> [!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 `phpunit/phpunit:^10.0.0`

When using `phpunit/phpunit:^10.0.0`, the extension uses the new event system of `phpunit/phpunit`.

The new event system supports a wide range of events that `phpunit/phpunit` emits during the execution of tests.

When the extension uses the new event system, it uses and subscribes to the [`PHPUnit\Event\Test\Prepared`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Lifecycle/Prepared.php#L22-L50) and [`PHPUnit\Event\Test\Passed`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Event/Events/Test/Outcome/Passed.php#L22-L50) events and measures the [duration between the points in time when `phpunit/phpunit` emits the former and the latter](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L614-L666).
A duration if invoking [`PHPUnit\Framework\TestCase::setUpBeforeClass()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L299) and [`PHPUnit\Framework\TestCase::tearDownAfterClass()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L306) methods is NOT measured as it is not per test, but per test class. An exception are tests [run in a separate process](https://docs.phpunit.de/en/10.5/annotations.html#runinseparateprocess), in this case, [`TestCase::setUpBeforeClass()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L299) and [`TestCase::tearDownAfterClass()`](https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L306) 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

Expand Down
3 changes: 2 additions & 1 deletion src/Subscriber/TestFinishedSubscriber.php
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ public function __construct(
}

/**
* @see https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L664-L666
* @see https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestRunner.php#L198
* @see https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestRunner.php#L238
*/
public function notify(Event\Test\Finished $event): void
{
Expand Down
2 changes: 1 addition & 1 deletion src/Subscriber/TestPreparationStartedSubscriber.php
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ public function __construct(TimeKeeper $timeKeeper)
}

/**
* @see https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L614-L616
* @see https://github.com/sebastianbergmann/phpunit/blob/10.0.0/src/Framework/TestCase.php#L585
*/
public function notify(Event\Test\PreparationStarted $event): void
{
Expand Down

0 comments on commit 945837c

Please sign in to comment.