Skip to main content

Get started

Downloading and running Doc Detective is straightforward. Follow these steps to 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 https://doc-detective.com/sample.spec.json

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 https://github.com/doc-detective/doc-detective.git
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 doc-content-inline-tests.md, run the following command:

npx doc-detective runTests --input doc-content-inline-tests.md

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 https://doc-detective.com/sample.spec.json, run the following command:

npx doc-detective runTests --input https://doc-detective.com/sample.spec.json

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 doc-content.md

Concepts​

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.

Resources​

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

  • The Schemas include 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.