Doc Detective: The Documentation Testing Framework
Doc Detective is doc content testing framework that makes it easy to keep your docs accurate and up-to-date. You write tests, and Doc Detective runs them directly against your product to make sure your docs match your user experience. Whether it’s a UI-based process or a series of API calls, Doc Detective can help you find doc bugs before your users do.
Doc Detective ingests test specifications and text files, parses them for testable actions, then executes those actions in a browser. The results (PASS/FAIL and context) are output as a JSON object so that other pieces of infrastructure can parse and manipulate them as needed.
This project handles test parsing and web-based UI testing---it doesn't support results reporting or notifications. This framework is a part of testing infrastructures and needs to be complemented by other components.
Components
Doc Detective has multiple components to integrate with your workflows as you need it to:
- Doc Detective (this repo): A standalone tool that enables testing without a separate Node project.
- Doc Detective Core: An NPM package that provides the testing functionality.
- Doc Detective Docs: Source files for doc-detective.com.
Install
- Install prerequisites:
- In a terminal, install Doc Detective globally:
npm i -g doc-detectiveIf you don't install Doc Detective globally, you'll be prompted to install the first time you run an npx command.
Note: If you're working in a cloned doc-detective repository, run npm i to install local dependencies or the npx command in the next step will fail.
Lazy-installed runtime
npm i doc-detective installs the CLI, then pre-installs the heavy runtime assets at postinstall. Those are browsers (Chrome, Firefox), drivers (ChromeDriver, Geckodriver), ffmpeg, and the npm packages that drive them. That last group includes webdriverio, appium, and sharp. They land in DOC_DETECTIVE_CACHE_DIR. This keeps a fresh install ready to run without a separate step, as it does any Docker image built FROM it. The pre-install runs in a child process whose output is captured. npm's deprecation warnings from the heavy transitive trees therefore never reach your terminal.
Opt out of the heavy pre-install by setting DOC_DETECTIVE_AUTOINSTALL=0, which also accepts false, no, and off. The CLI install then stays small, with no browser download and no heavy npm packages. The heavy assets install lazily the first time a test needs them, or up front through doc-detective install all.
Either way, the published package declares the heavy packages in neither dependencies nor optionalDependencies. npm itself therefore never fetches them as part of the dependency tree. In the source repo they live under optionalDependencies, and the publish step rewrites them into a custom ddRuntimeDependencies field. The resolver reads that field's version constraints when it installs each dep into the cache, whether at postinstall or on first use.
- Pre-install everything up front:
doc-detective install all --yes- Install only what you need:
doc-detective install browsers chrome
doc-detective install runtime webdriverio appium
doc-detective install agents- Inspect what's installed vs. expected:
doc-detective install status- Override the cache location (useful in containers and CI):
DOC_DETECTIVE_CACHE_DIR=/opt/doc-detective doc-detective install all --yesAuto-update
By default, doc-detective checks the npm registry on startup and self-updates if a newer release is available. Global installs run npm install -g, and npx invocations re-exec through npx -y doc-detective@latest. Local project installs print an "update available" hint instead of mutating your package.json. To opt out:
--no-auto-updateon the CLIautoUpdate: falsein.doc-detective.jsonDOC_DETECTIVE_SKIP_AUTO_UPDATE=1in the environment
process.env.CI is set) skip the check automatically.
Run tests
To run your tests, use the following command:
npx doc-detectiveBy 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 --input doc-content-inline-tests.mdTo 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 --config .doc-detective.jsonNote: 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 --config .doc-detective.json --input tests.spec.jsonCheck out some samples
You can find test and config samples in the samples directory.
Concepts
- 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 a performed in a step. Doc Detective supports a variety of actions:
.env file.
- record and stopRecord: Capture a video of test execution.
- type: 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.
- Context: A combination of platform and application to run tests on.
Develop
To develop Doc Detective, clone the repo and install dependencies:
git clone https://github.com/doc-detective/doc-detective.git
cd doc-detective
npm iTo run commands, use the same npx commands as above.
Make sure you review the contributions guide before submitting a pull request.
Contributions
Looking to help out? See our contributions guide for more info. If you can't contribute code, you can still help by reporting issues, suggesting new features, improving the documentation, or sponsoring the project.
License
This project uses the AGPL-3.0 license.