> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.doc-detective.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server. # Prepare for Doc Detective 5.0 > What's changing in Doc Detective 5.0, and how to try the new behavior on 4.x today. 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 `/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: ```bash 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](/docs/ci/reporters-and-artifacts).