Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Get started

Downloading and running Doc Detective is simple, but lets walk through it and run tests on a few sample files.

  1. Install prerequisites:

  2. In a terminal, install Doc Detective globally:

     npm i -g doc-detective
  3. Run a test:

     npx doc-detective runTests --input

Congratulations! You’ve run your first test with Doc Detective.

Get sample files

To get a few samples, view the samples on GitHub or clone the repo and navigate to the samples directory:

git clone
cd doc-detective/samples
npm i

Run tests

To run your tests, use the runTests command:

npx doc-detective runTests

By default, Doc Detective scans the current directory for valid tests, but you can specify your test file with the --input argument. For example, to run tests in a file named, run the following command:

npx doc-detective runTests --input

To customize your test, file type, and directory options, create a .doc-detective.json config file. If a .doc-detective.json file exists in the directory when you run the comment, Doc Detective loads the config. Otherwise, you can specify a config path with the --config argument.

npx doc-detective runTests --config .doc-detective.json

Note: All paths are relative to the current working directory, regardless where the config file is located.

You can override config options with command-line arguments. For example, to run tests in a file named tests.spec.json, even if that isn’t included in your config, run the following command:

npx doc-detective runTests --config .doc-detective.json --input tests.spec.json

Run remotely-hosted tests

You can run tests hosted remotely by specifying the URL of the test file with the --input argument. For example, to run tests from a file hosted at, run the following command:

npx doc-detective runTests --input

These tests run the same way as local tests, but Doc Detective fetches the test file from the specified URL and stores it in a temporary directory. The URL must be accessible to the machine running the tests.

Check your test coverage

You can check the test coverage of your documentation source files with the runCoverage command, specifying the source file or directory of source files with the --input argument. Doc Detective identifies potential areas of test coverage with file-format-specific regex, and supports CommonMark syntax natively. If you want to test coverage of a file with different syntax, update your the fileTypes object of your config file accordingly.

npx doc-detective runCoverage --config .doc-detective.json --input


For new users, here are some key concepts to understand:

  • Test specification: A group of tests to run in one or more contexts. Conceptually parallel to a document.
  • Test: A sequence of steps to perform. Conceptually parallel to a procedure.
  • Step: A portion of a test that includes a single action. Conceptually parallel to a step in a procedure.
  • Action: The task performed in a step. Doc Detective supports a variety of actions:
    • goTo: Navigate to a specified URL.
    • find: Locate and interact with an element on the page.
    • typeKeys: Type keys. To type special keys, begin and end the string with $ and use the special key’s enum. For example, to type the Escape key, enter $ESCAPE$.
    • wait: Pause before performing the next action.
    • saveScreenshot: Take a screenshot in PNG format.
    • setVariables: Load environment variables from a .env file.
    • startRecording and stopRecording: Capture a video of test execution.
    • checkLink: Check if a URL returns an acceptable status code from a GET request.
    • httpRequest: Perform a generic HTTP request, for example to an API.
    • runShell: Perform a native shell command.
  • Context: An application and platforms that support the tests.


There are a handful of resources to help you write and run tests:

  • The Action Builder prototype is an interactive tool to help you build test actions, using the same action definitions and validations as Doc Detective itself.
  • The Reference includes detailed information about the schemas and actions available in Doc Detective.
  • The Discord community is a great place to ask questions and get help from other users and the maintainers.
  • The Issue tracker is the best place to report bugs and request new features.
  • The Contribution guide includes information about how to contribute to the project.