doc-detective 1.0.0

package/ref/analytics.json

@@ -0,0 +1,112 @@
+{
+  "version": "doc-unit-test version that ran the tests.",
+  "detailLevel": "How much detail is included in the analytics object. Values: ['parameter', 'action', 'test', 'run']",
+  "userId": "Optional. Identifier of the organization or individual running tests.",
+  "tests": {
+    "numberTests": "Total number of tests in a run.",
+    "passed": "Number of tests that passed",
+    "failed": "Number of tests that failed."
+  },
+  "actions": {
+    "numberActions": "Total number of actions in a run.",
+    "averageNumberActionsPerTest": "Average number of actions per test in a run.",
+    "minActionsPerTest": "Smallest number of actions in a test in a run.",
+    "maxActionsPerTest": "Largest number of actions in a tedt in a run",
+    "passed": "Number of actions that passed",
+    "failed": "Number of actions that failed."
+  },
+  "actionDetails": {
+    "goTo": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "uri": "Number of instances this setting was used."
+    },
+    "find": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "css": "Number of instances this setting was used."
+    },
+    "matchText": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "css": "Number of instances this setting was used.",
+      "text": "Number of instances this setting was used."
+    },
+    "click": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "css": "Number of instances this setting was used."
+    },
+    "type": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "css": "Number of instances this setting was used.",
+      "keys": "Number of instances this setting was used.",
+      "trailingSpecialKey": "Number of instances this setting was used."
+    },
+    "moveMouse": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "alignH": "Number of instances this setting was used.",
+      "alignV": "Number of instances this setting was used.",
+      "offsetX": "Number of instances this setting was used.",
+      "offsetY": "Number of instances this setting was used."
+    },
+    "scroll": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "x": "Number of instances this setting was used.",
+      "y": "Number of instances this setting was used."
+    },
+    "wait": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "duration": "Number of instances this setting was used."
+    },
+    "screenshot": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "mediaDirectory": "Number of instances this setting was used.",
+      "filename": "Number of instances this setting was used.",
+      "matchPrevious": "Number of instances this setting was used.",
+      "matchThreshold": "Number of instances this setting was used."
+    },
+    "startRecording": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "mediaDirectory": "Number of instances this setting was used.",
+      "filename": "Number of instances this setting was used.",
+      "gifFps": "Number of instances this setting was used.",
+      "gifWidth": "Number of instances this setting was used."
+    },
+    "stopRecording": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed."
+    },
+    "checkLink": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "uri": "Number of instances this setting was used.",
+      "statusCodes": "Number of instances this setting was used."
+    },
+    "runShell": {
+      "numberInstances": "How many instances of the action were present in tests.",
+      "passed": "Number of instances that passed.",
+      "failed": "Number of instances that failed.",
+      "command": "Number of instances this setting was used.",
+      "env": "Number of instances this setting was used."
+    }
+  }
+}

package/ref/testDefinition.json

@@ -0,0 +1,37 @@
+{
+  "tests": [
+    {
+      "id": "Optional. ID of the test. Must be unique. Generated UUID if not specified.",
+      "file": "Output only. File the test is defined in. All actions for a given test must be defined in a single file.",
+      "status": "Output only. The status of the test based on test action results. Possible values: PASS, WARNING, FAIL",
+      "actions": [
+        {
+          "action": "Required. Task to perform. Supported values: goTo, find, matchText, click, type, wait, screenshot",
+          "alignH": "Optional. Applicable actions: moveMouse, find. Horizantal alignment of the mouse to the element. Accepted values: left, center, right",
+          "alignV": "Optional. Applicable actions: moveMouse, find. Vertical alignment of the mouse to the element. Accepted values: top, center, bottom",
+          "css": "Required for the following actions: find, matchText, click, type, moveMouse. CSS selectors that resolve to the element. Only returns the first element that matches the selectors.",
+          "duration": "Optional. Applicable actions: wait. How long to wait in milliseconds.",
+          "filename": "Optional. Applicable actions: screenshot. Name of the media file. If not specified, the filename is randomized.",
+          "gifFps": "Optional. Application action: startRecording. Frames per second of the output GIF file.",
+          "gifWidth": "Optional. Application action: startRecording. Width of the output GIF file.",
+          "keys": "Optional. Applicable actions: type, find. Strings of keys of enter. To send special keys like 'ENTER', see 'trailingSpecialKey'.",
+          "line": "Output only. Line number that the test action definition begins on.",
+          "mediaDirectory": "Optional. Applicable actions: screenshot. The directory path for media created by the action. Overrides the default directory config. Default is config.imageDirectory or config.videoDirectory depending on the file type.",
+          "offsetX": "Optional. Applicable actions: moveMouse, find. How many pixels to offset the mouse along the X axis, relative to the element center.",
+          "offsetY": "Optional. Applicable actions: moveMouse, find. How many pixels to offset the mouse along the Y axis, relative to the element center.",
+          "statusCodes": "Optional. Applicable action: checkLink. The HTTP status codes accepted from makeing a GET request to the specified URI.",
+          "testId": "Optional. Input only. Only valid for non-JSON test files. ID of the test the action belongs to.",
+          "text": "Required. Applicable actions: matchText, find. Exact text expected to display in the element.",
+          "trailingSpecialKey": "Optional. Applicable actions: type, find. A special key pressed after the 'keys' value, if present. Supported values: https://github.com/puppeteer/puppeteer/blob/main/src/common/USKeyboardLayout.ts",
+          "uri": "Required. Applicable actions: goTo, checkLink. URI to check or to navigate to in the browser.",
+          "result": {
+            "status": "Output only. Status based on test action results. Possible values: PASS, WARNING, FAIL",
+            "description": "Output only. Explaination of the action result.",
+            "image": "Output only. File path for an output image.",
+            "video": "Output only. File path for an output video."
+          }
+        }
+      ]
+    }
+  ]
+}

package/sample/config.json

@@ -0,0 +1,47 @@
+{
+  "env": "sample/variables.env",
+  "input": "sample/doc-content.md",
+  "output": "sample/results.json",
+  "recursive": true,
+  "testExtensions": [
+    ".md",
+    ".mdx",
+    ".html",
+    ".htm",
+    ".xml",
+    ".json"
+  ],
+  "mediaDirectory": "sample",
+  "fileTypes": [
+    {
+      "extensions": [
+        ".md",
+        ".mdx"
+      ],
+      "openTestStatement": "[comment]: # (test",
+      "closeTestStatement": ")"
+    },
+    {
+      "extensions": [
+        ".html",
+        ".htm",
+        ".xml"
+      ],
+      "openTestStatement": "<!-- test",
+      "closeTestStatement": "-->"
+    }
+  ],
+  "browserOptions": {
+    "headless": "true",
+    "path": "",
+    "height": 600,
+    "width": 800
+  },
+  "analytics": {
+    "send": false,
+    "userId": "",
+    "detailLevel": "action-detailed",
+    "customServers": []
+  },
+  "logLevel": "info"
+}

package/sample/doc-content.md

@@ -0,0 +1,42 @@
+# Search for kittens
+
+To use Google Search to find information on kittens,
+
+1.  Open [Google Search](https://www.google.com).
+
+    [comment]: # (test {"testId":"process-search-kittens", "action":"startRecording", "filename":"results.gif", "gifFps":15, "gifWidth":300})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"goTo", "uri":"www.google.com"})
+
+2.  In the search bar, enter "kittens", then press Enter.
+
+    [comment]: # (test {"testId":"process-search-kittens", "action":"moveMouse", "css":"#gbqfbb", "alignH": "center", "alignV": "center"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"wait", "duration":"5000"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"moveMouse", "css":"[title=Search]", "alignV": "center"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"type", "css":"[title=Search]", "keys":"kittens", "trailingSpecialKey":"Enter"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"wait", "duration":"5000"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"scroll", "y": 300})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"stopRecording"})
+    [comment]: # (test {"testId":"process-search-kittens", "action":"screenshot", "filename":"results.png", "matchPrevious": true, "matchThreshold": 0.1})
+
+Search results appear on the page.
+
+![Search results for 'kittens'.](results.png)
+
+## Recommended results
+
+To go directly to a recommended result for your search, use the **I'm Feeling Lucky** button. If you're searching for american shorthair information,
+
+[comment]: # (test {"testId":"text-match-lucky", "action":"goTo", "uri":"www.google.com"})
+[comment]: # (test {"testId":"text-match-lucky", "action":"matchText", "css":"#gbqfbb", "text":"I'm Feeling Lucky"})
+
+1.  Open [Google Search](https://www.google.com).
+
+    [comment]: # (test {"testId":"process-lucky-shorthair", "action":"goTo", "uri":"www.google.com"})
+
+2.  In the search bar, enter "american shorthair cats".
+
+    [comment]: # (test {"testId":"process-lucky-shorthair", "action":"type", "css":"[title=Search]", "keys":"american shorthair cats"})
+
+3.  Click **I'm Feeling Lucky**.
+
+    [comment]: # (test {"testId":"process-lucky-shorthair", "action":"click", "css":"#gbqfbb"})

package/sample/results.json

@@ -0,0 +1,36 @@
+{
+  "tests": [
+    {
+      "id": "process-lucky-shorthair",
+      "actions": [
+        {
+          "action": "goTo",
+          "uri": "www.google.com",
+          "result": {
+            "status": "PASS",
+            "description": "Opened URI."
+          }
+        },
+        {
+          "action": "type",
+          "css": "[title=Search]",
+          "keys": "american shorthair cats",
+          "result": {
+            "status": "PASS",
+            "description": "Typed keys."
+          }
+        },
+        {
+          "action": "click",
+          "moveMouse": true,
+          "css": "#gbqfbb",
+          "result": {
+            "status": "PASS",
+            "description": "Clicked element."
+          }
+        }
+      ],
+      "status": "PASS"
+    }
+  ]
+}

package/sample/tests.json

@@ -0,0 +1,92 @@
+{
+  "tests": [
+    {
+      "id": "process-search-kittens",
+      "actions": [
+        {
+          "action": "goTo",
+          "uri": "www.google.com"
+        },
+        {
+          "action": "type",
+          "css": "[title=Search]",
+          "keys": "kittens",
+          "trailingSpecialKey": "Enter"
+        },
+        {
+          "action": "wait",
+          "duration": "5000"
+        },
+        {
+          "action": "screenshot",
+          "filename": "results.png",
+          "matchPrevious": true,
+          "matchThreshold": 0.1
+        }
+      ]
+    },
+    {
+      "id": "text-match-lucky",
+      "actions": [
+        {
+          "action": "goTo",
+          "uri": "www.google.com"
+        },
+        {
+          "action": "matchText",
+          "css": "#gbqfbb",
+          "text": "I'm Feeling Lucky"
+        },
+        {
+          "action": "matchText",
+          "css": "#gbqfbb",
+          "text": "$TEXT",
+          "env": "./sample/variables.env"
+        }
+      ]
+    },
+    {
+      "id": "process-lucky-shorthair",
+      "actions": [
+        {
+          "action": "goTo",
+          "uri": "$URL",
+          "env": "./sample/variables.env"
+        },
+        {
+          "action": "type",
+          "css": "[title=Search]",
+          "keys": "$SHORTHAIR_CAT_SEARCH"
+        },
+        {
+          "action": "click",
+          "css": "#gbqfbb"
+        }
+      ]
+    },
+    {
+      "id": "non-ui-tests",
+      "actions": [
+        {
+          "action": "runShell",
+          "command": "echo $USERNAME",
+          "env": "./sample/variables.env"
+        },
+        {
+          "action": "checkLink",
+          "uri": "https://www.google.com",
+          "statusCodes": [
+            200
+          ]
+        },
+        {
+          "action": "checkLink",
+          "uri": "$URL",
+          "statusCodes": [
+            200
+          ]
+        }
+      ]
+    }
+  ]
+}

package/sample/variables.env

@@ -0,0 +1,5 @@
+USERNAME=foo
+PASSWORD=bar
+SHORTHAIR_CAT_SEARCH=american shorthair cats
+URL=www.google.com
+TEXT=I'm Feeling Lucky

package/src/config.json

@@ -0,0 +1,47 @@
+{
+  "env": "",
+  "input": ".",
+  "output": "./results.json",
+  "recursive": true,
+  "testExtensions": [
+    ".md",
+    ".mdx",
+    ".html",
+    ".htm",
+    ".xml",
+    ".json"
+  ],
+  "mediaDirectory": ".",
+  "fileTypes": [
+    {
+      "extensions": [
+        ".md",
+        ".mdx"
+      ],
+      "openTestStatement": "[comment]: # (test",
+      "closeTestStatement": ")"
+    },
+    {
+      "extensions": [
+        ".html",
+        ".htm",
+        ".xml"
+      ],
+      "openTestStatement": "<!-- test",
+      "closeTestStatement": "-->"
+    }
+  ],
+  "browserOptions": {
+    "headless": "true",
+    "path": "",
+    "height": 800,
+    "width": 1200
+  },
+  "analytics": {
+    "send": false,
+    "userId": "",
+    "detailLevel": "action-detailed",
+    "customServers": []
+  },
+  "logLevel": "info"
+}

package/src/index.js

@@ -0,0 +1,51 @@
+const {
+  setArgs,
+  setConfig,
+  setFiles,
+  parseFiles,
+  outputResults,
+  log,
+} = require("./lib/utils");
+const { sendAnalytics } = require("./lib/analytics.js");
+const { runTests } = require("./lib/tests");
+
+exports.run = function (config, argv) {
+  main(config, argv);
+};
+
+async function main(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 = parseFiles(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);
+  log(config, "debug", `RESULTS:`);
+  log(config, "debug", results);
+
+  // Output
+  outputResults(config, results);
+  if (config.analytics.send) {
+    sendAnalytics(config, results);
+  }
+}