Kotest

A container is itself a test node whose body executes during the run to register and run its children — it is not a before-hook. Code in it runs inline, may re-execute per leaf depending on the isolation mode, and a throw there fails the container and prevents its unregistered children from ever running.

Prefix the block with x: xgiven, xwhen, xthen, xand, xfeature, xscenario. Kotest marks that node disabled and never executes its body, so nested blocks are never registered and never appear individually - only the disabled node is reported as ignored.

The name is the string argument you pass to the DSL builder, evaluated when the spec registers its tests. It becomes the test's identity: shown in IDE and CI reports, used for name-based filtering, and it must be unique within its scope.

should("...") { } registers one leaf test whose reported name reads as "should ...". Grouping is done with context("...") { } containers, which may hold should leaves and further nested contexts. should also works at the spec root.

You write "a stack" should { "pop returns the last item" { ... } }. The should block is a container whose name renders as "a stack should"; the inner strings are leaf tests. An optional outer When block adds one scenario layer. Nesting is fixed: When → should → test.

shouldContainExactly requires the same elements in the same order and the same size. shouldContainExactlyInAnyOrder requires the same multiset — same size and same duplicate counts, order irrelevant. shouldContainAll is only a subset check: extras and duplicate mismatches are ignored.

Kotest's shouldBe does not simply call equals. It dispatches on runtime type first: arrays are compared by contents rather than by reference, iterables and maps element-wise with a positional diff, data classes with per-field failure reporting. Everything else falls back to equals.

failureMessage is shown when the matcher is used positively (should / a shouldX extension) and does not pass. negatedFailureMessage is shown when it is used negatively (shouldNot) and it does pass. Copying the positive text into the negated slot makes failures report the opposite of reality.

It returns the caught exception, already typed as T. Bind it and assert on message, cause or custom fields. Use shouldThrowUnit<T> when the block's last expression is Unit, because plain shouldThrow expects a block returning Any?.

Inside the block Kotest switches its error collector to soft mode, so matcher failures are recorded instead of thrown; at the end it throws one MultiAssertionError listing them all. Only failures routed through Kotest's collector are aggregated — non-assertion exceptions abort the block immediately.

Pass one Arb per constructor parameter to Kotest's Arb.bind, with a lambda that assembles the object: Arb.bind(Arb.string(), Arb.int(1..120)) { n, a -> Person(n, a) }. The result is a real Arb, so its fields keep their edge cases and shrink independently.

checkAll's lambda returns Unit and fails when an assertion inside it throws. forAll's lambda must return Boolean and fails when it returns false. forNone is the inverse — it fails when the predicate returns true.

An Arb is not purely random: it declares a set of edge cases alongside its random sampler, and Kotest interleaves those edge cases into the value stream with a small, configurable probability, so boundary values appear far more often than chance would produce.

Kotest prints the seed that drove the run's random source. Re-run the property with PropTestConfig(seed = thatValue) and the same generators produce the same samples in the same order, reproducing the failure — unless the test depends on anything outside that random source.

map transforms each sampled value (Arb<A> to Arb<B>). flatMap feeds a sampled value into a function that picks the next generator, so it expresses dependent values. filter re-samples until a predicate passes — it wastes samples, can skew the distribution and can stall when matches are rare.

Every row runs. Kotest collects the failures instead of stopping at the first one and then throws a single error that lists each failing row with its header/value pairs and that row's assertion error, so you see all bad rows in one run.

Kotest asks the element for a stable identifier: a WithDataTestName implementation wins, then an @IsStableType-annotated class's toString, then a data class's toString. Anything else falls back to a type-derived name, so every case ends up named the same.

Each arity has its own generated type — row(1, "a") is a two-column row, and table(headers, rows...) fixes both the column count and each column's type. forAll then hands the lambda one typed parameter per column. Limits: fixed arity, one type per column across all rows, positional access only.

Four hooks: implement WithDataTestName on the type, annotate the class @IsStableType so its toString is trusted, pass the nameFn overload withData({ "case ${it.id}" }, values), or pass a Map<String, T> whose keys become the names verbatim.

It can sit at the spec root, inside a container such as FunSpec's context, and inside another withData. Each element is registered as a node whose body is a container scope: it reports as a leaf test if nothing nested is registered, and as a container if the body registers more tests.

Declare Kotest's beforeTest { } and afterTest { } blocks in the spec body. beforeTest receives the TestCase about to run; afterTest receives a TestCase/TestResult pair. Both are suspend lambdas, so suspending setup and cleanup work directly.

Inside a spec via extension(...) or override fun extensions() — that spec only. In a class extending Kotest's AbstractProjectConfig via override fun extensions() — every spec in the run. Or @AutoScan for classpath-discovered global extensions.

Kotest treats containers and leaves both as test cases. beforeEach/afterEach fire only for leaf tests; beforeContainer/afterContainer only for containers; beforeTest/afterTest and their aliases beforeAny/afterAny fire for both.

SingleInstance: one instance for all tests. InstancePerRoot: a fresh instance per top-level test, everything nested under it shares that instance. InstancePerTest: a fresh instance per test case, containers included. InstancePerLeaf: a fresh instance per leaf test, with its container path re-executed.

Write one class (or object) extending AbstractProjectConfig with a no-arg constructor. Kotest 5 picks it up by convention from the io.kotest.provided package on the test classpath, or from the fully qualified name given in the kotest.framework.config.fqn system property. One config applies per run.

Kotest invokes every test body — and every lifecycle callback like beforeTest and beforeSpec — inside a coroutine, so suspending calls are made directly with no wrapper builder. The test scope is itself a CoroutineScope, and Kotest enforces the test's configured timeout around that coroutine.

Kotest specs are executed by Kotest's own TestEngine, not JUnit Jupiter, and Jupiter annotations only mean something to the Jupiter engine. Use Kotest's own facilities instead: beforeTest/afterTest/beforeSpec, .config(enabled = false) or the x-prefixed builders, @Ignored on the spec, and Kotest Tag objects.

eventually re-runs a block until it stops throwing, within a deadline — the first success passes. until does the same for a boolean predicate becoming true. continually requires the block to keep passing for the whole duration — the first failure fails the test.

It contains Kotest's JUnit Platform TestEngine implementation. The platform discovers that engine alongside any others, hands it the discovery request, and the engine finds Kotest spec classes, runs their tests with Kotest's own coroutine-based executor, and reports each test case back to the platform as it goes.

kotest-runner-junit5 runs specs; kotest-assertions-core holds the shouldBe/shouldContain matcher family; kotest-property provides Arb/Exhaustive property testing; kotest-framework-datatest provides withData; kotest-assertions-json adds JSON matchers. You add only the modules you use.