@RepeatedTest

## What `@RepeatedTest` is `@RepeatedTest` is a JUnit Jupiter annotation that replaces `@Test` on a method and tells the engine to execute that method a fixed number of times. `@RepeatedTest(10)` runs the method ten times. Mechanically it is not a special case of `@Test`: `@RepeatedTest` is meta-annotated with `@TestTemplate`. A test template is a method that produces *many* invocations, each of which the engine reports as its own test. That is why, in an IDE or an XML report, a repeated test appears as a **container node** (named after the method) with N **child nodes** underneath it, rather than as one test that happened to loop internally. The distinction matters. If you wrote the loop yourself — ```java @Test void generatesUniqueIds() { for (int i = 0; i < 10; i++) { assertNotNull(generator.next()); } } ``` — you would get **one** test result, the first failure would abort the remaining iterations, and setup would run once for all ten iterations. `@RepeatedTest` gives you ten results, ten independent setups, and (by default) execution of every repetition regardless of earlier failures. ## Lifecycle per repetition Each repetition is a full test execution: - `@BeforeEach` and `@AfterEach` run **once per repetition**. - With the default `Lifecycle.PER_METHOD` test-instance lifecycle, a **new instance of the test class** is constructed for each repetition, so instance fields are reset every time. - `@BeforeAll` / `@AfterAll` still run once for the whole class, not per repetition. - Extensions that hook per-test callbacks fire per repetition. The practical consequence: instance state does not leak between repetitions, but anything *outside* the instance does — static fields, singletons, a shared database, an embedded server, files on disk. If a repeated test passes on repetition 1 and fails on repetition 2, the usual culprit is exactly that kind of shared state (for example, an insert that violates a unique constraint the second time round). ## Display names and the name template Because each repetition is its own reported test, it needs its own name. The annotation's `name` attribute is a template with three placeholders: - `{displayName}` — the display name of the method itself (from `@DisplayName`, or the generated name). - `{currentRepetition}` — the 1-based index of this repetition. - `{totalRepetitions}` — the configured total. Two constants ship with the annotation: - `RepeatedTest.SHORT_DISPLAY_NAME` = `"repetition {currentRepetition} of {totalRepetitions}"` — this is the **default**. - `RepeatedTest.LONG_DISPLAY_NAME` = `"{displayName} :: repetition {currentRepetition} of {totalRepetitions}"`. So out of the box you see `repetition 3 of 10`, and the enclosing container carries the method's display name. Setting `name = RepeatedTest.LONG_DISPLAY_NAME` repeats the method name on every child line, which is useful when your CI report flattens the tree and the container name is lost. The `value` attribute (the repetition count) must be positive; `@RepeatedTest(0)` or a negative count is a configuration error, not a silently skipped test. ## When it earns its place Legitimate uses: - **Randomised or property-ish input** — the method draws a fresh random value each run and you want many samples reported individually. - **Warm-up-sensitive behaviour** — caches, lazy initialisation, connection pools that behave differently on the first call than on the hundredth. - **Proving a fix** — you temporarily crank the count while you demonstrate that a previously intermittent test is now stable, then dial it back. - **Idempotency checks** — running the same operation repeatedly must converge to the same state. It is a weak permanent tool for hunting flaky tests, because every repetition runs in the same JVM, on the same thread, in the same order — which is precisely the configuration that just passed. ## Common mistakes - Leaving `@Test` *and* `@RepeatedTest` on the same method. `@Test` is not a repeatable/composable partner here; the method should carry only `@RepeatedTest`. - Assuming setup runs once. It runs per repetition, so an expensive `@BeforeEach` multiplied by 200 repetitions is a slow suite. - Assuming a failure stops the rest. By default it does not — every repetition still runs (see `failureThreshold` if you want early exit). - Depending on order: repetition 5 must not rely on state left by repetition 4. If it does, you have written a stateful sequence, not a repeated test.