Annotation Type RetryingTest

@Target({METHOD,ANNOTATION_TYPE})
@Retention(RUNTIME)
@ExtendWith(RetryingTestExtension.class)
@TestTemplate
public @interface RetryingTest

@RetryingTest is a JUnit Jupiter extension that retries a failing test a certain number of times before the test actually shows up as failing.

If annotated with @RetryingTest(n), a test method is executed as long as it keeps failing, but no more than n times. That means all actual executions - except possibly the last - have failed. In contrast, all executions - except possibly the last - show up as being ignored/aborted because that is the best way to communicate a problem without breaking the test suite. Only if all n executions fail, is the last one marked as such. Each ignored/aborted or failed execution includes the underlying exception.

By default the test will be retried on all exceptions except TestAbortedException (which will abort the test entirely). To only retry on specific exceptions, use onExceptions().

@RetryingTest has a number of limitations:

• it can only be applied to methods
• methods annotated with this annotation MUST NOT be annotated with @Test to avoid multiple executions!
• it can't be used with other TestTemplate-based mechanisms like org.junit.jupiter.api.RepeatedTest @RepeatedTest or org.junit.jupiter.params.ParameterizedTest @ParameterizedTest
• it can't be used with org.junit.jupiter.api.DynamicTest @DynamicTest
• all retries are run sequentially, even when used with parallel test execution

During parallel test execution, all repetitions of a RetryingTest are executed sequentially to guarantee thread-safety.

For more details and examples, see the documentation on @RetryingTest.

Before version 0.7.0 this annotation was called @RepeatFailedTest.

Since:

0.4

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DISPLAY_NAME_PLACEHOLDER	Placeholder for the display name of a @RetryingTest: {displayName}
static final String	INDEX_PLACEHOLDER	Placeholder for the current invocation index of a @RetryingTest method (1-based): {index}

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
int	maxAttempts	Specifies how often the test is executed at most.
int	minSuccess	Specifies the minimum number of successful executions of the test.
String	name	The display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace.
Class<? extends Throwable>[]	onExceptions	Specifies on which exceptions a failed test is retried.
int	suspendForMs	Specifies a pause (in milliseconds) between executions.
int	value	Specifies how often the test is executed at most.

Field Details

DISPLAY_NAME_PLACEHOLDER

static final String DISPLAY_NAME_PLACEHOLDER

Placeholder for the display name of a @RetryingTest: {displayName}

Since:

1.7.0

See Also:

• name()
• Constant Field Values

INDEX_PLACEHOLDER

static final String INDEX_PLACEHOLDER

Placeholder for the current invocation index of a @RetryingTest method (1-based): {index}

Since:

1.7.0

See Also:

• name()
• Constant Field Values

Element Details

name

String name

The display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace.

Defaults to [{index}] {arguments}.

Supported placeholders:

- DISPLAY_NAME_PLACEHOLDER - INDEX_PLACEHOLDER

You may use MessageFormat patterns to customize formatting.

Since:

1.7.0

See Also:

• MessageFormat
• ParameterizedTest.name()

Default:

"[{index}]"

value

int value

Specifies how often the test is executed at most.

Alias for maxAttempts().

Default:

0

maxAttempts

int maxAttempts

Specifies how often the test is executed at most.

Either this or value() are required. The value must be greater than minSuccess().

Default:

0

minSuccess

int minSuccess

Specifies the minimum number of successful executions of the test.

The test will be executed at least this number of times. If the test does not complete successfully the given number of times, the test will fail.

Value must be greater than or equal to 1.

Default:

1

suspendForMs

int suspendForMs

Specifies a pause (in milliseconds) between executions.

The thread executing this test is sleeping during that time and won't execute other tests, so long suspensions are discouraged.

Value must be greater than or equal to 0.

Default:

0

onExceptions

Class<? extends Throwable>[] onExceptions

Specifies on which exceptions a failed test is retried.

If no exceptions are specified, tests will always be retried; otherwise only when it throws an exception that can be assigned to one of the specified types.

Default:

{}