diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 6ef246881d73..48a9600ef4a4 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -1614,9 +1614,9 @@ implementations. WARNING: You're invited to give it a try and provide feedback to the JUnit team so they can improve and eventually <> this feature. -The `@Timeout` annotation allows to declare that a test, test factory, test template, or -lifecycle method should fail if its execution time exceeds a given duration, and -optionally a time unit (seconds are used by default). +The `@Timeout` annotation allows one to declare that a test, test factory, test template, +or lifecycle method should fail if its execution time exceeds a given duration. The time +unit for the duration defaults to seconds but is configurable. The following example shows how `@Timeout` is applied to lifecycle and test methods. @@ -1628,23 +1628,23 @@ include::{testDir}/example/TimeoutDemo.java[tags=user_guide] Contrary to the `assertTimeoutPreemptively()` assertion, the execution of the annotated method proceeds in the main thread of the test. If the timeout is exceeded, the main thread is interrupted from another thread. This is done to ensure interoperability with -frameworks such as Spring that make extensive use of mechanisms that are sensitive to the -currently running thread (e.g. `ThreadLocals`). +frameworks such as Spring that make use of mechanisms that are sensitive to the currently +running thread — for example, `ThreadLocal` transaction management. -To apply the same timeout to all test methods within a test class and all its `@Nested` -classes, you can declare the `@Timeout` annotation on the class level. It will then be +To apply the same timeout to all test methods within a test class and all of its `@Nested` +classes, you can declare the `@Timeout` annotation at the class level. It will then be applied to all test, test factory, and test template methods within that class and its -`@Nested` classes unless overridden by a `@Timeout` annotation on a method or `@Nested` -class. Please note that `@Timeout` annotations declared on the class level are not -applied to lifecycle methods. +`@Nested` classes unless overridden by a `@Timeout` annotation on a specific method or +`@Nested` class. Please note that `@Timeout` annotations declared at the class level are +not applied to lifecycle methods. -Declaring `@Timeout` on a test factory method checks that the method returns within the -specified duration but does verify the execution time of the returned `DynamicTests`. -Please use `assertTimeout()`/`assertTimeoutPreemptively()` for that purpose. +Declaring `@Timeout` on a `@TestFactory` method checks that the factory method returns +within the specified duration but does verify the execution time of each individual +`DynamicTest` generated by the factory. Please use +`assertTimeout()` or `assertTimeoutPreemptively()` for that purpose. -If `@Timeout` is present on a test template method, such as a method annotated with -`@RepeatedTest` or `@ParameterizedTest`, each invocation is checked to finish within the -given timeout. +If `@Timeout` is present on a `@TestTemplate` method — for example, a `@RepeatedTest` or +`@ParameterizedTest` — each invocation will have the given timeout applied to it. The following <> can be used to specify global timeouts for all methods of a certain category unless they or an enclosing