Flat Styles

## What ShouldSpec is Kotest ships several *spec styles* — different DSLs that all produce the same underlying test tree. **ShouldSpec** is the style built around the keyword `should`. You extend it either by passing a lambda to the constructor (`class X : ShouldSpec({ ... })`) or by putting the DSL calls in an `init` block (`class X : ShouldSpec() { init { ... } }`). Both forms are equivalent; the lambda form is the more common idiom. ## Leaves and containers Kotest's test tree has exactly two kinds of node: - A **leaf** (terminal test) has a body of assertions and is what a report counts as a passing or failing test. - A **container** has no assertions of its own; its job is to declare child nodes and to contribute a name segment to their path. In ShouldSpec: - `should("...") { ... }` registers a **leaf**. You may not nest another `should` (or a `context`) inside it — the DSL scope inside a `should` body does not offer those functions, so the mistake is a compile error rather than a runtime surprise. - `context("...") { ... }` registers a **container**. Inside it you may write `should` leaves and further `context` blocks, nesting as deep as you find readable. Both `should` and `context` are legal at the spec root, which is what makes ShouldSpec unusual: a file that only uses root-level `should` calls is a flat list of tests, indistinguishable in shape from a StringSpec or a FunSpec, while a file that opens with `context` reads like a nested spec. ## Name derivation The string you pass is not the whole displayed name. Kotest prefixes the leaf with the keyword, so `should("return an empty list")` is reported as *"should return an empty list"*. The practical consequence is a naming convention: write the string as the **predicate of a sentence** whose subject is the surrounding context and whose verb is supplied by `should`. Writing `should("it should return an empty list")` produces a stuttering name in the report. When the leaf sits inside containers, the full test path is the concatenation of the container names and the leaf name, in declaration order — this is what appears in IDE test trees and in build reports, and it is what you match against when filtering by test name. ## Typical shape ```kotlin class PriceCalculatorTest : ShouldSpec({ context("an empty basket") { should("cost zero") { calculate(emptyList()) shouldBe 0 } } context("a basket with one item") { context("and no discount") { should("cost the item price") { } } context("and a percentage discount") { should("apply the discount") { } } } }) ``` The context strings carry the *state or scenario*; the should strings carry the *expected behaviour*. Read top to bottom, each leaf's path is a sentence. ## Where the body runs Every `should` and `context` body is a **suspending** lambda, so you can call suspend functions directly in a test without wrapping them in a blocking builder. Bodies of containers are not setup hooks: a container body executes as part of the run, in order, to register and run its children. If you need setup, prefer Kotest's lifecycle callbacks rather than statements dropped at the top of a `context`. ## Choosing it ShouldSpec appeals to teams who want behaviour-flavoured test names without the ceremony of a full given/when/then structure, and it scales down gracefully: small specs stay flat, and you introduce `context` only when a group genuinely needs a shared heading. The cost is that `should` is fixed as the leaf keyword, so it cannot express a test name that is not naturally phrased as "should ...". ## Common mistakes Expecting `should` to nest is the usual one — people try to write an outer `should("handle errors")` grouping inner `should` calls, which does not compile. The other is confusing this `should` (a **test registration function** taking a name and a lambda) with the matcher infix functions such as `shouldBe`, which assert inside a test body. They are unrelated APIs that happen to share a word.