Timeout Assertions

## What a timeout assertion is A timeout assertion answers the question "did this piece of code finish fast enough?" from inside a test method. JUnit 5's assertion entry point is the class `org.junit.jupiter.api.Assertions`, and the two relevant static methods are `assertTimeout` and `assertTimeoutPreemptively`. This answer covers the plain, non-preemptive one. ## The API shape There are two families of overloads: - `assertTimeout(Duration timeout, Executable executable)` — `Executable` is JUnit's functional interface with a single `void execute() throws Throwable` method. Use it when the block returns nothing. - `assertTimeout(Duration timeout, ThrowingSupplier<T> supplier)` — returns `T`, the value the block produced. This lets you write `Order order = assertTimeout(ofSeconds(2), () -> service.place(cart));` and then continue asserting on `order`. Both accept an optional third parameter: a `String` message or a `Supplier<String>` for a lazily built message, appended to the failure output. Because both functional interfaces declare `throws Throwable`, the lambda may throw checked exceptions without a try/catch — a small ergonomic win over writing the timing code by hand. ## Why Duration and not milliseconds The timeout is a `java.time.Duration`, constructed with `Duration.ofMillis(...)`, `Duration.ofSeconds(...)`, `Duration.ofMinutes(...)`. Passing a `Duration` makes the unit part of the value, so a reader never has to guess whether `500` meant milliseconds or seconds, and the same object can be shared as a constant across tests. Static-importing `java.time.Duration.ofMillis` keeps call sites short. ## Execution semantics — same thread, runs to completion This is the single most important behavioural fact. `assertTimeout` does **not** run the block in the background and does **not** stop it at the deadline. It records a start timestamp, invokes the block **on the current test thread**, waits for it to return, records the end timestamp, and only then compares elapsed time to the budget. Consequences: - A block that takes 10 seconds against a 1-second budget still runs for the full 10 seconds; the test simply fails afterwards. The suite pays the full wall-clock cost. - A block that never returns — a deadlock, an infinite loop, a socket read with no read timeout — hangs the test forever. `assertTimeout` gives you no protection against hangs. Hang protection needs `assertTimeoutPreemptively` or the `@Timeout` annotation with a separate-thread mode. - Everything bound to the test thread stays valid: an open transaction, a `ThreadLocal`-held security context, an MDC logging context, a bound persistence context. Nothing is copied or lost, which is exactly why the same-thread variant is the safe default in Spring or Jakarta EE style tests. ## Failure output On overrun, JUnit throws an `AssertionFailedError` whose message reads like `execution exceeded timeout of 500 ms by 132 ms`, optionally prefixed by your custom message. The "by" part is genuinely useful: an overrun of 2 ms reads very differently from an overrun of 4 seconds when you are deciding whether the budget or the code is wrong. If the block throws instead of finishing, the throwable is rethrown as-is (wrapped only where the language requires it), so you see the real stack trace rather than a timing failure. Timing is only evaluated on a normal return. ## Practical guidance Use `assertTimeout` to catch gross regressions — an operation that should be milliseconds suddenly doing network I/O or an N+1 query — not to assert precise latency. Wall-clock time on a shared CI machine is noisy: JIT warm-up, GC pauses, and neighbouring containers all move the number. Pick a budget several times larger than the observed steady-state cost so the test fails only on a real order-of-magnitude change. Also remember the assertion measures whatever is inside the lambda, including any setup you accidentally left there. Move fixture construction outside the block so you are timing the operation under test, not the arrangement. ## Minimal example ```java String body = assertTimeout(Duration.ofMillis(300), () -> renderer.render(template, model), "template rendering regressed"); assertTrue(body.contains("<h1>")); ``` That single call both bounds the work and hands you the result for further assertions, which is why the `ThrowingSupplier` overload is usually the one you want.