doc-detective 2.9.0-dev.2 → 2.9.2

package/.github/FUNDING.yml

@@ -1,14 +1,14 @@
-# These are supported funding model platforms
-
-github: [doc-detective] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: # Replace with a single Patreon username
-open_collective: doc-detective # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-otechie: # Replace with a single Otechie username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+# These are supported funding model platforms
+
+github: [doc-detective] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: doc-detective # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/dependabot.yml

@@ -1,11 +1,11 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  - package-ecosystem: "npm" # See documentation for possible values
-    directory: "/" # Location of package manifests
-    schedule:
-      interval: "weekly"
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/workflows/docker-image.yml

@@ -1,19 +1,19 @@
-name: Docker Image CI
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-  workflow_dispatch:
-
-jobs:
-
-  build:
-
-    runs-on: macos-latest
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Build the Docker image
-      run: npm run docker:build:multiarch
+name: Docker Image CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+jobs:
+
+  build:
+
+    runs-on: macos-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build the Docker image
+      run: npm run docker:build:multiarch

package/.github/workflows/electron-publish.yml

@@ -1,17 +1,17 @@
-name: Build and publish Electron bundles
-
-on:
-#  push:
-#    branches:
-#      - main
-  workflow_dispatch:
-
-jobs:
-  build:
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-      - run: cd frontend && npm i
-      - run: cd ../electron && npm i
-      - run: npm run publish
+name: Build and publish Electron bundles
+
+on:
+#  push:
+#    branches:
+#      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: cd frontend && npm i
+      - run: cd ../electron && npm i
+      - run: npm run publish

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,67 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Publish NPM package
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        node: 
+          - 18
+          - 20
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Cache node_modules
+        uses: actions/cache@v3
+        with:
+          # Cache key uses the contents of `package-lock.json` to identify unique cache
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.OS }}-node-
+          path: |
+            node_modules
+          
+      - run: npm ci
+
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: actions/setup-node@v3
+        with:
+          registry-url: https://registry.npmjs.org/
+
+      - name: Cache node_modules
+        uses: actions/cache@v3
+        with:
+          # Cache key uses the contents of `package-lock.json` to identify unique cache
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.OS }}-node-
+          path: |
+            node_modules
+            
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/.github/workflows/npm-test.yaml

@@ -1,50 +1,48 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Run tests
-
-on:
-
-  push:
-
-    branches:
-
-      - main
-
-  pull_request:
-
-    types: [opened, reopened, synchronize]
-
-  workflow_dispatch:
-
-jobs:
-
-  build:
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-
-      matrix:
-
-        os: 
-          - ubuntu-latest
-          - windows-latest
-          - macos-latest
-
-        node: [18, 20]
-
-    steps:
-
-      - uses: actions/checkout@v3
-
-      - uses: actions/setup-node@v3
-
-        with:
-
-          node-version: ${{ matrix.node }}
-
-      - run: npm i
-
-      - run: npm test
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Run tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: 
+      - opened
+      - reopened
+      - synchronize
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        node: 
+          - 18
+          - 20
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Cache node_modules
+        uses: actions/cache@v3
+        with:
+          # Cache key uses the contents of `package-lock.json` to identify unique cache
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.OS }}-node-
+          path: |
+            node_modules
+          
+      - run: npm ci
+
+      - run: npm test

package/CONTRIBUTIONS.md

@@ -0,0 +1,27 @@
+# How to contribute
+
+`doc-detective` welcomes contributions of all sorts (as do all Doc Detective projects). If you can't contribute code, you can still help by reporting issues, suggesting new features, improving the documentation, or sponsoring the project. Please follow the guidelines below.
+
+## Reporting issues
+
+If you find a bug, report it on the [GitHub issue tracker](https://github.com/doc-detective/doc-detective/issues).
+
+## Contributing code
+
+To contribute code,
+
+1. Fork the project.
+2. Create a new branch.
+3. Make your changes.
+4. Submit a pull request to the `rc` (release candidate) branch.
+5. Wait for your pull request to be reviewed.
+6. Make any necessary changes to your pull request.
+7. Your pull request will be merged once it has been reviewed and approved.
+
+## License
+
+By contributing to `doc-detective`, you agree that your contributions will be licensed under the [MIT license](https://github.com/doc-detective/doc-detective/blob/main/LICENCE).
+
+## Thank you
+
+Thank you for your contributions! We appreciate your help in making the project better.

package/LICENSE

@@ -1,21 +1,21 @@
-The MIT License
-
-Copyright (c) 2021- Manny Silva
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+The MIT License
+
+Copyright (c) 2021- Manny Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.

package/README.md

@@ -1,112 +1,117 @@
-# <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 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:
-
-- Doc Detective (this repo): A standalone tool that enables testing.
-- [Doc Detective Core](https://github.com/doc-detective/doc-detective-core): An NPM package that provides the core 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
-
-0. Install prerequisites:
-
-    - [Node.js](https://nodejs.org/) (tested on v18 and v20)
-
-1. In a terminal, clone the repo and install dependencies:
-
-    ```bash
-    npm i -g doc-detective
-    ```
-
-## 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:
-
-```bash
-npx doc-detective runTests --input ./samples/doc-content-inline-tests.md
-```
-
-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.
-
-```bash
-npx doc-detective 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:
-
-```bash
-npx doc-detective runTests --config ./samples/config.json --input ./samples/tests.spec.json
-```
-
-To see all available options, use the `--help` argument:
-
-```bash
-npx doc-detective runTests --help
-```
-
-**Note**: If you clone this repo and run the `runTests` command, use `npm run runTests --` instead of `npx doc-detective runTests`.
-
-## 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`](https://doc-detective.com/reference/schemas/config.html) file accordingly.
-
-```bash
-npx doc-detective runCoverage --config ./samples/config.json --input ./samples/doc-content.md
-```
-
-To see all available options, use the `--help` argument:
-
-```bash
-npx doc-detective runCoverage --help
-```
-
-## Run locally
-
-To run Doc Detective locally, 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 `npm run` scripts:
-
-```bash
-npm run runTests -- --input ./samples/doc-content-inline-tests.md
-npm run runCoverage -- --input ./samples/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.
-
-## 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 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:
+
+- 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
+
+> 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).
+
+You can run Doc Detective as a CLI tool with Node:
+
+0.  Install prerequisites:
+
+    - [Node.js](https://nodejs.org/) (tested on 18.16.0)
+
+1.  In a terminal, clone the repo and install dependencies:
+
+    ```bash
+    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:
+
+```bash
+npm run runTests -- --input ./samples/doc-content.md
+```
+
+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.
+
+```bash
+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:
+
+```bash
+npm run runTests -- --config ./samples/config.json --input ./samples/tests.spec.json
+```
+
+To see all available options, use the `--help` argument:
+
+```bash
+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`](https://doc-detective.com/reference/schemas/config.html) file accordingly.
+
+
+```bash
+npm run runCoverage -- --config ./samples/config.json --input ./samples/doc-content.md
+```
+
+To see all available options, use the `--help` argument:
+
+```bash
+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**](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
+
+## Contributions
+
+Looking to help out? See our [contributions guide](https://github.com/doc-detective/doc-detective/blob/main/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).