> 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. # config > Configuration options for Doc Detective operations. Configuration options for Doc Detective operations. ## Fields | Field | Type | Description | Default | | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | | \$schema | string | Optional. JSON Schema for this object. Accepted values: `https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/config_v3.schema.json` | — | | configId | string | Optional. Identifier for the configuration. | — | | configPath | string | ReadOnly. Path to the configuration file. | — | | input | one of: - string - array of string | Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | `.` | | output | string | Optional. Path of the directory in which to store the output of Doc Detective commands. If a file path is specified, Doc Detective attempts to honor the file name specified, but file path behavior is controlled by the configured reporters. | `.` | | reporters | array of string | Optional. Reporters to use when emitting test results. Built-in reporters: `terminal`, `json`, `html`, `runFolder`, `junit` (JUnit XML for CI test-summary widgets, written as `junit.xml` in the output directory, or beside `output` when it names a file), `markdown` (a run summary for CI job summaries and merge request comments, written as `doc-detective-summary.md` in the output directory, or beside `output` when it names a file). The `runFolder` reporter (on by default) archives each run's results as `/.doc-detective/runs//testResults.json` (or `coverageResults.json` for coverage runs), beside any screenshots the run captured, in addition to the flat output the `json` reporter writes. You can also reference custom reporters registered via `registerReporter()` by name. | `["terminal","json","runFolder"]` | | specFilter | array of string | Optional. Regex patterns (case-insensitive) applied to each spec's `specId`. If set, only specs whose `specId` matches at least one pattern are run. Equivalent to `--spec` on the CLI. Each entry must contain at least one non-whitespace character. | — | | testFilter | array of string | Optional. Regex patterns (case-insensitive) applied to each test's `testId`. If set, only tests whose `testId` matches at least one pattern are run. Equivalent to `--test` on the CLI. Each entry must contain at least one non-whitespace character. | — | | recursive | boolean | Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | `true` | | relativePathBase | string | Optional. Whether paths should be interpreted as relative to the current working directory (`cwd`) or to the file in which they're specified (`file`). Accepted values: `cwd`, `file` | `file` | | loadVariables | string | Optional. Load environment variables from the specified `.env` file. | — | | origin | string | Optional. Default protocol and domain to use for relative URLs. | — | | originParams | object | Optional. Query parameters to append to URLs resolved against `origin`. Values support environment variable substitution via `$VAR` syntax. Step-level `params` on `goTo` / `checkLink` are merged on top of these, with step keys winning on collision. WARNING: values are embedded in request URLs and appear verbatim in test results, logs, and reports — avoid putting long-lived secrets here. | `{}` | | beforeAny | one of: - string - array of string | Optional. Path(s) to test specifications to perform before those specified by `input`. Useful for setting up testing environments. | — | | afterAll | one of: - string - array of string | Optional. Path(s) to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. | — | | detectSteps | boolean | Optional. Whether or not to detect steps in input files based on defined markup. | `true` | | allowUnsafeSteps | boolean | Optional. Whether or not to run potentially unsafe steps, such as those that might modify files or system state. | — | | crawl | boolean | Optional. If `true`, crawls sitemap.xml files specified by URL to find additional files to test. | `false` | | processDitaMaps | boolean | Optional. If `true`, processes DITA maps and includes generated files as inputs. | `true` | | logLevel | string | Optional. Amount of detail to output when performing an operation. Accepted values: `silent`, `error`, `warning`, `info`, `debug` | `info` | | runOn | array of object([context](/reference/schemas/context)) | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | — | | fileTypes | array of one of: string, object([File type (custom)](/reference/schemas/file-type-custom)), object([File type (executable)](/reference/schemas/file-type-executable)) | Optional. Configuration for file types and their markup detection. | `["markdown","asciidoc","html","dita"]` | | integrations | object([Integrations options](/reference/schemas/integrations-options)) | Optional. Options for connecting to external services. | — | | telemetry | object([Telemetry options](/reference/schemas/telemetry-options)) | Optional. Options around sending telemetry for Doc Detective usage. | `{"send":true}` | | hints | object([Hints options](/reference/schemas/hints-options)) | Optional. Options for the post-run hints feature. After a test run, Doc Detective may print one short, contextual hint with code samples and links to encourage further engagement (for example, suggesting a CI workflow when none is detected). Doc Detective displays hints only in an interactive terminal (TTY) and only at the default `info` log level. | `{"enabled":true}` | | concurrentRunners | integer,boolean | Optional. Number of concurrent test runners. Set to true to use CPU core count (capped at 4). Minimum: 1 | `1` | | environment | object([Environment details](/reference/schemas/environment-details)) | ReadOnly. Environment information for the system running Doc Detective. | — | | debug | one of: - boolean - string | Deprecated and ignored. Previously reserved for an interactive step-through debugger that was never implemented. Retained so existing configs continue to validate. For diagnostics, run `doc-detective debug` or set the `DOC_DETECTIVE_DEBUG` environment variable. | — | | dryRun | boolean | Optional. If `true`, fully resolve tests (file/env config merge, schema validation, file detection, inline-test extraction) and emit the resolved test plan as JSON, but do not execute any steps. Equivalent to `--dry-run` on the CLI. | `false` | | autoScreenshot | boolean | Optional. If `true`, captures a screenshot after every browser-driven step that does not already define an explicit `screenshot`. Steps with an explicit `screenshot` are skipped for auto-capture since they already produce an image. Doc Detective saves images in the per-run artifact directory (`/.doc-detective/runs//`) under the nested resource tree, with each image named by the step's order, action, and ID (for example, `specs//tests//contexts//screenshots/01-goTo-s4f2a91c.png`), so the same step lands on the same relative path in every run's folder for run-over-run comparison. Specs and tests can override this value with their own `autoScreenshot` fields (test level wins over spec level, which wins over config level). Equivalent to `--auto-screenshot` on the CLI. | `false` | | annotationDefaults | object([Annotation defaults](/reference/schemas/annotation-defaults)) | Optional. Default visual theme for screenshot and recording annotations. Specs and tests can override this value with their own `annotationDefaults` fields (test level wins over spec level, which wins over config level), and an individual annotation's `style` wins over all of them. Fields left unset fall back to Doc Detective's built-in theme. Setting a theme here keeps every annotated image in a doc set visually consistent. | — | | autoRecord | boolean | Optional. If `true`, records a video of every test context that runs in a browser, in addition to any explicit `record` steps. The recording wraps the whole context (it starts before the first step and stops after the last) and always uses the `ffmpeg` engine. Videos are saved in the per-run artifact directory (`/.doc-detective/runs//`) under the nested resource tree (for example, `specs//tests//contexts//recordings/.mp4`), so the same context lands on the same relative path in every run's folder for run-over-run comparison. Specs and tests can override this value with their own `autoRecord` fields (test level wins over spec level, which wins over config level). Equivalent to `--auto-record` on the CLI. | `false` | | autoUpdate | boolean | Optional. If `true` (default), the CLI checks for a newer published `doc-detective` on startup and self-updates before running tests. Updates happen for global (`npm i -g`) and `npx` installs only — local installs (where `doc-detective` is a project dep) get an informational message instead, since auto-updating would mutate the user's lockfile. CI environments and the `DOC_DETECTIVE_SKIP_AUTO_UPDATE=1` env var also skip the check. Set to `false` to pin to the installed version. Equivalent to `--no-auto-update` on the CLI. | `true` | | exitOnFail | boolean | Optional. If `true`, the CLI exits with a non-zero code (`1`) when any spec's result is `FAIL`, so a documentation-testing job fails the build the way a broken unit test would. Defaults to `false`, which preserves the CLI's historical behavior of exiting `0` on test failures (it exits non-zero only on a crash or invalid config) — the exit-on-fail decision has historically lived in CI wrappers like the Doc Detective GitHub Action. `WARNING` results are non-fatal and never trigger a non-zero exit. Equivalent to `--exit-on-fail` on the CLI. | `false` | | shell | string | Optional. Default shell for `runShell` steps (and `runCode`'s shell-based execution). `runShell` steps can override this value with their own `shell` field. `cmd` and `powershell` are only supported on Windows. On Windows, `bash` resolves to Git Bash, which Doc Detective installs automatically if it isn't present. Accepted values: `bash`, `cmd`, `powershell` | `bash` | | cacheDir | string | Optional. Directory for lazy-installed runtime assets (heavy npm packages, browser binaries, ffmpeg). Defaults to `~/.doc-detective/` (the user's home directory). Override here, with the `DOC_DETECTIVE_CACHE_DIR` env var, or with `--cache-dir` on the CLI to share one cache across users or place it on another volume. Minimum length: 1. Pattern: `\S` | — | | browserFallback | string | Optional. Controls whether a context whose browser cannot start a driver session falls back to another available browser instead of being skipped. Drivers are validated by execution (not just presence) so a present-but-broken driver — for example a partially downloaded geckodriver — no longer silently skips Firefox coverage. `auto` (default): fall back to any other available browser for both auto-selected and explicitly requested browsers; a fallback away from an explicitly requested browser reports the context as `WARNING` rather than `PASS`. `explicit`: fall back only when the browser was auto-selected; an explicitly requested browser whose driver is broken is skipped with a diagnostic reason. `off`: never fall back across browsers (driver validation and diagnostic skip reasons still apply). Equivalent to `--browser-fallback` on the CLI. Accepted values: `auto`, `explicit`, `off` | `auto` | | retries | integer | Optional. How many times to re-run a whole test context on a fresh session when the session it was running against turns out to be unusable — an early step (like `goTo`) passes, then a later step fails because the session or page is gone. After any failing context, an active probe checks the session and retries only when it finds one of three unambiguous signs: the session is dead (WebDriver `ECONNREFUSED` / `invalid session id`), it is alive but sitting on a browser crash or error page (`chrome-error:`, `about:neterror`), or it is alive but never left its initial blank document, meaning the context never actually got started. A page a test could legitimately be on is never treated as a retry signal, so a real assertion failure (the session is alive, the page loaded, the element genuinely isn't there) always fails and is never retried. Defaults to `1`; set to `0` to disable and keep the exact single-attempt behavior. Contexts can override this with their own `retries` field. This is distinct from a step's `retry` route, which re-runs a single step on the *same* session — `retries` re-runs the *whole context* on a *new* session. Capped at `10` to prevent a runaway retry storm from a misconfiguration. Minimum: 0. Maximum: 10 | `1` | ## Examples ```json {} ``` ```json { "shell": "powershell" } ``` ```json { "input": ".", "output": ".", "recursive": true, "loadVariables": ".env", "fileTypes": [ "markdown" ], "reporters": [ "terminal", "json", "html" ] } ``` ```json { "origin": "https://my-app.com", "originParams": { "__clerk_testing_token": "$CLERK_TESTING_TOKEN" } } ``` ```json { "fileTypes": [ { "extends": "markdown", "extensions": [ "md", "markdown", "mdx" ], "inlineStatements": { "testStart": "", "testEnd": "", "ignoreStart": "", "ignoreEnd": "", "step": "" }, "markup": [ { "name": "onscreenText", "regex": "\\*\\*.+?\\*\\*", "actions": "find" } ] } ] } ``` ```json { "fileTypes": [ { "name": "Jupyter Notebooks", "extensions": "ipynb", "runShell": { "command": "jupyter", "args": [ "nbconvert", "--to", "script", "--execute", "$1", "--stdout" ] } }, { "name": "JavaScript", "extensions": "js", "runShell": { "command": "node $1" } }, { "name": "Python", "extensions": "py", "runShell": { "command": "python $1" } } ] } ``` ```json { "environment": { "platform": "windows", "arch": "x64" } } ``` ```json { "concurrentRunners": 1 } ``` ```json { "concurrentRunners": true } ``` ```json { "concurrentRunners": 4 } ``` ```json { "debug": false } ``` ```json { "integrations": { "docDetectiveApi": { "apiKey": "your-api-key-here" } } } ``` ```json { "crawl": true } ``` ```json { "processDitaMaps": true } ``` ```json { "integrations": { "heretto": [ { "name": "example", "organizationId": "your-organization-id", "username": "your-username", "apiToken": "your-api-token" } ] } } ``` ```json { "testFilter": [ "smoke", "login" ], "specFilter": [ "auth" ] } ``` ```json { "autoScreenshot": true, "output": "./test-results" } ``` ```json { "input": ".", "annotationDefaults": { "color": "#E11D48", "strokeWidth": 3, "badge": { "background": "#E11D48", "color": "#FFFFFF" } } } ```