Timeout Verification

## The problem it solves In a synchronous test the collaborator is called before your test method resumes, so `verify { mock.f() }` is safe the moment the call under test returns. As soon as the production code hands work to another thread, an executor, or a coroutine on a real dispatcher, the call under test returns *before* the collaborator has been touched. A plain `verify` then fails not because the code is wrong but because the test asked too early. ## What the parameter is MockK's `verify` has a `timeout: Long` parameter measured in milliseconds, defaulting to `0` (no waiting). `coVerify` takes the same parameter for suspend functions. You use it exactly like a normal verify: ``` verify(timeout = 2000) { listener.onFinished(file) } ``` ## The mechanics MockK does not change the mock's behaviour, and it does not re-run your test. It blocks the thread that called `verify` and evaluates the verification block repeatedly against the list of calls recorded on that mock, retrying while the verification is unsatisfied. Two consequences follow directly: 1. **It returns early.** The moment the recorded calls satisfy the block, the loop stops and `verify` returns. A test that would have passed after 3 ms costs about 3 ms even if you wrote `timeout = 5000`. 2. **The failure is the ordinary failure.** When the deadline expires, MockK throws the usual verification-failure assertion showing the expected call and the calls it actually recorded — the same diagnostics as a non-timeout verify, so nothing is lost by adding a timeout. Calls made on *any* thread are recorded against the same mock instance, which is why polling from the test thread eventually sees work performed by a background thread. The mock is shared state; the timeout is just a bounded wait on that shared state changing. ## Why this beats sleeping `Thread.sleep(n)` before a verify has three separate problems. First, the value is a guess about the slowest machine that will ever run the suite — CI under load is far slower than a developer laptop, so the value that passes locally flakes in the pipeline. Second, the cost is unconditional: a hundred tests with a 500 ms sleep add fifty seconds to *every* green run. Third, and most subtly, sleeping does not remove the race; it only moves it. You still assert exactly once, at one instant, so a call arriving one millisecond after the sleep still fails the test. A timeout inverts all three. It is an upper bound rather than a fixed cost, so you can be generous; it converges as soon as the condition is true rather than at a guessed instant; and only genuinely broken tests pay the full duration. ## What it does not do * It does not wait for *quiet* — it waits for a condition to become true, so it cannot prove something never happens (a verification that is already satisfied returns immediately). * It does not synchronise anything after the block. Other in-flight work may still be running when `verify` returns; only what you verified is known to have happened. * The `verifyOrder`, `verifySequence` and `verifyAll` shorthands take no timeout parameter. `verify` itself exposes both `ordering` and `timeout`, so ordered verification with waiting goes through `verify`. * It cannot make exceptions thrown on the background thread visible. If the worker thread dies, nothing propagates into the test; the timeout expiry is your only signal, and the message will say "the call never happened" rather than "the worker crashed". ## Choosing a value Because success returns early, treat the number as a *deadline you are willing to wait before declaring failure*, not as an expected duration. Seconds are normal for work crossing a thread boundary. Very small values (a few tens of milliseconds) reintroduce exactly the flakiness you were trying to remove, because thread scheduling under a loaded CI agent is not bounded by anything that small.