Prepare for Doc Detective 5.0

Doc Detective 5.0 makes the CLI safer to rely on in CI, and it’s a breaking release. It isn’t out yet. If you landed here from a warning in your logs, your setup uses something that changes in 5.0, and nothing breaks until you upgrade. Auto-update won’t move you to 5.0 on its own. To hide these warnings, pass --log-level silent on the command line. A config file’s logLevel: silent hides most of them, but not the warnings about commands and flags.

What’s coming

Today on 4.x	On 5.0
A failed spec exits `0` unless you pass `--exit-on-fail`	A failed spec exits `1`
A run that tests nothing exits `0`	A run that tests nothing exits `2`
`--output` and `output` accept a folder	They name the JSON results file, and a folder needs `--output-dir`
`install-agents`	Removed. Use `install agents`
`-a` and `-s` on `install agents`	Removed. Use `--agent` and `--scope`
`install --silent`	Removed. Use `--quiet`
`--concurrent-runners` with no value	Needs a value. Use `--concurrent-runners true`
The `doc-detective-lsp` bin	Removed. Use `doc-detective lsp --stdio`
The `doc-detective-runner` bin	Replaced by a `doc-detective runner` command
`-r terminal html`	Takes one comma-separated value, like `-r terminal,html`, which 4.x doesn’t read. Until you upgrade, set `reporters` in your config
`-t` or `-s` given twice, which 4.x ignores	A usage error. Use one comma-separated value, like `-t a,b`
A `config` object in the `DOC_DETECTIVE` env var	Deprecated, and it merges below `DOC_DETECTIVE_CONFIG` and flags. Use `DOC_DETECTIVE_CONFIG`
A `container` key in the `DOC_DETECTIVE` env var of your own Docker image allows unsafe steps	It doesn’t. Use `allowUnsafeSteps: true`. The official images handle this for you
Each boolean `DOC_DETECTIVE_*` env var reads values its own way	All of them read `1`, `true`, `yes`, or `on` as on, and `0`, `false`, `no`, `off`, or empty as off
Browsers load from a `browser-snapshots` folder if one exists	Doc Detective ignores that folder, and browsers install into `<cacheDir>/browsers`
`beforeAny`	Renamed `beforeAll`. `beforeAny` still works, with a warning
`reporters` names in any case, like `JSON`	Exits `2`. Use `terminal`, `json`, `html`, `runFolder`, `junit`, or `markdown`
`stop: "spec"`, `stop: "run"`, or `goToTest` in a step’s routing, and `stop: "run"`, `retry`, or `goToStep` in a test’s	Exits `2`
`"click": true` clicks the text `true`	Exits `2`. Use `"click": "true"` for that text. If you don’t want a click, remove the step
`browser: "edge"` on a surface, and a device’s `orientation`, `udid`, and `provider`	Removed
`timeout: 0` on `runShell`, `runCode`, `goTo`, `httpRequest`, or a `startSurface` process or app, and negative durations, delays, and timeouts anywhere	Exits `2`. Locator and wait timeouts can still be `0`
`screenshot: false` takes a screenshot	Skips the step. Use `screenshot: true` for a screenshot
`find.click` set to text, or to an object with keys other than `button` and `duration`	Exits `2`
A locator such as `selector` inside `find.type`	Exits `2`. Use a separate `type` step
A `goTo` or `httpRequest` URL that starts with a `$VAR`, like `$URL/docs`	Exits `2`. A URL starts with `http://`, `https://`, or `/`, or is a whole `$VAR`
A `saveCookie` or `loadCookie` path with a `/` that doesn’t end in `.txt`	Exits `2`
An app’s `workingDirectory: "."`	Fails the step

Logs also move to stderr, so stdout carries only results.

Try it now

Add --exit-on-fail to your 4.x runs to get the new exit code for failed specs:

npx doc-detective --exit-on-fail

To keep exit code 0 after you upgrade, set --no-exit-on-fail, or exitOnFail: false in your config. Either one also works today, and it silences the warnings about exit codes.

The other replacements in the table that say “use” already work on 4.x, except --output-dir, which arrives with 5.0.

What’s next

A full migration guide replaces this page when 5.0 ships. For how exit codes work today, see Reporters and artifacts.