Annotation Interface Timeout

@Target({TYPE,METHOD}) @Retention(RUNTIME) @Documented @Inherited @API(status=STABLE, since="5.7") public @interface Timeout
@Timeout is used to define a timeout for a method or all testable methods within one class and its @Nested classes.

This annotation may also be used on lifecycle methods annotated with @BeforeAll, @BeforeEach, @AfterEach, or @AfterAll.

Applying this annotation to a test class has the same effect as applying it to all testable methods, i.e. all methods annotated or meta-annotated with @Test, @TestFactory, or @TestTemplate, but not to its lifecycle methods.

Default Timeouts

If this annotation is not present, no timeout will be used unless a default timeout is defined via one of the following configuration parameters:

"junit.jupiter.execution.timeout.default"
Default timeout for all testable and lifecycle methods
"junit.jupiter.execution.timeout.testable.method.default"
Default timeout for all testable methods
"junit.jupiter.execution.timeout.test.method.default"
Default timeout for @Test methods
"junit.jupiter.execution.timeout.testtemplate.method.default"
Default timeout for @TestTemplate methods
"junit.jupiter.execution.timeout.testfactory.method.default"
Default timeout for @TestFactory methods
"junit.jupiter.execution.timeout.lifecycle.method.default"
Default timeout for all lifecycle methods
"junit.jupiter.execution.timeout.beforeall.method.default"
Default timeout for @BeforeAll methods
"junit.jupiter.execution.timeout.beforeeach.method.default"
Default timeout for @BeforeEach methods
"junit.jupiter.execution.timeout.aftereach.method.default"
Default timeout for @AfterEach methods
"junit.jupiter.execution.timeout.afterall.method.default"
Default timeout for @AfterAll methods

More specific configuration parameters override less specific ones. For example, "junit.jupiter.execution.timeout.test.method.default" overrides "junit.jupiter.execution.timeout.testable.method.default" which overrides "junit.jupiter.execution.timeout.default".

Supported Values

Values for timeouts must be in the following, case-insensitive format: <number> [ns|μs|ms|s|m|h|d]. The space between the number and the unit may be omitted. Specifying no unit is equivalent to using seconds.

Timeout configuration via configuration parameter vs. annotation
Value Equivalent annotation
42 @Timeout(42)
42 ns @Timeout(value = 42, unit = NANOSECONDS)
42 μs @Timeout(value = 42, unit = MICROSECONDS)
42 ms @Timeout(value = 42, unit = MILLISECONDS)
42 s @Timeout(value = 42, unit = SECONDS)
42 m @Timeout(value = 42, unit = MINUTES)
42 h @Timeout(value = 42, unit = HOURS)
42 d @Timeout(value = 42, unit = DAYS)

Disabling Timeouts

You may use the "junit.jupiter.execution.timeout.mode" configuration parameter to explicitly enable or disable timeouts.

Supported values:

  • enabled: enables timeouts
  • disabled: disables timeouts
  • disabled_on_debug: disables timeouts while debugging
Since:
5.5