Package org.junit.jupiter.api

Annotation Type RepeatedTest

  • @Target({ANNOTATION_TYPE,METHOD})
@Retention(RUNTIME)
@Documented
@API(status=STABLE,
     since="5.0")
@TestTemplate
public @interface 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.

    Inheritance

    @RepeatedTest methods are inherited from superclasses as long as they are not overridden according to the visibility rules of the Java language. Similarly, @RepeatedTest methods declared as interface default methods are inherited as long as they are not overridden.

    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:
    DisplayName, RepetitionInfo, TestTemplate, TestInfo, Test

    • Field Summary

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

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      int value
      The number of repetitions.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      int failureThreshold
      Configures the number of failures after which remaining repetitions will be automatically skipped.
      java.lang.String name
      The display name for each repetition of the repeated test.

    • Field Detail

      • DISPLAY_NAME_PLACEHOLDER

        static final java.lang.String DISPLAY_NAME_PLACEHOLDER
        Placeholder for the display name of a @RepeatedTest method: {displayName}

      • CURRENT_REPETITION_PLACEHOLDER

        static final java.lang.String CURRENT_REPETITION_PLACEHOLDER
        Placeholder for the current repetition count of a @RepeatedTest method: {currentRepetition}

      • TOTAL_REPETITIONS_PLACEHOLDER

        static final java.lang.String TOTAL_REPETITIONS_PLACEHOLDER
        Placeholder for the total number of repetitions of a @RepeatedTest method: {totalRepetitions}

      • LONG_DISPLAY_NAME

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

    • Element Detail

      • value

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

      • failureThreshold

        @API(status=MAINTAINED,
     since="5.13.3")
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:
        the failure threshold; must be greater than zero and less than the total number of repetitions
        Since:
        5.10
        Default:
        2147483647