org.junit.jupiter.api

Annotation Type Timeout

@Target(value={TYPE,METHOD})
 @Retention(value=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 and 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 and Description
long	value The duration of this timeout.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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")
public 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=EXPERIMENTAL,
     since="5.9")
public 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

public abstract long value

The duration of this timeout.

Returns:

timeout duration; must be a positive number

unit

public abstract 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=EXPERIMENTAL,
     since="5.9")
public abstract 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