@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.
- Since:
- 5.0
- See Also:
-
Required Element Summary
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionint
Configures the number of failures after which remaining repetitions will be automatically skipped.The display name for each repetition of the repeated test. -
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Placeholder for the current repetition count of a@RepeatedTest
method:{currentRepetition}
static final String
static final String
Long display name pattern for a repeated test: "{displayName} :: repetition {currentRepetition} of {totalRepetitions}"static final String
Short display name pattern for a repeated test: "repetition {currentRepetition} of {totalRepetitions}"static final String
Placeholder for the total number of repetitions of a@RepeatedTest
method:{totalRepetitions}
-
Field Details
-
DISPLAY_NAME_PLACEHOLDER
- See Also:
-
CURRENT_REPETITION_PLACEHOLDER
Placeholder for the current repetition count of a@RepeatedTest
method:{currentRepetition}
- See Also:
-
TOTAL_REPETITIONS_PLACEHOLDER
Placeholder for the total number of repetitions of a@RepeatedTest
method:{totalRepetitions}
- See Also:
-
SHORT_DISPLAY_NAME
Short display name pattern for a repeated test: "repetition {currentRepetition} of {totalRepetitions}" -
LONG_DISPLAY_NAME
Long display name pattern for a repeated test: "{displayName} :: repetition {currentRepetition} of {totalRepetitions}"
-
-
Element Details
-
value
int valueThe number of repetitions.- Returns:
- the number of repetitions; must be greater than zero
-
-
-
name
String nameThe 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
, resulting in names such asLONG_DISPLAY_NAME
"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:
- a custom display name; never blank or consisting solely of whitespace
- See Also:
- Default:
- "repetition {currentRepetition} of {totalRepetitions}"
-
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, setfailureThreshold = 1
. You can alternatively set the threshold to a number greater than1
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:
- the failure threshold; must be greater than zero and less than the total number of repetitions
- Since:
- 5.10
- Default:
- 2147483647
-