Spec Styles

## Containers are tests, not hooks A developer arriving from annotation-driven frameworks reads ```kotlin describe("the order service") { val repo = InMemoryOrderRepo() // "setup" val service = OrderService(repo) it("creates an order") { ... } it("rejects a duplicate") { ... } } ``` as *"setup, then two tests"* — as if the first two lines were a before-each. They are not. In Kotest the `describe` block is itself a node in the test tree (a **container**), and its lambda is **executed code that runs during the test run**. When it runs, the two `val` initialisations execute, then each `it(...)` call **registers** a child, and the children execute. That is a materially different model from a hook, and every trap below follows from it. ## Trap 1 — ordering is textual, not phase-based Because the body is straight-line code interleaved with registrations, the position of a statement matters: ```kotlin context("a queue") { counter = 0 // runs before both leaves test("first") { counter++ } counter = 100 // runs AFTER "first" has run test("second") { counter shouldBe 101 } } ``` There is no phase separation that hoists all setup above all tests. Reviewers who assume a hook-like model misread such files routinely. ## Trap 2 — re-execution depends on isolation Kotest's `IsolationMode` decides how spec instances and container bodies relate to leaves. Under the default single-instance behaviour, a container body runs **once** and every descendant leaf shares whatever it created — so a mutable fixture accumulates state across leaves and tests become order-dependent. Under an isolation mode that gives each leaf its own instance, the path of containers leading to a leaf is **re-executed for every leaf**, so the fixture is fresh each time and the accumulation disappears. That is the nastiest property of inline container setup: **the same test file passes or fails depending on a setting declared somewhere else** — a spec property or a project-wide default. A test whose correctness depends on the isolation mode is not communicating its own requirements. Worse, re-execution also re-runs any *side effects* in the body: starting a container, opening a connection, seeding a database. What looked like a once-per-group cost silently becomes once-per-leaf. ## Trap 3 — a throwing container swallows a subtree Suppose the second line of the container body throws: ```kotlin context("with a seeded db") { val db = connect() // throws test("reads a row") { } // never registered test("writes a row") { } // never registered } ``` The container is reported as **failed**, and the two leaves are not "failed" — they never existed as far as the report is concerned. Counting tests across runs is the only way to notice. Compare that with a lifecycle callback failure, which Kotest attributes to the tests it guards, or with a leaf-level failure, which names exactly one test. Silent subtree loss is the reason "containers declare structure only" is a rule and not a preference. The same logic applies to **assertions** placed in a container body: a failed assertion there aborts registration of everything below it. An assertion belongs in a leaf, where it names one test and where its failure cannot delete siblings. ## Trap 4 — a container body that does real work distorts timings and hooks Because the container is a test node, its duration includes whatever you did inline. Slow work in a container shows up as a slow *container*, not as a slow test, which makes profiling a suite harder. And Kotest's lifecycle callbacks fire relative to the tree — a before-test callback does not run before the statements you inlined into the enclosing container body, because those statements are part of the container's own execution. ## What to do instead 1. **Fixtures go in lifecycle callbacks.** Kotest gives you callbacks that run around each test and around the spec; they have well-defined, isolation-independent semantics, and a failure inside one is attributed to the tests it guards rather than deleting them. 2. **Prefer per-leaf construction.** Where a fixture is cheap, build it inside the leaf. A test that constructs its own world is order-independent by construction and reads without reference to any configuration. 3. **State the isolation mode explicitly when it matters.** If a spec genuinely relies on fresh state per leaf, say so on the spec rather than inheriting a project default that someone may change. 4. **Keep container bodies to declarations.** The ideal container body contains registration calls and nothing else — perhaps a `val` holding an immutable test constant, which is safe because nothing mutates it. 5. **Be deliberate about expensive shared resources.** A single resource that must exist for a whole spec (a database container, a server) belongs in spec-level lifecycle handling with explicit cleanup, not in a container body where the isolation mode decides how many you start. ## The senior-level summary "A container is a test node whose body is executed registration code, not a before-hook. Statements run inline and interleave with child registration; the number of times they run is decided by the isolation mode, not by the file; and a throw there fails the container and erases its unregistered children from the report. So container bodies declare structure, fixtures live in lifecycle callbacks or in the leaf, and assertions live only in leaves."