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

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

  • Field Details

    • DEFAULT_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all testable and lifecycle methods: "junit.jupiter.execution.timeout.default".

      The value of this property will be used unless overridden by a more specific property or a @Timeout annotation present on the method or on an enclosing test class (for testable methods).

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all testable methods: "junit.jupiter.execution.timeout.testable.method.default".

      The value of this property will be used unless overridden by a more specific property or a @Timeout annotation present on the testable method or on an enclosing test class.

      This property overrides the "junit.jupiter.execution.timeout.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @Test methods: "junit.jupiter.execution.timeout.test.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @Test method or on an enclosing test class.

      This property overrides the "junit.jupiter.execution.timeout.testable.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @TestTemplate methods: "junit.jupiter.execution.timeout.testtemplate.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @TestTemplate method or on an enclosing test class.

      This property overrides the "junit.jupiter.execution.timeout.testable.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @TestFactory methods: "junit.jupiter.execution.timeout.testfactory.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @TestFactory method or on an enclosing test class.

      This property overrides the "junit.jupiter.execution.timeout.testable.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all lifecycle methods: "junit.jupiter.execution.timeout.lifecycle.method.default".

      The value of this property will be used unless overridden by a more specific property or a @Timeout annotation present on the lifecycle method.

      This property overrides the "junit.jupiter.execution.timeout.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @BeforeAll methods: "junit.jupiter.execution.timeout.beforeall.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @BeforeAll method.

      This property overrides the "junit.jupiter.execution.timeout.lifecycle.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @BeforeEach methods: "junit.jupiter.execution.timeout.beforeeach.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @BeforeEach method.

      This property overrides the "junit.jupiter.execution.timeout.lifecycle.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @AfterEach methods: "junit.jupiter.execution.timeout.aftereach.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @AfterEach method.

      This property overrides the "junit.jupiter.execution.timeout.lifecycle.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME
      Property name used to set the default timeout for all @AfterAll methods: "junit.jupiter.execution.timeout.afterall.method.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the @AfterAll method.

      This property overrides the "junit.jupiter.execution.timeout.lifecycle.method.default" property.

      Please refer to the class description for the definition of supported values.

      Since:
      5.5
      See Also:

    • TIMEOUT_MODE_PROPERTY_NAME

      @API(status=STABLE, since="5.9") static final String TIMEOUT_MODE_PROPERTY_NAME
      Property name used to configure whether timeouts are applied to tests: "junit.jupiter.execution.timeout.mode".

      The value of this property will be used to toggle whether @Timeout is applied to tests.

      Supported timeout mode values:

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

      If not specified, the default is enabled.

      Since:
      5.6
      See Also:

    • DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME

      @API(status=EXPERIMENTAL, since="5.9") static final String DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME
      Property name used to set the default thread mode for all testable and lifecycle methods: "junit.jupiter.execution.timeout.thread.mode.default".

      The value of this property will be used unless overridden by a @Timeout annotation present on the method or on an enclosing test class (for testable methods).

      The supported values are SAME_THREAD or SEPARATE_THREAD, if none is provided SAME_THREAD is used as default.

      Since:
      5.9
      See Also:

  • 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:
      Default:
      SECONDS

    • threadMode

      @API(status=STABLE, since="5.11") Timeout.ThreadMode threadMode
      The thread mode of this timeout.
      Returns:
      thread mode
      Since:
      5.9
      See Also:
      Default:
      INFERRED