doc-detective 2.13.0-dev.0 → 2.13.1

package/README.md

@@ -1,126 +1,126 @@
-# <img src="https://github.com/doc-detective/doc-detective/blob/main/icon.png" width=50 style="vertical-align:middle;margin-bottom:7px"/> Doc Detective: The Documentation Testing Framework
-
-![Current version](https://img.shields.io/github/package-json/v/doc-detective/doc-detective?color=orange)
-[![Discord Shield](https://img.shields.io/badge/chat-on%20discord-purple)](https://discord.gg/2M7wXEThfF)
-[![Docs Shield](https://img.shields.io/badge/docs-doc--detective.com-blue)](https://doc-detective.com)
-
-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](https://github.com/doc-detective/doc-detective-core): An NPM package that provides the testing functionality.
-- [Doc Detective Docs](https://github.com/doc-detective/doc-detective.github.io): Source files for [doc-detective.com](https://doc-detective.com).
-
-## Install
-
-1. Install prerequisites:
-
-   - [Node.js](https://nodejs.org/) (tested on v18 and v20)
-
-1. In a terminal, install Doc Detective globally:
-
-    ```bash
-    npm i -g doc-detective
-    ```
-
-    If you don't install Doc Detective globally, you'll be prompted to install the first time you run an `npx` command.
-
-## (Optional) Get sample files
-
-To test a few samples, clone the repo and navigate to the `samples` directory:
-
-```bash
-git clone https://github.com/doc-detective/doc-detective.git
-cd doc-detective/samples
-```
-
-## Run tests
-
-To run your tests, use the `runTests` command:
-
-```bash
-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:
-
-```bash
-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](https://doc-detective.com/reference/schemas/config.html) 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.
-
-```bash
-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:
-
-```bash
-npx doc-detective runTests --config .doc-detective.json --input tests.spec.json
-```
-
-## 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](https://doc-detective.com/reference/schemas/config.html) file accordingly.
-
-```bash
-npx doc-detective runCoverage --config .doc-detective.json --input doc-content.md
-```
-
-## Concepts
-
-- [**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.
-- [**Test**](https://doc-detective.com/reference/schemas/test.html): 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**](https://doc-detective.com/reference/schemas/checkLink.html): Check if a URL returns an acceptable status code from a GET request.
-  - [**find**](https://doc-detective.com/reference/schemas/find.html): Check if an element exists with the specified selector.
-  - [**goTo**](https://doc-detective.com/reference/schemas/goTo.html): Navigate to a specified URL.
-  - [**httpRequest**](https://doc-detective.com/reference/schemas/httpRequest.html): Perform a generic HTTP request, for example to an API.
-  - [**runShell**](https://doc-detective.com/reference/schemas/runShell.html): Perform a native shell command.
-  - [**saveScreenshot**](https://doc-detective.com/reference/schemas/saveScreenshot.html): Take a screenshot in PNG format.
-  - [**setVariables**](https://doc-detective.com/reference/schemas/setVariables.html): Load environment variables from a `.env` file.
-  - [**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.
-  - [**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$`.
-  - [**wait**](https://doc-detective.com/reference/schemas/wait.html): Pause before performing the next action.
-- [**Context**](https://doc-detective.com/reference/schemas/context.html): 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
-
-## Develop
-
-To develop Doc Detective, clone the repo and install dependencies:
-
-```bash
-git clone https://github.com/doc-detective/doc-detective.git
-cd doc-detective
-npm i
-```
-
-To run commands, use the same `npx` commands as above.
-
-Make sure you review the [contributions guide](CONTRIBUTIONS.md) before submitting a pull request.
-
-## Contributions
-
-Looking to help out? See our [contributions guide](CONTRIBUTIONS.md) 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](https://github.com/doc-detective/doc-detective/blob/master/LICENSE).
+# <img src="https://github.com/doc-detective/doc-detective/blob/main/icon.png" width=50 style="vertical-align:middle;margin-bottom:7px"/> Doc Detective: The Documentation Testing Framework
+
+![Current version](https://img.shields.io/github/package-json/v/doc-detective/doc-detective?color=orange)
+[![Discord Shield](https://img.shields.io/badge/chat-on%20discord-purple)](https://discord.gg/2M7wXEThfF)
+[![Docs Shield](https://img.shields.io/badge/docs-doc--detective.com-blue)](https://doc-detective.com)
+
+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](https://github.com/doc-detective/doc-detective-core): An NPM package that provides the testing functionality.
+- [Doc Detective Docs](https://github.com/doc-detective/doc-detective.github.io): Source files for [doc-detective.com](https://doc-detective.com).
+
+## Install
+
+1. Install prerequisites:
+
+   - [Node.js](https://nodejs.org/) (tested on v18 and v20)
+
+1. In a terminal, install Doc Detective globally:
+
+    ```bash
+    npm i -g doc-detective
+    ```
+
+    If you don't install Doc Detective globally, you'll be prompted to install the first time you run an `npx` command.
+
+## (Optional) Get sample files
+
+To test a few samples, clone the repo and navigate to the `samples` directory:
+
+```bash
+git clone https://github.com/doc-detective/doc-detective.git
+cd doc-detective/samples
+```
+
+## Run tests
+
+To run your tests, use the `runTests` command:
+
+```bash
+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:
+
+```bash
+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](https://doc-detective.com/reference/schemas/config.html) 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.
+
+```bash
+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:
+
+```bash
+npx doc-detective runTests --config .doc-detective.json --input tests.spec.json
+```
+
+## 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](https://doc-detective.com/reference/schemas/config.html) file accordingly.
+
+```bash
+npx doc-detective runCoverage --config .doc-detective.json --input doc-content.md
+```
+
+## Concepts
+
+- [**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.
+- [**Test**](https://doc-detective.com/reference/schemas/test.html): 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**](https://doc-detective.com/reference/schemas/checkLink.html): Check if a URL returns an acceptable status code from a GET request.
+  - [**find**](https://doc-detective.com/reference/schemas/find.html): Check if an element exists with the specified selector.
+  - [**goTo**](https://doc-detective.com/reference/schemas/goTo.html): Navigate to a specified URL.
+  - [**httpRequest**](https://doc-detective.com/reference/schemas/httpRequest.html): Perform a generic HTTP request, for example to an API.
+  - [**runShell**](https://doc-detective.com/reference/schemas/runShell.html): Perform a native shell command.
+  - [**saveScreenshot**](https://doc-detective.com/reference/schemas/saveScreenshot.html): Take a screenshot in PNG format.
+  - [**setVariables**](https://doc-detective.com/reference/schemas/setVariables.html): Load environment variables from a `.env` file.
+  - [**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.
+  - [**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$`.
+  - [**wait**](https://doc-detective.com/reference/schemas/wait.html): Pause before performing the next action.
+- [**Context**](https://doc-detective.com/reference/schemas/context.html): 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
+
+## Develop
+
+To develop Doc Detective, clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/doc-detective/doc-detective.git
+cd doc-detective
+npm i
+```
+
+To run commands, use the same `npx` commands as above.
+
+Make sure you review the [contributions guide](CONTRIBUTIONS.md) before submitting a pull request.
+
+## Contributions
+
+Looking to help out? See our [contributions guide](CONTRIBUTIONS.md) 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](https://github.com/doc-detective/doc-detective/blob/master/LICENSE).

package/dev/dev.spec.json

@@ -1,62 +1,62 @@
-{
-  "id": "Do all the things! - Spec",
-  "tests": [
-    {
-      "id": "Do all the things! - Test",
-      "description": "This test includes nearly every property across all actions.",
-      "steps": [
-        {
-          "action": "setVariables",
-          "path": ".env"
-        },
-        {
-          "action": "runShell",
-          "command": "echo",
-          "args": ["$USER"]
-        },
-        {
-          "action": "checkLink",
-          "url": "https://www.duckduckgo.com"
-        },
-        {
-          "action": "httpRequest",
-          "url": "https://reqres.in/api/users",
-          "method": "post",
-          "requestData": {
-            "name": "morpheus",
-            "job": "leader"
-          },
-          "responseData": {
-            "name": "morpheus",
-            "job": "leader"
-          },
-          "statusCodes": [200, 201]
-        },
-        {
-          "action": "goTo",
-          "url": "https://www.google.com"
-        },
-        {
-          "action": "startRecording",
-          "path": "test.mp4"
-        },
-        {
-          "action": "find",
-          "selector": "[title=Search]",
-          "timeout": 10000,
-          "moveTo": true,
-          "click": true,
-          "typeKeys": {
-            "keys": ["shorthair cat", "$ENTER$"]
-          }
-        },
-        {
-          "action": "wait"
-        },
-        {
-          "action": "stopRecording"
-        }
-      ]
-    }
-  ]
-}
+{
+  "id": "Do all the things! - Spec",
+  "tests": [
+    {
+      "id": "Do all the things! - Test",
+      "description": "This test includes nearly every property across all actions.",
+      "steps": [
+        {
+          "action": "setVariables",
+          "path": ".env"
+        },
+        {
+          "action": "runShell",
+          "command": "echo",
+          "args": ["$USER"]
+        },
+        {
+          "action": "checkLink",
+          "url": "https://www.duckduckgo.com"
+        },
+        {
+          "action": "httpRequest",
+          "url": "https://reqres.in/api/users",
+          "method": "post",
+          "requestData": {
+            "name": "morpheus",
+            "job": "leader"
+          },
+          "responseData": {
+            "name": "morpheus",
+            "job": "leader"
+          },
+          "statusCodes": [200, 201]
+        },
+        {
+          "action": "goTo",
+          "url": "https://www.google.com"
+        },
+        {
+          "action": "startRecording",
+          "path": "test.mp4"
+        },
+        {
+          "action": "find",
+          "selector": "[title=Search]",
+          "timeout": 10000,
+          "moveTo": true,
+          "click": true,
+          "typeKeys": {
+            "keys": ["shorthair cat", "$ENTER$"]
+          }
+        },
+        {
+          "action": "wait"
+        },
+        {
+          "action": "stopRecording"
+        }
+      ]
+    }
+  ]
+}

package/dev/index.js

@@ -1,6 +1,6 @@
-const { setArgs, setConfig } = require("../src/utils");
-
-// Test that arguments are parsed correctly
-json = {
-}
+const { setArgs, setConfig } = require("../src/utils");
+
+// Test that arguments are parsed correctly
+json = {
+}
 console.log(setConfig(json,setArgs(process.argv)))

package/doc-detective.svg

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 24.3.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="_x31_" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="1200px" height="1200px" viewBox="0 0 1200 1200" enable-background="new 0 0 1200 1200" xml:space="preserve">
+<g>
+	<path fill="#4B9A47" d="M1128.306,1200H71.694C32.099,1200,0,1167.901,0,1128.306V71.694C0,32.099,32.099,0,71.694,0h1056.612
+		C1167.901,0,1200,32.099,1200,71.694v1056.612C1200,1167.901,1167.901,1200,1128.306,1200z"/>
+	<g>
+		<path fill="#FFFFFF" d="M251.414,202.411v792.621c0,30.013,24.331,54.344,54.344,54.344h612.917
+			c16.716,0,30.268-13.551,30.268-30.268V420.58L677.939,149.577l-376.472,2.454C273.771,152.211,251.414,174.714,251.414,202.411z"
+			/>
+		<path d="M918.676,1078.376H305.758c-45.956,0-83.344-37.388-83.344-83.344V202.411c0-43.487,35.378-79.097,78.865-79.38
+			l388.594-2.533l288.069,288.07v610.541C977.942,1051.788,951.355,1078.376,918.676,1078.376z M666.006,178.655l-364.349,2.375
+			c-11.713,0.076-21.243,9.668-21.243,21.381v792.621c0,13.975,11.37,25.344,25.344,25.344h612.917c0.698,0,1.267-0.568,1.267-1.268
+			V432.592L666.006,178.655z"/>
+	</g>
+	<rect x="449.529" y="595.822" width="302.675" height="60.076"/>
+	<rect x="449.529" y="759.771" width="181.605" height="60.076"/>
+	<path d="M864.547,919.645l-33.693,0.599l-22.668-28.276c47.751-52.006,73.916-119.016,73.916-190.056
+		c0-75.146-29.264-145.795-82.4-198.932c-53.137-53.137-123.785-82.4-198.932-82.4s-145.795,29.264-198.932,82.4
+		c-53.137,53.136-82.4,123.785-82.4,198.932s29.264,145.795,82.4,198.932c53.136,53.137,123.785,82.4,198.932,82.4
+		c72.38,0,140.58-27.159,192.986-76.64l22.685,24.676l0.425,32.343c0,2.932,1.17,5.743,3.249,7.81l214.126,212.771l49.529-52.28
+		L872.417,922.828C870.324,920.757,867.49,919.611,864.547,919.645z M600.77,920.244c-120.389,0-218.332-97.943-218.332-218.332
+		S480.382,483.58,600.77,483.58s218.332,97.943,218.332,218.332S721.159,920.244,600.77,920.244z"/>
+</g>
+</svg>

package/package.json

@@ -1,43 +1,44 @@
-{
-  "name": "doc-detective",
-  "version": "2.13.0-dev.0",
-  "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
-  "bin": {
-    "doc-detective": "src/index.js"
-  },
-  "main": "./src/index.js",
-  "scripts": {
-    "mocha": "mocha",
-    "test": "mocha test/*.test.js",
-    "runTests": "node ./src/index.js runTests",
-    "runCoverage": "node ./src/index.js runCoverage",
-    "dev": "node ./dev"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hawkeyexl/doc-detective.git"
-  },
-  "keywords": [
-    "documentation",
-    "unit",
-    "test",
-    "doc",
-    "docs"
-  ],
-  "author": "Manny Silva",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/doc-detective/doc-detective/issues"
-  },
-  "homepage": "https://github.com/doc-detective/doc-detective#readme",
-  "dependencies": {
-    "doc-detective-common": "^1.17.0-dev.1",
-    "doc-detective-core": "^2.13.0-dev.0",
-    "prompt-sync": "^4.2.0",
-    "yargs": "^17.7.2"
-  },
-  "devDependencies": {
-    "chai": "^4.3.10",
-    "mocha": "^10.4.0"
-  }
-}
+{
+  "name": "doc-detective",
+  "version": "2.13.1",
+  "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
+  "bin": {
+    "doc-detective": "src/index.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "mocha": "mocha",
+    "test": "mocha test/*.test.js",
+    "runTests": "node ./src/index.js runTests",
+    "runCoverage": "node ./src/index.js runCoverage",
+    "dev": "node ./dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hawkeyexl/doc-detective.git"
+  },
+  "keywords": [
+    "documentation",
+    "unit",
+    "test",
+    "doc",
+    "docs"
+  ],
+  "author": "Manny Silva",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/doc-detective/doc-detective/issues"
+  },
+  "homepage": "https://github.com/doc-detective/doc-detective#readme",
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "doc-detective-common": "^1.17.0",
+    "doc-detective-core": "^2.13.0",
+    "prompt-sync": "^4.2.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "chai": "^5.1.1",
+    "mocha": "^10.4.0"
+  }
+}