Package org.junitpioneer.jupiter

Annotation Type RetryingTest

@Target({METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @ExtendWith(org.junitpioneer.jupiter.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

  • 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.
    Class<? extends Throwable>[]
    onExceptions
    Specifies on which exceptions a failed test is retried.
    int
    value
    Specifies how often the test is executed at most.

  • Element Details

    • 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

    • 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:
      {}