@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

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	Timeout.ThreadMode `ThreadMode` is used to define whether test code should be executed in the thread of the calling code or in a separate thread.

Field Summary

Modifier and Type	Field and Description
public static final String	DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@AfterAll` methods: .
public static final String	DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@AfterEach` methods: .
public static final String	DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@BeforeAll` methods: .
public static final String	DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@BeforeEach` methods: .
public static final String	DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all lifecycle methods: .
public static final String	DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@TestFactory` methods: .
public static final String	DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@Test` methods: .
public static final String	DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@TestTemplate` methods: .
public static final String	DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all testable methods: .
public static final String	DEFAULT_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all testable and lifecycle methods: .
public static final String	DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME Property name used to set the default thread mode for all testable and lifecycle methods: .
public static final String	TIMEOUT_MODE_PROPERTY_NAME Property name used to configure whether timeouts are applied to tests: .

Method Summary

Modifier and Type	Method and Description
public Timeout.ThreadMode	Returns: thread mode threadMode() The thread mode of this timeout.
public TimeUnit	Returns: time unit unit() The time unit of this timeout.
public long	Returns: timeout duration; must be a positive number value() The duration of this timeout.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Field Detail

DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@AfterAll` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @AfterAll methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@AfterEach` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @AfterEach methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@BeforeAll` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @BeforeAll methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@BeforeEach` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @BeforeEach methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all lifecycle methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all lifecycle methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@TestFactory` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @TestFactory methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@Test` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @Test methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all `@TestTemplate` methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all @TestTemplate methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all testable methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all testable methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TIMEOUT_PROPERTY_NAME back to summary

DEFAULT_TIMEOUT_PROPERTY_NAME	back to summary
public static final String DEFAULT_TIMEOUT_PROPERTY_NAME Property name used to set the default timeout for all testable and lifecycle methods: . 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. Annotations @API status:STABLE since:5.9 Since 5.5

public static final String DEFAULT_TIMEOUT_PROPERTY_NAME

Property name used to set the default timeout for all testable and lifecycle methods: .

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.

Annotations

@API
status:STABLE
since:5.9

Since: 5.5

DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME back to summary

DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME	back to summary
public static final String DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME Property name used to set the default thread mode for all testable and lifecycle methods: . 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`, ignoring case. If none is provided, `SAME_THREAD` is used as default. Annotations @API status:MAINTAINED since:5.13.3 Since 5.9 See Also `threadMode()`

public static final String DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME

Property name used to set the default thread mode for all testable and lifecycle methods: .

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, ignoring case. If none is provided, SAME_THREAD is used as default.

Annotations

@API
status:MAINTAINED
since:5.13.3

Since: 5.9
See Also: threadMode()

TIMEOUT_MODE_PROPERTY_NAME back to summary

TIMEOUT_MODE_PROPERTY_NAME	back to summary
public static final String TIMEOUT_MODE_PROPERTY_NAME Property name used to configure whether timeouts are applied to tests: . The value of this property will be used to toggle whether `@Timeout` is applied to tests. Supported timeout mode values (case insensitive): `ENABLED`: enables timeouts `DISABLED`: disables timeouts `DISABLED_ON_DEBUG`: disables timeouts while debugging If not specified, the default is `ENABLED`. Annotations @API status:STABLE since:5.9 Since 5.6

public static final String TIMEOUT_MODE_PROPERTY_NAME

Property name used to configure whether timeouts are applied to tests: .

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

Supported timeout mode values (case insensitive):

ENABLED: enables timeouts
DISABLED: disables timeouts
DISABLED_ON_DEBUG: disables timeouts while debugging

If not specified, the default is ENABLED.

Annotations

@API
status:STABLE
since:5.9

Since: 5.6

Method Detail

threadMode back to summary

threadMode	back to summary
public Timeout.ThreadMode threadMode() The thread mode of this timeout. Returns:Timeout.ThreadMode thread mode Annotations @API status:STABLE since:5.11 Since 5.9 See Also `ThreadMode`, `DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME`

public Timeout.ThreadMode threadMode()

The thread mode of this timeout.

Returns:Timeout.ThreadMode

thread mode

Annotations

@API
status:STABLE
since:5.11

Since

5.9

unit back to summary

unit	back to summary
public TimeUnit unit() The time unit of this timeout. Returns:TimeUnit time unit See Also `TimeUnit`

public TimeUnit unit()

The time unit of this timeout.

Returns:TimeUnit: time unit
See Also: TimeUnit

value	back to summary
public long value() The duration of this timeout. Returns:long timeout duration; must be a positive number

value

back to summary

public long value()

The duration of this timeout.

Returns:long: timeout duration; must be a positive number

org.junit.jupiter.api back to summary

public final Enum Timeout.ThreadMode

Class Inheritance

extends Enum<Timeout.ThreadMode>

java.lang.Object
java.lang.Enum
org.junit.jupiter.api.Timeout.ThreadMode

Annotations

@API
status:STABLE
since:5.11

ThreadMode is used to define whether test code should be executed in the thread of the calling code or in a separate thread.

Since: 5.9

Field Summary

Modifier and Type	Field and Description
public static final Timeout.ThreadMode	INFERRED The thread mode is determined using the parameter configured in property junit.jupiter.execution.timeout.thread.mode.default.
public static final Timeout.ThreadMode	SAME_THREAD The test code is executed in the thread of the calling code.
public static final Timeout.ThreadMode	SEPARATE_THREAD The test code is executed in a different thread than that of the calling code.

Constructor Summary

Access	Constructor and Description
private	ThreadMode()

Method Summary

Modifier and Type	Method and Description
public static Timeout.ThreadMode	valueOf(String name)
public static Timeout.ThreadMode[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

INFERRED	back to summary
public static final Timeout.ThreadMode INFERRED The thread mode is determined using the parameter configured in property junit.jupiter.execution.timeout.thread.mode.default.

SAME_THREAD	back to summary
public static final Timeout.ThreadMode SAME_THREAD The test code is executed in the thread of the calling code.

SEPARATE_THREAD	back to summary
public static final Timeout.ThreadMode SEPARATE_THREAD The test code is executed in a different thread than that of the calling code. Furthermore, execution of the test code will be preemptively aborted if the timeout is exceeded. See the Preemptive Timeouts section of the class-level Javadoc for a discussion of possible undesirable side effects.

Constructor Detail

ThreadMode	back to summary
private ThreadMode()

Method Detail

valueOf	back to summary
public static Timeout.ThreadMode valueOf(String name)

values	back to summary
public static Timeout.ThreadMode[] values()

public @Interface Timeout

Default Timeouts

Supported Values

Disabling Timeouts

Nested and Inner Type Summary

Field Summary

Method Summary

Field Detail

Supported timeout mode values (case insensitive):

Method Detail

public final Enum Timeout.ThreadMode

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail