> 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.

# Installation

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

1. Install prerequisites:

   * [Node.js](https://nodejs.org/) v22.22.0 or later on the v22 line, or v24 or later

2. In a terminal, install Doc Detective globally:

   ```bash
     npm i -g doc-detective
   ```

   > **Note**
   >
   > If you're working in a local copy of the `doc-detective` repository, you need to run `npm i` to install local dependencies.

   > **Tip**
   >
   > 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.

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

   ```json title={"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"
           }
         ]
       }
     ]
   }

   ```

4. Run a test, pointing to the file you just created:

   ```bash
     npx doc-detective --input sample.spec.json
   ```

#### Docker

1. Install prerequisites:

   * [Docker](https://docs.docker.com/get-docker/)

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

   ```json title={"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"
           }
         ]
       }
     ]
   }

   ```

3. Run a test, pointing to the file you just created:

   ```bash
     docker run -v .:/app docdetective/docdetective --input /app/sample.spec.json
   ```

   > **Note**
   >
   > The `-v` argument mounts your current directory (`.`) to `/app` in the container. That gives Doc Detective access to your test specification, and lets it output results and screenshots. Keep it.
   >
   > An HTTPS `--input` URL removes the need for the mount to *read* the specification, but not the need to mount at all. Results and screenshots still default to the container's working directory, `/app`. Without the mount, the results file and the *example.png* this test captures are discarded when the container exits. Drop `-v` only when you don't need those files on the host.

You've run your first test with Doc Detective. :tada:

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`):

```bash
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:

```bash
doc-detective install all --yes
```

### Install specific components

Install only what your tests need:

```bash
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:

```bash
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:

```bash
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](/docs/get-started/concepts) native to Doc Detective. You can also work through the guided walkthroughs in [Test your docs](/docs/test-docs/overview), or explore how to write [tests](/docs/get-started/how-testing-works) and [actions](/docs/get-started/how-testing-works).