Skip to content
javahacks.dev
JUnit

How to Set JUnit Timeouts and Retry Flaky Tests Correctly

Set timeouts with @Timeout and assertTimeout in JUnit 5, understand threading differences, and handle flaky tests without hiding real bugs through retries.

5 min read
Summarize in AI
Flat illustration of a JUnit test run with one failing test, with the JUnit5, Jenkins and Selenium logos.

A hanging test blocks the build until the CI job times out, often hours later, and the report says nothing about which test hung. A timeout turns that into a failure with a name and a stack trace in minutes. This guide covers the timeout annotation, a project-wide default, the two assertion forms and their threading trap, the right way to deal with flaky tests and what to do if you must retry. It targets JUnit Jupiter 6 on JDK 25, and everything shown also holds for JUnit 5.13.

The annotation

java
@Test
@Timeout(value = 500, unit = TimeUnit.MILLISECONDS)
void parsesQuickly() {
    parser.parse(sample);
}

@Timeout(5)
class IntegrationTests {

    @Test
    void loads() { /* five second limit per test */ }
}

The default unit is seconds. On a class, the limit applies to each test method separately. It can also go on @BeforeEach and other lifecycle methods, which is where a stuck connection to a container usually hangs. When the limit is exceeded, JUnit interrupts the test thread and fails the test with a message naming the limit. The interrupt matters: a test blocked on Thread.sleep, a lock acquired with a timeout or a blocking queue stops promptly, while code in a tight CPU loop that never checks the interrupt flag keeps running until it finishes on its own, and the test is reported as failed afterwards.

A default for every test

src/test/resources/junit-platform.propertiesproperties
junit.jupiter.execution.timeout.default = 30 s
junit.jupiter.execution.timeout.testable.method.default = 10 s

A project-wide ceiling catches the infinite loop nobody expected, with no changes to the tests. Choose a number far above your slowest legitimate test, so it never fires except in a real hang. Specific tests that need longer override the default with their own annotation. The full list of keys is in junit-platform.properties.

Block-level assertions

java
assertTimeout(Duration.ofSeconds(1), () -> service.compute(input));

assertTimeoutPreemptively(Duration.ofSeconds(1), () -> service.compute(input));

assertTimeout runs the block in the calling thread and fails only after the block finishes, so a true infinite loop still hangs the build. assertTimeoutPreemptively runs the block in a separate thread and abandons it at the limit. The price is a different thread: thread locals, security contexts and the transaction that Spring's test support opened are not visible inside the lambda. A test that passes with assertTimeout and fails with the preemptive form usually depends on one of them. Prefer the annotation, which interrupts the original thread and avoids the issue.

Fix flaky tests, do not retry them

A flaky test passes and fails with no code change. The first step is to reproduce it on demand, and @RepeatedTest does that.

java
@RepeatedTest(200)
void flakyOrdering() {
    assertEquals(expected, service.process());
}

If it fails once in two hundred runs, you have a reproduction, and the failure rate is a number you can lower. The causes are few and well known.

CauseFix
Real clock or sleepInject a Clock, wait on a condition instead
Unordered collectionsSort, or compare as sets
Shared static stateReset per test, see parallel execution
Concurrency raceFix the race, see Heisenbugs
External serviceReplace with a fake, see test doubles

Rather than sleeping for a fixed time and hoping, poll with a deadline using a library such as Awaitility: the test continues the moment the condition is true and fails with a clear message if it never becomes true. Fixed sleeps are both the slowest and the flakiest option, because the right duration differs between your laptop and a busy CI agent.

If you must retry

JUnit does not retry on its own. A rerun extension, or the Surefire setting rerunFailingTestsCount, re-executes failures and reports a test as flaky if a later run passes. Treat that as containment while a ticket exists, never as a fix. Report the reruns separately, so the number stays visible and does not hide in a green build. A suite that passes only after retries is a suite whose failures nobody trusts, and the habit of rerunning a red build until it is green spreads from the flaky test to real regressions.

What to do on a timeout

When a timeout fires, read the thread dump, not just the message. The interrupted test thread's stack shows exactly where it was waiting. Typical findings are a connection that never closes, a latch that is never counted down because an exception happened first, and a lock acquired in the wrong order. If the failure is intermittent, add the thread dump to the CI artifacts, so the next occurrence arrives with evidence. A related technique is described in reading a thread dump.

Choosing the numbers

Set the per-test timeout from the slowest healthy run, with a generous margin. If the longest integration test takes eight seconds on CI, a ceiling of 60 seconds for the class catches hangs without firing on a busy agent. Unit tests deserve tighter limits, a second or two, because they should never touch the network. Keep the numbers in properties and annotations rather than scattered in test bodies, and review them when the suite slows down. A timeout that is raised every time it fires has stopped doing its job.

Timeouts in the build tool

Surefire has its own forkedProcessTimeoutInSeconds, and Gradle can set a timeout on the test task. These kill the whole test JVM, which is a coarser tool than a per-test limit, since you lose the name of the test that hung. Use the build-level limit as a last resort behind the JUnit ones, and make it long enough that the finer limits fire first. CI systems add a third layer, the job timeout. Three layers of increasing size give you a named failure in the common case and a clean kill in the worst.

Timeouts in parameterised and nested tests

A timeout annotation on a parameterised test applies to each invocation separately, and one on a nested class applies to its tests. If a long setup method belongs to the whole class, give it a longer limit on the @BeforeAll method, and keep the per-test limit short. When tests share an expensive resource through an extension, put a timeout on the extension's callbacks too, because a hung container start is the most common cause of a stuck build.

Where timeouts do not help

Timeouts are a guard, not a performance test. They fire on a slow CI agent as readily as on a slow algorithm, so do not use a tight timeout to assert speed; use a benchmark for that. The semantics are in the declarative timeouts section and the repeated tests section of the user guide. The repetition annotations are explained in repeated tests and templates.

Also inTesting
Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.