Ordering & Concurrency

## Two axes: coroutines and threads Kotest test bodies are suspending functions, so the framework can interleave many of them on few threads. That gives two distinct knobs. **Concurrency** is how many test coroutines may be in flight at once, set through `AbstractProjectConfig`: - `concurrentSpecs` — how many spec classes run concurrently. - `concurrentTests` — how many tests inside a single spec run concurrently. Both are one-at-a-time by default, which is why a fresh Kotest suite is fully serial. They compose: concurrent specs each running concurrent tests multiplies the in-flight count, so raise one at a time and measure. **Parallelism** is how many threads the engine dispatches onto, set by `parallelism` in the same config. Alongside it, `dispatcherAffinity` (on by default) keeps all tests of a given spec on the same thread. That default matters when the code under test is thread-confined — anything keyed off a thread-local, or context propagation that assumes one thread — because a spec's tests then see a consistent thread even under load. The distinction is worth stating explicitly: raising concurrency without threads still speeds up IO-bound suites, because a suspended test frees its thread; raising threads helps CPU-bound test bodies. Most integration suites are IO-bound and benefit most from concurrency. ## The escape hatches Real suites always contain specs that cannot share the machine. `@Isolate` on a spec class tells Kotest to run that spec alone, never concurrently with others. Use it for specs that mutate process-global state — system properties, static mocks, a shared singleton, a fixed port, a frozen clock. It is the pressure valve that lets you enable concurrency globally without rewriting the whole suite on day one, but each `@Isolate` is debt: it names a spec whose isolation is broken. `.config(blockingTest = true)` addresses the other failure mode. A test body that *blocks* its thread — a sleep, a blocking JDBC call, a legacy client — does not release the thread the way a suspending call does, so under concurrency it can starve other tests sharing that dispatcher. Marking the test as blocking gets it its own thread so the rest keeps moving. ## What actually breaks The failures are all forms of sharing: - **One database.** Two tests inserting the same key, or one truncating tables while another reads. Fixes: per-test transaction rollback, unique keys per test, or a schema or container per concurrent worker. - **Singletons and companion objects.** Any mutable global becomes a race. - **System properties and environment tricks.** Process-wide by definition — `@Isolate` territory. - **Static mocks and global stubs.** Configured by one test, seen by another. - **Fixed ports and fixed temp-file names.** Two specs binding the same port fail nondeterministically. - **Order-dependent tests.** Concurrency destroys the implicit ordering they relied on, so it surfaces the same defects random ordering does, more violently. ## Rollout that works Start in one module. Turn on `concurrentSpecs` first, since cross-spec isolation is usually better than within-spec isolation. Run the suite repeatedly — concurrency bugs are probabilistic, so a single green run proves nothing. `@Isolate` the specs that fail, file the isolation debt, and only then consider `concurrentTests`. Measure wall-clock at each step: if the suite is dominated by one slow spec, concurrency across specs buys nothing until that spec is split. Finally, expect reporting to change: interleaved output makes logs harder to read, and a failure's context can be mixed with unrelated work. Structured per-test output capture matters more once concurrency is on.