Listeners & Extensions

## One interface, several doors Everything pluggable in Kotest 5 implements the marker interface `Extension`. Two families sit under it: - **Listeners** — narrow callback interfaces you implement to *observe* the run: `BeforeSpecListener` / `AfterSpecListener`, `BeforeTestListener` / `AfterTestListener`, `BeforeEachListener` / `AfterEachListener`, `BeforeContainerListener` / `AfterContainerListener`, `BeforeInvocationListener` / `AfterInvocationListener`, `PrepareSpecListener` / `FinalizeSpecListener`, and `BeforeProjectListener` / `AfterProjectListener`. The convenience interface `TestListener` bundles the spec/test ones; `ProjectListener` bundles the two project ones. - **Interceptors** — interfaces that *wrap* execution and can change what happens: `SpecExtension`, `TestCaseExtension`, `ConstructorExtension`. Because they share one interface, they share one registration mechanism. What differs is where you register, and that decides scope. ## Door 1 — spec scope Inside a spec you can register inline or by override: ```kotlin class OrderTests : FunSpec({ extension(TimingExtension()) test("places an order") { /* ... */ } }) class PaymentTests : FunSpec() { override fun extensions() = listOf(TimingExtension()) init { test("charges once") { /* ... */ } } } ``` The extension only sees this spec's lifecycle. Two consequences that trip people up: a `BeforeProjectListener` registered here will never fire (the project already started), and a `ConstructorExtension` registered here can never apply to this spec, because the engine had to construct the spec instance before it could read the list. ## Door 2 — project scope A subclass of `AbstractProjectConfig` (Kotest finds one per run) can return extensions that apply to every spec: ```kotlin package io.kotest.provided class ProjectConfig : AbstractProjectConfig() { override fun extensions() = listOf(DatabaseLifecycle, TimingExtension()) } ``` This is the only scope where project-wide behaviour is meaningful: `beforeProject`/`afterProject`, and constructor interception. It is also the right place for anything cross-cutting — a listener that fails the build on leaked threads, a reporter, a global clock reset — because you get uniformity without touching hundreds of files. ## Door 3 — @AutoScan An extension annotated `@AutoScan` is discovered by classpath scanning and applied globally without any explicit registration. It is how some library extensions ship. It depends on classpath scanning being enabled in your setup, and it hides the wiring: someone reading a failing spec has no local clue that an extension is involved. Many teams disable or avoid it and register explicitly in project config instead. ## Per-test scope `TestCaseConfig` also carries an `extensions` list, so `.config(extensions = listOf(...))` on a single test attaches a `TestCaseExtension` to just that test. Rarely used, but it exists — useful when exactly one test needs wrapping and you do not want the rest of the spec paying for it. ## Duplication and ordering Kotest does not deduplicate registrations. Register the same object at project scope *and* in a spec and its callbacks run twice there — a classic source of "my counter is off by one" or "the container started twice". Keep an extension registered in exactly one place, and prefer stateless or idempotent implementations. Interceptor-style extensions nest: each `intercept` receives an `execute` lambda, so the code before your call to `execute` runs on the way in and the code after runs on the way out, with other interceptors layered inside. Do not build logic that depends on a precise ordering between independently registered extensions; if two things must happen in a fixed order, put them in one extension. ## Diagnosing "my extension never ran" Walk the scope question first. Is the callback a project-level one registered at spec level? Is the project config class actually on the test classpath of the module being executed? Is the extension a `ConstructorExtension` registered too late? Is it a spec-level registration on a spec that the current tag filter excluded entirely? Those four cover most cases before you start suspecting the framework.