Coroutine Support

## The design choice Kotest was built for Kotlin rather than adapted to it, and one of the visible consequences is that **the test lambda is a suspending lambda**. Every spec style registers bodies of the form `suspend TestScope.() -> Unit`. Kotest then runs each test case inside a coroutine it creates and controls. ```kotlin class UserServiceTest : FunSpec({ test("loads a user") { val user = service.loadUser(1) // suspend call, no wrapper user.name shouldBe "Ada" } }) ``` There is nothing to wrap the body in. The framework already established a coroutine context before invoking your lambda. ## Lifecycle callbacks get the same treatment This is the part candidates most often forget. Kotest's lifecycle DSL — `beforeSpec`, `beforeTest`, `afterTest`, `afterSpec`, container-level callbacks — is suspending as well. Setup that must talk to a suspending client, start a suspending server, or await a connection is written plainly: ```kotlin beforeSpec { server.startSuspending() } afterTest { database.truncateAll() } ``` So the suspending-by-default property is a property of the whole execution model, not just of the leaf test lambda. ## What the coroutine buys the framework Two things matter operationally. **Timeouts become real.** Kotest lets you configure a `timeout` per test (and `invocationTimeout` when a test is configured to run multiple invocations). Because the body is a coroutine, the framework can enforce that bound and cancel at suspension points, rather than being stuck with a thread it cannot safely stop. The important nuance: cancellation is cooperative. A body that blocks a thread in a tight non-suspending loop cannot be cancelled at all, and the timeout will not save you — the suspending model gives Kotest a *mechanism*, not a guarantee against code that never suspends. **Suspending assertion helpers compose.** Kotest's non-deterministic assertions are suspend functions that `delay` between attempts. That only works because the caller — your test body — is itself suspending. In a framework with blocking test methods those helpers would have to block a thread. ## The `CoroutineScope` on the test scope Kotest's test scope implements `CoroutineScope`, so this compiles: ```kotlin test("processes in background") { launch { worker.process() } // ... } ``` Treat that with care. Fire-and-forget work started in a test is a classic source of flakiness and of assertions that race against a job whose completion you never established. The disciplined pattern is to hold the handle and await it: ```kotlin test("processes in background") { val job = async { worker.process() } job.await() shouldBe Result.Ok } ``` If what you want is to observe an effect that genuinely arrives later, that is a job for Kotest's polling assertions, not for hoping a `launch` finished in time. ## Practical consequences for how you write tests 1. **Do not wrap the body in a coroutine builder out of habit.** Adding one nests an extra coroutine inside the one Kotest already made, which mainly costs you clarity — and if the wrapper blocks the thread, it also removes the cancellability the outer timeout depends on. 2. **Push setup that suspends into the suspending lifecycle callbacks** rather than into lazily-initialised blocking helpers. 3. **Be explicit about background work.** Await handles; do not rely on scheduling luck. 4. **Remember that a blocking call is still blocking.** Suspending test bodies do not make a JDBC driver or a `Thread.sleep` non-blocking; they only mean your *own* suspending code needs no ceremony. ## Where this sits relative to time control By default the coroutine Kotest creates uses real time and a real dispatcher: `delay` actually waits. Deterministic virtual time is a separate, opt-in Kotest configuration flag applied per test, per spec or project-wide — a distinct facility from the suspending-by-default execution described here. Knowing which of the two you are relying on is the difference between a test that waits and one that does not.