Module org.junitpioneer
Package org.junitpioneer.jupiter

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 Fields Description
      static java.lang.String DISPLAY_NAME_PLACEHOLDER
      Placeholder for the display name of a @RetryingTest: {displayName}
      static java.lang.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.
      java.lang.String name
      The display name to be used for individual invocations of the parameterized test; never blank or consisting solely of whitespace.
      java.lang.Class<? extends java.lang.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 Detail

      • DISPLAY_NAME_PLACEHOLDER

        static final java.lang.String DISPLAY_NAME_PLACEHOLDER
        Placeholder for the display name of a @RetryingTest: {displayName}
        Since:
        1.7.0
        See Also:
        name()

      • INDEX_PLACEHOLDER

        static final java.lang.String INDEX_PLACEHOLDER
        Placeholder for the current invocation index of a @RetryingTest method (1-based): {index}
        Since:
        1.7.0
        See Also:
        name()

    • Element Detail

      • name

        java.lang.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

        java.lang.Class<? extends java.lang.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:
        {}