@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 Summary

Fields
Modifier and Type	Fields	Description
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.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".
`static java.lang.String`	`DEFAULT_TIMEOUT_PROPERTY_NAME`	Property name used to set the default timeout for all testable and lifecycle methods: "junit.jupiter.execution.timeout.default".
`static java.lang.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".
`static java.lang.String`	`TIMEOUT_MODE_PROPERTY_NAME`	Property name used to configure whether timeouts are applied to tests: "junit.jupiter.execution.timeout.mode".

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
`Timeout.ThreadMode`	`threadMode`	The thread mode of this timeout.
`java.util.concurrent.TimeUnit`	`unit`	The time unit of this timeout.

- Field Detail
  - DEFAULT_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - TIMEOUT_MODE_PROPERTY_NAME
```
@API(status=STABLE,
     since="5.9")
static final java.lang.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
- - DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME
```
@API(status=MAINTAINED,
     since="5.13.3")
static final java.lang.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
- Element Detail
  - value
```
long value
```
    The duration of this timeout.
    
    Returns:
    
    timeout duration; must be a positive number
- - unit
```
java.util.concurrent.TimeUnit unit
```
    The time unit of this timeout.
    
    Returns:
    
    time unit
    
    See Also:
    
    TimeUnit
    
    Default:
    
    java.util.concurrent.TimeUnit.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:
    
    Timeout.ThreadMode
    
    Default:
    
    org.junit.jupiter.api.Timeout.ThreadMode.INFERRED

Annotation Type Timeout

Default Timeouts

Supported Values

Disabling Timeouts

Field Summary

Required Element Summary

Optional Element Summary

Field Detail

DEFAULT_TIMEOUT_PROPERTY_NAME

DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME

DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME

TIMEOUT_MODE_PROPERTY_NAME

Supported timeout mode values:

DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME

Element Detail

value

unit

threadMode