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

Annotation Type 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 Detail

      • 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:
        java.util.concurrent.TimeUnit.SECONDS