Project-Level Config

## What the class is `AbstractProjectConfig` is the single place to express run-wide test settings: default isolation mode, default timeouts, assertion mode, test ordering, concurrency knobs, globally registered extensions, and project-level `beforeProject`/`afterProject` callbacks. You subclass it and override the properties or functions you care about; everything you do not override keeps Kotest's default. ```kotlin package io.kotest.provided class ProjectConfig : AbstractProjectConfig() { override val isolationMode = IsolationMode.SingleInstance override val timeout = 30.seconds override fun extensions() = listOf(MyGlobalListener) override suspend fun beforeProject() { /* run-wide setup */ } } ``` The class name does not matter; the type and the location do. ## Detection in Kotest 5 Two mechanisms: 1. **Package convention.** Kotest 5 looks for a subclass of `AbstractProjectConfig` in the package `io.kotest.provided`. This is the scan-free path and the one to teach your team: put the file in a source directory whose package declaration is `io.kotest.provided`, in the test source set. 2. **Explicit FQN.** The system property `kotest.framework.config.fqn` names the config class directly, wherever it lives. Useful when you keep configuration in your own package structure, or when a shared test-support artefact supplies it. Either way, a single config is used for the run. Do not expect two config classes to merge — write one, and have it delegate to shared helpers if several teams contribute settings. ## Why it is a class and not a file Because configuration is code: you can compute a timeout from an environment variable, register different extensions on CI than locally, or build the extension list from a helper shared across modules. That expressiveness is the reason the config is not simply a properties file — though several settings can *also* be supplied through system properties or a `kotest.properties` file on the classpath, which is how CI often adjusts a run without editing code. ## Debugging "my config is ignored" Work through the chain, cheapest first. - **Package.** Is the declared package exactly `io.kotest.provided`? A file in a directory called `provided` with a different `package` line does not count — Kotest resolves by package, not by folder. - **Classpath and module.** Test runs resolve config from the classpath of the module being executed. In a multi-module repository, module B's tests do not see module A's config unless the config ships in an artefact that B depends on (and even then, only if it lands in `io.kotest.provided` or is named via the FQN property). - **Source set.** A config compiled into main rather than test may not be on the test run's classpath at all. - **Constructibility.** Kotest instantiates it reflectively; it needs to be public with a no-arg constructor (an `object` also works). - **The FQN property reaching the right JVM.** Setting a system property in a shell is not the same as it arriving in the forked JVM that runs the tests; verify with a `println(System.getProperty(...))` from a test if in doubt. - **Real override.** `override val isolationMode = …` fails to compile if the name is wrong, which is good — but a hand-written `val isolationMode` with no `override` (in an unrelated helper) silently does nothing. Prefer explicit `override`. - **Being overridden downstream.** A setting can be present and still not take effect because something more specific wins — a spec-level property or per-test `.config(...)`. Confirm by checking the spec before blaming detection. ## Practical conventions - Keep exactly one config class per module that runs tests, all in `io.kotest.provided`, all thin — a few overrides plus `extensions()` pointing at objects declared elsewhere. - Put shared behaviour in a test-support artefact and have each module's config register it, rather than trying to make one config serve every module. - Comment non-obvious global settings with *why*: a global default is invisible from the spec that it affects, so the reasoning must live somewhere a reader will find.