JUnit 5 5.10.2 · org.junit.jupiter.api.RepeatedTest

@RepeatedTest is used to signal that the annotated method is a test template method that should be repeated a specified number of times with a configurable display name and an optional failure threshold.

Each invocation of the repeated test behaves like the execution of a regular @Test method with full support for the same lifecycle callbacks and extensions. In addition, the current repetition and total number of repetitions can be accessed by having the RepetitionInfo injected.

@RepeatedTest methods must not be private or static and must return void.

@RepeatedTest methods may optionally declare parameters to be resolved by ParameterResolvers.

@RepeatedTest may also be used as a meta-annotation in order to create a custom composed annotation that inherits the semantics of @RepeatedTest.

Test Execution Order

By default, test methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite execute test methods in the same order, thereby allowing for repeatable builds. In this context, a test method is any instance method that is directly annotated or meta-annotated with @Test, @RepeatedTest, @ParameterizedTest, @TestFactory, or @TestTemplate.

Although true unit tests typically should not rely on the order in which they are executed, there are times when it is necessary to enforce a specific test method execution order — for example, when writing integration tests or functional tests where the sequence of the tests is important, especially in conjunction with @TestInstance(Lifecycle.PER_CLASS).

To control the order in which test methods are executed, annotate your test class or test interface with @TestMethodOrder and specify the desired MethodOrderer implementation.

Field Summary

Modifier and Type	Field and Description
public static final String	CURRENT_REPETITION_PLACEHOLDER Placeholder for the current repetition count of a `@RepeatedTest` method: `{currentRepetition}`
public static final String	DISPLAY_NAME_PLACEHOLDER Placeholder for the display name of a `@RepeatedTest` method: `{displayName}`
public static final String	LONG_DISPLAY_NAME Long display name pattern for a repeated test: {displayName} :: repetition {currentRepetition} of {totalRepetitions}
public static final String	SHORT_DISPLAY_NAME Short display name pattern for a repeated test: repetition {currentRepetition} of {totalRepetitions}
public static final String	TOTAL_REPETITIONS_PLACEHOLDER Placeholder for the total number of repetitions of a `@RepeatedTest` method: `{totalRepetitions}`

Method Summary

Modifier and Type	Method and Description
public int	Returns: the failure threshold; must be greater than zero and less than the total number of repetitions failureThreshold() Configures the number of failures after which remaining repetitions will be automatically skipped.
public String	Returns: a custom display name; never blank or consisting solely of whitespace name() The display name for each repetition of the repeated test.
public int	Returns: the number of repetitions; must be greater than zero value() The number of repetitions.

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

Field Detail

CURRENT_REPETITION_PLACEHOLDER	back to summary
public static final String CURRENT_REPETITION_PLACEHOLDER Placeholder for the current repetition count of a `@RepeatedTest` method: `{currentRepetition}`

DISPLAY_NAME_PLACEHOLDER	back to summary
public static final String DISPLAY_NAME_PLACEHOLDER Placeholder for the display name of a `@RepeatedTest` method: `{displayName}`

LONG_DISPLAY_NAME back to summary

LONG_DISPLAY_NAME	back to summary
public static final String LONG_DISPLAY_NAME Long display name pattern for a repeated test: {displayName} :: repetition {currentRepetition} of {totalRepetitions} See Also `DISPLAY_NAME_PLACEHOLDER`, `SHORT_DISPLAY_NAME`

public static final String LONG_DISPLAY_NAME

Long display name pattern for a repeated test: {displayName} :: repetition {currentRepetition} of {totalRepetitions}

See Also: DISPLAY_NAME_PLACEHOLDER, SHORT_DISPLAY_NAME

SHORT_DISPLAY_NAME back to summary

SHORT_DISPLAY_NAME	back to summary
public static final String SHORT_DISPLAY_NAME Short display name pattern for a repeated test: repetition {currentRepetition} of {totalRepetitions} See Also `CURRENT_REPETITION_PLACEHOLDER`, `TOTAL_REPETITIONS_PLACEHOLDER`, `LONG_DISPLAY_NAME`

public static final String SHORT_DISPLAY_NAME

Short display name pattern for a repeated test: repetition {currentRepetition} of {totalRepetitions}

See Also: CURRENT_REPETITION_PLACEHOLDER, TOTAL_REPETITIONS_PLACEHOLDER, LONG_DISPLAY_NAME

TOTAL_REPETITIONS_PLACEHOLDER	back to summary
public static final String TOTAL_REPETITIONS_PLACEHOLDER Placeholder for the total number of repetitions of a `@RepeatedTest` method: `{totalRepetitions}`

Method Detail

failureThreshold back to summary

failureThreshold	back to summary
public int failureThreshold() Configures the number of failures after which remaining repetitions will be automatically skipped. Set this to a positive number less than the total number of repetitions in order to skip the invocations of remaining repetitions after the specified number of failures has been encountered. For example, if you are using `@RepeatedTest` to repeatedly invoke a test that you suspect to be flaky, a single failure is sufficient to demonstrate that the test is flaky, and there is no need to invoke the remaining repetitions. To support that specific use case, set `failureThreshold = 1`. You can alternatively set the threshold to a number greater than `1` depending on your use case. Defaults to `Integer#MAX_VALUE`, signaling that no failure threshold will be applied, which effectively means that the specified number of repetitions will be invoked regardless of whether any repetitions fail. Warning if the repetitions of a `@RepeatedTest` method are executed in parallel, no guarantees can be made regarding the failure threshold. It is therefore recommended that a `@RepeatedTest` method be annotated with `@Execution(SAME_THREAD)` when parallel execution is configured. Returns:int the failure threshold; must be greater than zero and less than the total number of repetitions Annotations @API status:EXPERIMENTAL since:5.10 Since 5.10

public int failureThreshold()

Configures the number of failures after which remaining repetitions will be automatically skipped.

Set this to a positive number less than the total number of repetitions in order to skip the invocations of remaining repetitions after the specified number of failures has been encountered.

For example, if you are using @RepeatedTest to repeatedly invoke a test that you suspect to be flaky, a single failure is sufficient to demonstrate that the test is flaky, and there is no need to invoke the remaining repetitions. To support that specific use case, set failureThreshold = 1. You can alternatively set the threshold to a number greater than 1 depending on your use case.

Defaults to Integer#MAX_VALUE, signaling that no failure threshold will be applied, which effectively means that the specified number of repetitions will be invoked regardless of whether any repetitions fail.

Warning

if the repetitions of a @RepeatedTest method are executed in parallel, no guarantees can be made regarding the failure threshold. It is therefore recommended that a @RepeatedTest method be annotated with @Execution(SAME_THREAD) when parallel execution is configured.

Returns:int

the failure threshold; must be greater than zero and less than the total number of repetitions

Annotations

@API
status:EXPERIMENTAL
since:5.10

Since

5.10

name back to summary

name	back to summary
public String name() The display name for each repetition of the repeated test. Supported placeholders `DISPLAY_NAME_PLACEHOLDER` `CURRENT_REPETITION_PLACEHOLDER` `TOTAL_REPETITIONS_PLACEHOLDER` Defaults to `SHORT_DISPLAY_NAME`, resulting in names such as `"repetition 1 of 2"`, `"repetition 2 of 2"`, etc. Can be set to `LONG_DISPLAY_NAME`, resulting in names such as `"myRepeatedTest() :: repetition 1 of 2"`, `"myRepeatedTest() :: repetition 2 of 2"`, etc. Alternatively, you can provide a custom display name, optionally using the aforementioned placeholders. Returns:String a custom display name; never blank or consisting solely of whitespace See Also `SHORT_DISPLAY_NAME`, `LONG_DISPLAY_NAME`, `DISPLAY_NAME_PLACEHOLDER`, `CURRENT_REPETITION_PLACEHOLDER`, `TOTAL_REPETITIONS_PLACEHOLDER`, `TestInfo#getDisplayName()`

public String name()

The display name for each repetition of the repeated test.

Supported placeholders

Defaults to SHORT_DISPLAY_NAME, resulting in names such as "repetition 1 of 2", "repetition 2 of 2", etc.

Can be set to LONG_DISPLAY_NAME, resulting in names such as "myRepeatedTest() :: repetition 1 of 2", "myRepeatedTest() :: repetition 2 of 2", etc.

Alternatively, you can provide a custom display name, optionally using the aforementioned placeholders.

Returns:String: a custom display name; never blank or consisting solely of whitespace
See Also: SHORT_DISPLAY_NAME, LONG_DISPLAY_NAME, DISPLAY_NAME_PLACEHOLDER, CURRENT_REPETITION_PLACEHOLDER, TOTAL_REPETITIONS_PLACEHOLDER, TestInfo#getDisplayName()

value	back to summary
public int value() The number of repetitions. Returns:int the number of repetitions; must be greater than zero

value

back to summary

public int value()

The number of repetitions.

Returns:int: the number of repetitions; must be greater than zero