Configuration

Fairlead reads one file at the root of your repository: fairlead.toml, or fairlead.yaml if you prefer YAML. Both formats mean exactly the same thing. Every key has a default, so a repository without a config file works too.

fairlead config check          # validate every layer and the merged result
fairlead config show           # the merged config
fairlead config show --origin  # each value, with the layer that set it
fairlead config schema         # JSON Schema, for editor autocomplete

Layers

Later layers override earlier ones:

1. Built-in defaults, then any framework packs the files below name in extends.
2. Since 0.10.0: the workspace file, when the repository is in a workspace folder. Its [workspace] table is left out, and it’s ignored when the CI environment variable is set.
3. The project file: fairlead.toml or fairlead.yaml, found by walking up from the current directory, never past the repository root (the first directory holding .git). Two in the same directory is an error.
4. The environment’s shared file, fairlead.<name>.toml (or .yaml), when an environment is named. See Environments.
5. The local file, fairlead.local.toml (or .yaml), next to the project file. Keep it out of git. It’s ignored when the CI environment variable is set.
6. The environment’s local file, fairlead.<name>.local.toml, also out of git and ignored in CI.
7. Environment variables: FAIRLEAD_ followed by the key path, with sections separated by a double underscore. So FAIRLEAD_TESTS__UNREACHED=all sets tests.unreached.
8. --set key=value, for one run: fairlead config show --set tests.unreached=all.

For environment variables and --set, a value that parses as a TOML boolean, number or array (true, 30, ["a", "b"]) is used as that type; anything else, dates included, is a string. Environment variables apply in name order.

Environments

Name an environment with FAIRLEAD_ENV=staging, or --env staging on any command, and Fairlead layers fairlead.staging.toml over the project file and fairlead.staging.local.toml over the local one. A file with no .local is shared and belongs in git; one with .local is yours and stays out of it, like fairlead.local.toml.

fairlead.toml                 every environment
fairlead.staging.toml         staging, shared
fairlead.local.toml           you, every environment
fairlead.staging.local.toml   you, in staging

Environment files sit beside the project file, wherever you run from. An environment name is lowercase letters, digits and dashes, and can’t be local. Naming an environment with no file for it is an error, so a typo can’t fall back to the defaults silently. In CI only the shared file counts, so an environment CI uses needs one. replay run --config reads exactly the file it names, with no environment or local layers.

Lists

Lists append across layers, so your plan.run_all adds to the built-in one. To replace a list instead, write it as { replace = [...] }:

[tests]
match = { replace = ["test/**/*.ts"] }

So run_all = [] appends nothing and the built-in list stays; config check warns about an empty list written over one that already has items. { replace = [] } clears it.

Globs

* matches within a path segment and ** across segments. {a,b} is an alternation, and alternations nest: {src/**/*.test.{ts,tsx},tests/**}. A brace group of just a name, like {name}, captures that segment instead, where the key supports captures. [abc] is a character class. A backslash makes the next character literal, so a path with brackets is app/**/\[...slug\]/** (in TOML’s double-quoted strings the backslash itself is doubled: "app/**/\\[...slug\\]/**"). config check compiles every glob, so one that can’t compile fails there, not at plan time.

Errors

Unknown keys are errors, so a typo can’t silently switch something off. Every error names the file or layer it came from, and the key:

fairlead.toml: tests.unreachd: unknown field `unreachd`, expected one of ...

Keys

Commands are always argv arrays, never shell strings, and {files} expands to one argument per file. {packages} expands to one ./dir per directory holding a selected test, or ./... when everything runs, for go test. Since 0.7.0: for Maven and Gradle, an argument holding {class} is repeated once per selected test class and {classes} joins them with commas; either is dropped when everything runs (Java and Kotlin). In tests.runners.cwd, {module} is the module’s root path and {module.id} its id.

Since 0.7.1: when everything runs, {files} expands to nothing, so bun test {files} becomes a bare bun test, which runs every test the tool finds, end-to-end specs included, not only the files the runner’s match claims. A runner’s all_command is the argv to use instead whenever everything runs, such as ["bun", "test", "test/unit"]; without one, command runs with no files, as before. It takes the same placeholders as command except {files}, {class} and {classes}, which have nothing to expand to there and fail config check: {packages} is ./..., and {module} and {module.id} are filled in per module. exclude_arg is an argv fragment holding {file}, such as ["--exclude", "{file}"] or ["--ignore={file}"], added once for each test a [[quarantine]] entry holds, so a run of everything can leave out the tests that run alone (Invocations).

config check validates every key’s type, the ids, placeholders and references between sections, and lists test files that match no runner or more than one. In tests.owners, a placeholder used in covers must be captured in match.