config
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 <output>/.doc-detective/runs/<runId>/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) | 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)), object(File type (executable)) | Optional. Configuration for file types and their markup detection. | ["markdown","asciidoc","html","dita"] |
| integrations | object(Integrations options) | Optional. Options for connecting to external services. | — |
| telemetry | object(Telemetry options) | Optional. Options around sending telemetry for Doc Detective usage. | {"send":true} |
| hints | object(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) | 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 (<output>/.doc-detective/runs/<runId>/) under the nested resource tree, with each image named by the step’s order, action, and ID (for example, specs/<specId>/tests/<testId>/contexts/<contextId>/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) | 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 (<output>/.doc-detective/runs/<runId>/) under the nested resource tree (for example, specs/<specId>/tests/<testId>/contexts/<contextId>/recordings/<contextId>.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
{}
{"shell": "powershell"}
{"input": ".","output": ".","recursive": true,"loadVariables": ".env","fileTypes": ["markdown"],"reporters": ["terminal","json","html"]}
{"origin": "https://my-app.com","originParams": {"__clerk_testing_token": "$CLERK_TESTING_TOKEN"}}
{"fileTypes": [{"extends": "markdown","extensions": ["md","markdown","mdx"],"inlineStatements": {"testStart": "<!--\\s*testStart\\s*(.*?)\\s*-->","testEnd": "<!-- testEnd -->","ignoreStart": "<!-- ignoreStart -->","ignoreEnd": "<!-- ignoreEnd -->","step": "<!--\\s*step\\s*(.*?)\\s*-->"},"markup": [{"name": "onscreenText","regex": "\\*\\*.+?\\*\\*","actions": "find"}]}]}
{"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"}}]}
{"environment": {"platform": "windows","arch": "x64"}}
{"concurrentRunners": 1}
{"concurrentRunners": true}
{"concurrentRunners": 4}
{"debug": false}
{"integrations": {"docDetectiveApi": {"apiKey": "your-api-key-here"}}}
{"crawl": true}
{"processDitaMaps": true}
{"integrations": {"heretto": [{"name": "example","organizationId": "your-organization-id","username": "your-username","apiToken": "your-api-token"}]}}
{"testFilter": ["smoke","login"],"specFilter": ["auth"]}
{"autoScreenshot": true,"output": "./test-results"}
{"input": ".","annotationDefaults": {"color": "#E11D48","strokeWidth": 3,"badge": {"background": "#E11D48","color": "#FFFFFF"}}}