What is Kotest's ConstructorExtension for, and why can it only be registered at project level?

## The construction step Running a spec has an often-invisible first step: turning the spec **class** into a spec **object**. By default Kotest does this reflectively via the no-arg constructor, which is why specs conventionally take no parameters and build their collaborators as properties. `ConstructorExtension` is the hook for that step: ```kotlin interface ConstructorExtension : Extension { fun <T : Spec> instantiate(clazz: KClass<T>): Spec? } ``` For each spec class about to be instantiated, Kotest consults the registered constructor extensions. The `null` return is the important part of the contract: it means "I do not handle this class", and Kotest moves on to the next extension and finally to its own default construction. A well-behaved constructor extension therefore inspects the `KClass` — an annotation, a marker interface, a package — and returns `null` for everything it does not own. An extension that unconditionally returns an object hijacks every spec in the project. ## Why it exists The motivating use case is dependency injection. If a container owns your objects, you would like to write: ```kotlin class OrderTests(private val orders: OrderService) : FunSpec({ /* ... */ }) ``` A no-arg constructor cannot express that. A constructor extension resolves the class through the container and hands the fully wired instance back to Kotest. Framework integrations use this exact mechanism; you can also write your own for a small hand-rolled factory, which is often simpler than pulling a service locator into every spec. Secondary uses: instrumenting construction (recording which specs are built and how often, which is a neat way to *see* what an isolation mode is doing), or substituting a subclass in a controlled environment. ## The registration constraint Spec-level registration works like this: Kotest constructs the spec, then reads its `extensions()`/`extension(...)` registrations, then applies them. Every step depends on the instance existing. A `ConstructorExtension`'s job is to produce that instance. If you register it inside the spec, Kotest must already have constructed the spec by conventional means before it can see the registration — the extension arrives after the moment it was meant to influence. It does not error; it simply never applies, which makes it a genuinely confusing failure. The fix is always the same: move it to `AbstractProjectConfig.extensions()`, the scope that is resolved before any spec is built (or let it be discovered globally, if your setup enables that). ## Frequency of invocation Because it hooks construction, it fires once per **instance**, not once per class. Under a non-single isolation mode a spec class is instantiated repeatedly, and your extension is asked to build each instance. Two consequences: - The work in `instantiate` must be cheap, or at least cheap on repeat. Resolving from a warm container is fine; building a container per call is not. - Anything you inject is re-resolved per instance. If the injected object is stateful and you expected one shared instance per class, the isolation mode has quietly changed your test's sharing model. Scope shared state in the container deliberately rather than by accident. ## Interaction with the rest of the lifecycle Construction sits before every per-instance callback. Ordering, roughly: `prepareSpec` (once per class) → construct instance (constructor extensions) → `beforeSpec` for that instance → tests → `afterSpec` → … → `finalizeSpec` (once per class). So a constructor extension cannot see test results, and it is not the place for setup that belongs in `beforeSpec` — keep it to *producing the object*. ## Signals a candidate understands it - Names the `null` fall-through contract rather than describing it as "a factory Kotest calls". - Knows the registration constraint and can explain the chicken-and-egg reason instead of quoting a rule. - Connects invocation frequency to isolation mode. - Recognises it as a niche hook: most projects never write one, and reaching for it to solve ordinary setup problems is a smell — that is what `beforeSpec` and injected factories are for.