Your JUnit 5 suite occasionally wedges in CI and a job has to be cancelled manually. How would you design a time-limit policy across the suite, and what are the tradeoffs of the options you would consider?

## Framing the decision The question is not "what number" but "what is a timeout for here". Two different goals get confused: **liveness** (no run may hang forever) and **latency** (this operation must be fast). Test-level time limits are good at the first and bad at the second, because CI machines are shared, throttled, and highly variable. A policy that mixes the goals produces flaky tests, which erodes trust in the suite far more than the original hang did. ## Layer 1: the deadlock net The cheapest, highest-value move is one line of configuration: a suite-wide default applied to every method through `junit.jupiter.execution.timeout.default`. Choose it an order of magnitude above the slowest legitimate method — if the slowest honest test is twenty seconds, five minutes is a fine net. It will effectively never fire during normal operation, so it adds no flakiness, but it converts an infinite hang into a reported failure with a stack trace. Within the net it is worth differentiating by category. Fixtures deserve stricter budgets than tests: `junit.jupiter.execution.timeout.beforeeach.method.default` of thirty seconds is defensible when no honest per-test setup takes that long, and setup hangs are the most common wedge (a container that never becomes ready, a port already bound, a pool waiting for a connection that never returns). ## Layer 2: targeted annotations Above the net, annotate deliberately. Class-level `@Timeout` on integration test classes gives a tighter budget where hangs are plausible without touching the fast unit suite. Method-level annotations are for two cases: a method whose whole point is that it must not block (a circuit-breaker test, a client with a configured read timeout), and the reverse — a genuinely slow test that needs to opt out of a tighter class budget. The discipline to insist on: the number must be justified by an argument, not by measurement plus a fudge factor. "Our HTTP client is configured with a two-second read timeout, so this test cannot honestly exceed five seconds" is a maintainable rule. "It took 800 ms on my laptop so I set one second" is a future flake. ## Layer 3: the hard stop outside the JVM The uncomfortable truth is that in the default same-thread mode Jupiter's limits are advisory. The watchdog interrupts the test thread; code that ignores interruption — a busy loop, a classic blocking socket read, a native call, a `catch (InterruptedException) { /* retry */ }` — carries on, and the failure is only recorded when the method returns. So the only genuine guarantee is above the JVM: a per-job wall-clock cap in CI, ideally preceded by a thread dump so the hang is diagnosable rather than merely killed. If you skip the dump you get a red job and no evidence, and the hang recurs. ## The thread-mode call Switching the suite-wide thread mode to `SEPARATE_THREAD` looks tempting because it makes limits preemptive. I would not do it globally. It abandons the runaway thread — which may hold a lock, an open transaction, or a pooled connection — so later tests can deadlock or see dirty state, turning one hang into a cascade. And it removes thread affinity, breaking Spring transactional rollback, `SecurityContextHolder`, and MDC. The right shape is same-thread by default with a narrow, commented opt-in for the handful of tests exercising known-uninterruptible code. ## Developer experience A strict policy must not punish debugging. `junit.jupiter.execution.timeout.mode = disabled_on_debug` keeps a single committed configuration that enforces on CI and stands down under a debug agent, so nobody edits the file locally and forgets to restore it. Time limits should also produce good failures: the message names the method and duration, but the useful artefact is a thread dump at the moment of the timeout, which an extension can produce. ## Governance Finally, treat firing timeouts as a signal to manage. If a limit fires, the default response is investigation, not a bigger number; a repository where budgets creep upward over time has quietly turned its net into decoration. Track which tests time out, and if the same one fires repeatedly, either the code under test lacks its own bounded I/O timeouts — the real fix, since a client with a proper read timeout cannot hang — or the test is doing something it should not. ## The summary answer Generous global net, category-specific tightening for fixtures, targeted annotations with justified numbers, same-thread default for safety, debugger-aware mode, hard cap outside the JVM with a thread dump, and a policy that a firing timeout is a bug report.