doc-detective 1.3.1 → 2.9.0-dev.0

package/.github/FUNDING.yml

@@ -0,0 +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']

package/.github/dependabot.yml

@@ -0,0 +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"

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,50 @@
+# 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

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,42 +1,109 @@
-# Doc Detective Core
-
-![Current version](https://img.shields.io/github/package-json/v/doc-detective/doc-detective-core?color=orange)
-[![NPM Shield](https://img.shields.io/npm/v/doc-detective)](https://www.npmjs.com/package/doc-detective)
-[![Discord Shield](https://img.shields.io/badge/chat-on%20discord-purple)](https://discord.gg/mSCCRAhH)
-
-Low-code documentation testing embedded in your project via [NPM](https://www.npmjs.com/package/doc-detective).
-
-For pre-built implementations, see [Doc Detective](https://github.com/doc-detective/doc-detective).
-
-## Install
-
-```bash
-npm i doc-detective
-```
-
-## Init
-
-```javascript
-const { test, coverage, suggest } = require("doc-detective");
-```
-
-## Methods
-
-### `test(config, argv)`
-
-Run tests. Recursively parses files in the `config.input` path for tests to perform. Returns a test report object.
-
-### `coverage(config, argv)`
-
-Run test coverage analysis on the specified source documents. Identifies uncovered markup based on regular expressions in `config.fileTypes.markup`. Returns a coverage report object.
-
-### `suggest(config, argv)`
-
-Interactively build tests for uncovered markup in the specified source documents. Identifies uncovered markup based on regular expressions in `config.fileTypes.markup`. Writes tests to file and returns a suggestions object.
-
-
-## Objects
-
-### `config`
-
-Settings for your documentation source files and Doc Detective tests. See a sample config object in the [Doc Detective](https://github.com/doc-detective/doc-detective/blob/main/sample/config.json) repo.
+# <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
+
+> 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 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
+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
+## License
+
+This project uses the [MIT license](https://github.com/doc-detective/doc-detective/blob/master/LICENSE).

package/dev/dev.spec.json

@@ -0,0 +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"
+        }
+      ]
+    }
+  ]
+}

package/dev/index.js

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

package/index.js

@@ -1,129 +1 @@
-const {
-  setArgs,
-  setConfig,
-  setFiles,
-  parseTests,
-  outputResults,
-  log,
-} = require("./src/utils");
-const { sendAnalytics } = require("./src/analytics.js");
-const { runTests } = require("./src/tests");
-const { checkTestCoverage, checkMarkupCoverage } = require("./src/analysis");
-const { reportCoverage } = require("./src/coverage");
-const { suggestTests, runSuggestions } = require("./src/suggest");
-const { exit } = require("process");
-
-exports.test = test;
-exports.coverage = coverage;
-exports.suggest = suggest;
-
-async function test(config, argv) {
-  // Set args
-  argv = setArgs(argv);
-  log(config, "debug", `ARGV:`);
-  log(config, "debug", argv);
-
-  // Set config
-  config = setConfig(config, argv);
-  log(config, "debug", `CONFIG:`);
-  log(config, "debug", config);
-
-  // Set files
-  const files = setFiles(config);
-  log(config, "debug", `FILES:`);
-  log(config, "debug", files);
-
-  // Set tests
-  const tests = parseTests(config, files);
-  if (config.logLevel === "debug") {
-    console.log("(DEBUG) TESTS:");
-    tests.tests.forEach((test) => {
-      console.log(test);
-    });
-  }
-
-  // Run tests
-  const results = await runTests(config, tests);
-
-  // Output
-  outputResults(config.output, results, config);
-  if (config.analytics.send) {
-    // sendAnalytics(config, results);
-  }
-
-  return results;
-}
-
-async function coverage(config, argv) {
-  // Set args
-  argv = setArgs(argv);
-  log(config, "debug", `ARGV:`);
-  log(config, "debug", argv);
-
-  // Set config
-  config = setConfig(config, argv);
-  log(config, "debug", `CONFIG:`);
-  log(config, "debug", config);
-
-  // Set files
-  const files = setFiles(config);
-  log(config, "debug", `FILES:`);
-  log(config, "debug", files);
-
-  const testCoverage = checkTestCoverage(config, files);
-  log(config, "debug", "TEST COVERAGE:");
-  log(config, "debug", testCoverage);
-
-  const markupCoverage = checkMarkupCoverage(config, testCoverage);
-  log(config, "debug", "MARKUP COVERAGE:");
-  log(config, "debug", markupCoverage);
-
-  const coverageReport = reportCoverage(config, markupCoverage);
-  log(config, "debug", "COVERAGE REPORT:");
-  log(config, "debug", coverageReport);
-
-  // Output
-  outputResults(config.coverageOutput, coverageReport, config);
-
-  return coverageReport;
-}
-
-async function suggest(config, argv) {
-  // Set args
-  argv = setArgs(argv);
-  log(config, "debug", `ARGV:`);
-  log(config, "debug", argv);
-
-  // Set config
-  config = setConfig(config, argv);
-  log(config, "debug", `CONFIG:`);
-  log(config, "debug", config);
-
-  // Set files
-  const files = setFiles(config);
-  log(config, "debug", `FILES:`);
-  log(config, "debug", files);
-
-  const testCoverage = checkTestCoverage(config, files);
-  log(config, "debug", "TEST COVERAGE:");
-  log(config, "debug", testCoverage);
-
-  const markupCoverage = checkMarkupCoverage(config, testCoverage);
-  log(config, "debug", "MARKUP COVERAGE:");
-  log(config, "debug", markupCoverage);
-
-  const suggestionReport = suggestTests(config, markupCoverage);
-  log(config, "debug", "TEST SUGGESTIONS:");
-  log(config, "debug", suggestionReport);
-
-  await runSuggestions(config, suggestionReport);
-
-  // Output
-  outputResults(
-    config.testSuggestions.reportOutput,
-    suggestionReport,
-    config
-  );
-
-  return suggestionReport;
-}
+console.log("Here there be dragons.")

package/package.json

@@ -1,44 +1,43 @@
-{
-  "name": "doc-detective",
-  "version": "1.3.1",
-  "description": "The documentation testing framework.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/doc-detective/doc-detective-core.git"
-  },
-  "keywords": [
-    "documentation",
-    "test",
-    "doc",
-    "docs"
-  ],
-  "author": "Manny Silva",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/doc-detective/doc-detective-core/issues"
-  },
-  "homepage": "https://github.com/doc-detective/doc-detective-core#readme",
-  "dependencies": {
-    "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "axios": "^0.27.2",
-    "dotenv": "^16.0.2",
-    "git": "^0.1.5",
-    "gnumake": "^0.3.5",
-    "n-readlines": "^1.0.1",
-    "node-jq": "^2.3.4",
-    "pixelmatch": "^5.3.0",
-    "pngjs": "^6.0.0",
-    "prompt-sync": "^4.2.0",
-    "puppeteer": "^13.7.0",
-    "puppeteer-screen-recorder": "^2.0.2",
-    "uuid": "^8.3.2",
-    "yargs": "^17.4.1"
-  },
-  "devDependencies": {
-    "make": "^0.8.1"
-  }
-}
+{
+  "name": "doc-detective",
+  "version": "2.9.0-dev.0",
+  "description": "Unit test documentation (and record videos of those tests).",
+  "bin": {
+    "doc-detective": "node ./src/index.js"
+  },
+  "scripts": {
+    "mocha": "mocha",
+    "postinstall": "node ./node_modules/doc-detective-core/scripts/postinstall.js",
+    "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.13.0",
+    "doc-detective-core": "^2.9.3",
+    "prompt-sync": "^4.2.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "mocha": "^10.3.0"
+  }
+}