Installation | Doc Detective

Downloading and running Doc Detective is straightforward. You can install Doc Detective using NPX (Node.js) or Docker. Follow the instructions for your preferred method:

Choose NPX if you have Node.js installed and want Doc Detective on your machine locally. Choose Docker if you can’t install applications locally or prefer containerized environments. It also suits you if you need to avoid a Node.js install, or want to isolate Doc Detective from your system.

NPX

Docker

Install prerequisites:
- Node.js v22.22.0 or later on the v22 line, or v24 or later
In a terminal, install Doc Detective globally:
```
  npm i -g doc-detective
```
If you’re working in a local copy of the doc-detective repository, you need to run npm i to install local dependencies.

To try pre-release features, install from the @next dist-tag: npm i -g doc-detective@next. For stable releases, use the default command above.

Save this file to your current directory as sample.spec.json:

sample.spec.json

{
  "tests": [
    {
      "steps": [
        {
          "description": "Go to the specified URL",
          "goTo": "https://example.com"
        },
        {
          "description": "Verify the presence of the main heading",
          "find": "Example Domain"
        },
        {
          "description": "Verify that the 'Learn more' link is present and working",
          "click": "Learn more"
        },
        {
          "description": "Capture a screenshot of the resulting page",
          "screenshot": "example.png"
        }
      ]
    }
  ]
}

Run a test, pointing to the file you just created:
```
  npx doc-detective --input sample.spec.json
```

You’ve run your first test with Doc Detective. 🎉

You should see output in the terminal indicating the progress and results of the test. Results are also saved in a testResults-<timestamp>.json file in the current directory (configurable with the --output option), and this test saves a screenshot to example.png.

Runtime installation

Running npm i doc-detective installs the CLI and pre-installs heavy runtime assets. Those are browsers (Chrome, Firefox), drivers (ChromeDriver, Geckodriver), ffmpeg, and the npm packages that drive them, such as webdriverio, appium, and sharp. They land in ~/.doc-detective/, or DOC_DETECTIVE_CACHE_DIR. This keeps your install ready to run tests without a separate step.

The pre-install runs in a child process and captures its output, so npm’s deprecation warnings from transitive dependencies won’t clutter your terminal.

Opt out of pre-installation

To skip the heavy asset pre-install, set DOC_DETECTIVE_AUTOINSTALL=0 (also accepts false, no, or off):

DOC_DETECTIVE_AUTOINSTALL=0 npm i doc-detective

With this option, the CLI install stays small. Heavy assets install lazily the first time a test needs them.

Pre-install manually

If you opted out or need to reinstall, pre-install all runtime assets:

doc-detective install all --yes

Install specific components

Install only what your tests need:

doc-detective install browsers chrome chromedriver
doc-detective install runtime webdriverio appium
doc-detective install agents

Check installation status

See what’s installed versus what the current version expects:

doc-detective install status

Override the cache location

The default cache location is ~/.doc-detective/, which persists across reboots. For containers, shared CI caches, or any environment where the cache belongs somewhere else, set a custom location:

DOC_DETECTIVE_CACHE_DIR=/opt/doc-detective doc-detective install all --yes

You can also set cacheDir in your .doc-detective.json config file or use the --cache-dir CLI flag.

Auto-update

By default, Doc Detective checks the npm registry on startup and updates itself when a newer version is available:

Global installs (npm i -g doc-detective): Runs npm install -g doc-detective@<latest> and re-executes.
npx invocations: Re-executes with npx -y doc-detective@latest.
Local project installs: Prints an “update available” message instead of modifying your package.json.

To disable auto-update, use any of these methods:

Pass --no-auto-update on the CLI
Set autoUpdate: false in your .doc-detective.json config file
Set the DOC_DETECTIVE_SKIP_AUTO_UPDATE=1 environment variable

CI environments skip the update check automatically whenever the CI environment variable has a value.

Next steps

Next up, take a look at the concepts native to Doc Detective. You can also work through the guided walkthroughs in Test your docs, or explore how to write tests and actions.