From 5eea7869bd4b7e3faf959fbddc39c339ff00d091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Vo=C5=99=C3=AD=C5=A1ek?= Date: Thu, 14 Dec 2023 15:04:34 +0100 Subject: [PATCH] update docs --- README.md | 37 ++----------------- src/Subscriber/TestFinishedSubscriber.php | 3 +- .../TestPreparationStartedSubscriber.php | 2 +- 3 files changed, 7 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 4999d2f2..48461b94 100644 --- a/README.md +++ b/README.md @@ -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.0.0` +### Understanding measured test durations -When using `phpunit/phpunit:^8.5.19` or `phpunit/phpunit:^9.0.0`, 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 diff --git a/src/Subscriber/TestFinishedSubscriber.php b/src/Subscriber/TestFinishedSubscriber.php index db4fdef9..d34e5536 100644 --- a/src/Subscriber/TestFinishedSubscriber.php +++ b/src/Subscriber/TestFinishedSubscriber.php @@ -44,7 +44,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 { diff --git a/src/Subscriber/TestPreparationStartedSubscriber.php b/src/Subscriber/TestPreparationStartedSubscriber.php index d0cf7201..f8cc794b 100644 --- a/src/Subscriber/TestPreparationStartedSubscriber.php +++ b/src/Subscriber/TestPreparationStartedSubscriber.php @@ -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 {