doc-detective 2.9.0-dev.2 → 2.9.1

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/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,110 @@
-# <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.
+- [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
+```
+
+## 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).