2.10.1 • Published 3 days ago

doc-detective v2.10.1

Weekly downloads
-
License
MIT
Repository
github
Last release
3 days ago

Doc Detective: The Documentation Testing Framework

Current version Discord Shield Docs Shield

Doc Detective is an open-source documentation testing framework that makes it easy to keep your docs accurate and up-to-date. You write low-code (soon no-code) 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:

Install

The following sections cover running Doc Detective as a CLI tool. To use Doc Detective via another interface (like as an NPM package), see the docs.

You can run Doc Detective as a CLI tool with Node:

  1. Install prerequisites:

  2. In a terminal, clone the repo and install dependencies:

    git clone https://github.com/doc-detective/doc-detective.git
    cd doc-detective
    npm install

Run tests

To run your tests, use the runTests command and specify your test file with the --input argument. For example, to run tests in a file named doc-content.md in the samples directory (like in this repo!), run the following command:

npm run runTests -- --input ./samples/doc-content.md

To customize your test, file type, and directory options, create a config.json file and reference it with the --config argument.

npm run runTests -- --config ./samples/config.json

You can override config.json options with command-line arguments. For example, to run tests in a file named tests.spec.json in the samples directory, run the following command:

npm run runTests -- --config ./samples/config.json --input ./samples/tests.spec.json

To see all available options, use the --help argument:

npm run runTests -- --help

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.json file accordingly.

npm run runCoverage -- --config ./samples/config.json --input ./samples/doc-content.md

To see all available options, use the --help argument:

npm run runCoverage -- --help

Suggest tests for coverage gaps (Experimental)

The suggestTests command provides experimental support for suggesting tests for coverage gaps identifying during test coverage analysis. However, the suggestTests command is highly experimental, so usage of the command is left as an exercise for the user.

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:
    • checkLink: Check if a URL returns an acceptable status code from a GET request.
    • find: Check if an element exists with the specified selector.
    • goTo: Navigate to a specified URL.
    • httpRequest: Perform a generic HTTP request, for example to an API.
    • runShell: Perform a native shell command.
    • saveScreenshot: Take a screenshot in PNG format.
    • setVariables: Load environment variables from a .env file.
    • startRecording and stopRecording: Capture a video of test execution.
    • 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.
  • Context: An application and platforms that support the tests.

Roadmap

Future updates may include support for the following items:

  • Apps: iOS Safari, Android Chrome, native Windows, native macOS, native Linux
  • Platforms: iOS, Android
  • Commands: suggestTests stable release

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

2.10.1

3 days ago

2.10.0

9 days ago

2.9.3-dev.0

18 days ago

2.9.2

18 days ago

2.9.1

19 days ago

2.9.0-dev.0

20 days ago

2.9.0-dev.2

19 days ago

2.9.0-dev.1

20 days ago

2.9.0

20 days ago

2.0.0-beta.0

12 months ago

1.3.1

1 year ago

1.2.0

1 year ago

1.1.1

1 year ago

1.1.0

1 year ago

1.0.9

1 year ago

1.0.7

1 year ago

1.2.4

1 year ago

1.0.6

1 year ago

1.2.3

1 year ago

1.0.5

1 year ago

1.2.2

1 year ago

1.0.4

1 year ago

1.2.1

1 year ago

1.0.3

2 years ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago