doc-detective 2.9.0-dev.0 → 2.9.0-dev.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -36
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -20,10 +20,6 @@ Doc Detective has multiple components to integrate with your workflows as you ne
|
|
|
20
20
|
|
|
21
21
|
## Install
|
|
22
22
|
|
|
23
|
-
> 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](https://doc-detective.com).
|
|
24
|
-
|
|
25
|
-
You can run Doc Detective as a CLI tool with Node:
|
|
26
|
-
|
|
27
23
|
0. Install prerequisites:
|
|
28
24
|
|
|
29
25
|
- [Node.js](https://nodejs.org/) (tested on v18 and v20)
|
|
@@ -39,71 +35,78 @@ You can run Doc Detective as a CLI tool with Node:
|
|
|
39
35
|
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:
|
|
40
36
|
|
|
41
37
|
```bash
|
|
42
|
-
|
|
38
|
+
npx doc-detective runTests --input ./samples/doc-content-inline-tests.md
|
|
43
39
|
```
|
|
44
40
|
|
|
45
41
|
To customize your test, file type, and directory options, create a [`config.json`](https://doc-detective.com/reference/schemas/config.html) file and reference it with the `--config` argument.
|
|
46
42
|
|
|
47
43
|
```bash
|
|
48
|
-
|
|
44
|
+
npx doc-detective runTests --config ./samples/config.json
|
|
49
45
|
```
|
|
50
46
|
|
|
51
47
|
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:
|
|
52
48
|
|
|
53
49
|
```bash
|
|
54
|
-
|
|
50
|
+
npx doc-detective runTests --config ./samples/config.json --input ./samples/tests.spec.json
|
|
55
51
|
```
|
|
56
52
|
|
|
57
53
|
To see all available options, use the `--help` argument:
|
|
58
54
|
|
|
59
55
|
```bash
|
|
60
|
-
|
|
56
|
+
npx doc-detective runTests --help
|
|
61
57
|
```
|
|
62
58
|
|
|
59
|
+
**Note**: If you clone this repo and run the `runTests` command, use `npm run runTests --` instead of `npx doc-detective runTests`.
|
|
60
|
+
|
|
63
61
|
## Check your test coverage
|
|
64
62
|
|
|
65
63
|
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`](https://doc-detective.com/reference/schemas/config.html) file accordingly.
|
|
66
64
|
|
|
67
|
-
|
|
68
65
|
```bash
|
|
69
|
-
|
|
66
|
+
npx doc-detective runCoverage --config ./samples/config.json --input ./samples/doc-content.md
|
|
70
67
|
```
|
|
71
68
|
|
|
72
69
|
To see all available options, use the `--help` argument:
|
|
73
70
|
|
|
74
71
|
```bash
|
|
75
|
-
|
|
72
|
+
npx doc-detective runCoverage --help
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Run locally
|
|
76
|
+
|
|
77
|
+
To run Doc Detective locally, clone the repo and install dependencies:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
git clone https://github.com/doc-detective/doc-detective.git
|
|
81
|
+
cd doc-detective
|
|
82
|
+
npm i
|
|
76
83
|
```
|
|
77
84
|
|
|
78
|
-
|
|
85
|
+
To run commands, use the `npm run` scripts:
|
|
79
86
|
|
|
80
|
-
|
|
87
|
+
```bash
|
|
88
|
+
npm run runTests -- --input ./samples/doc-content-inline-tests.md
|
|
89
|
+
npm run runCoverage -- --input ./samples/doc-content.md
|
|
90
|
+
```
|
|
81
91
|
|
|
82
92
|
## Concepts
|
|
83
93
|
|
|
84
|
-
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
-
|
|
99
|
-
|
|
100
|
-
## Roadmap
|
|
101
|
-
|
|
102
|
-
Future updates may include support for the following items:
|
|
103
|
-
|
|
104
|
-
- Apps: iOS Safari, Android Chrome, native Windows, native macOS, native Linux
|
|
105
|
-
- Platforms: iOS, Android
|
|
106
|
-
- Commands: `suggestTests` stable release
|
|
94
|
+
- [**Test specification**](https://doc-detective.com/reference/schemas/specification.html): A group of tests to run in one or more contexts. Conceptually parallel to a document.
|
|
95
|
+
- [**Test**](https://doc-detective.com/reference/schemas/test.html): A sequence of steps to perform. Conceptually parallel to a procedure.
|
|
96
|
+
- **Step**: A portion of a test that includes a single action. Conceptually parallel to a step in a procedure.
|
|
97
|
+
- **Action**: The task a performed in a step. Doc Detective supports a variety of actions:
|
|
98
|
+
- [**checkLink**](https://doc-detective.com/reference/schemas/checkLink.html): Check if a URL returns an acceptable status code from a GET request.
|
|
99
|
+
- [**find**](https://doc-detective.com/reference/schemas/find.html): Check if an element exists with the specified selector.
|
|
100
|
+
- [**goTo**](https://doc-detective.com/reference/schemas/goTo.html): Navigate to a specified URL.
|
|
101
|
+
- [**httpRequest**](https://doc-detective.com/reference/schemas/httpRequest.html): Perform a generic HTTP request, for example to an API.
|
|
102
|
+
- [**runShell**](https://doc-detective.com/reference/schemas/runShell.html): Perform a native shell command.
|
|
103
|
+
- [**saveScreenshot**](https://doc-detective.com/reference/schemas/saveScreenshot.html): Take a screenshot in PNG format.
|
|
104
|
+
- [**setVariables**](https://doc-detective.com/reference/schemas/setVariables.html): Load environment variables from a `.env` file.
|
|
105
|
+
- [**startRecording**](https://doc-detective.com/reference/schemas/startRecording.html) and [**stopRecording**](https://doc-detective.com/reference/schemas/stopRecording.html): Capture a video of test execution.
|
|
106
|
+
- [**typeKeys**](https://doc-detective.com/reference/schemas/typeKeys.html): 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$`.
|
|
107
|
+
- [**wait**](https://doc-detective.com/reference/schemas/wait.html): Pause before performing the next action.
|
|
108
|
+
- [**Context**](https://doc-detective.com/reference/schemas/context.html): An application and platforms that support the tests.
|
|
109
|
+
|
|
107
110
|
## License
|
|
108
111
|
|
|
109
112
|
This project uses the [MIT license](https://github.com/doc-detective/doc-detective/blob/master/LICENSE).
|