Module org.junit.jupiter.api
Package org.junit.jupiter.api

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.

Values 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.

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)
Since:
5.5

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    long
    value
    The duration of this timeout.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    TimeUnit
    unit
    The time unit of this timeout.

  • Element Details

    • value

      long value
      The duration of this timeout.
      Returns:
      timeout duration; must be a positive number

    • unit

      TimeUnit unit
      The time unit of this timeout.
      Returns:
      time unit
      See Also:
      TimeUnit
      Default:
      SECONDS