doc-detective 2.9.3-dev.0 → 2.10.1

package/samples/doc-content-inline-tests.md

@@ -1,28 +1,28 @@
-# Doc Detective documentation overview
-
-[comment]: # (test start {"id":"search-kittens", "detectSteps":false})
-
-[Doc Detective documentation](http://doc-detective.com) is split into a few key sections:
-
-[comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com"})
-
--   The landing page discusses what Doc Detective is, what it does, and who might find it useful.
--   [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
-
-    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/get-started.html"})
-
--   The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
-
-    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/"})
-    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/config.html"})
-    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/specification.html"})
-    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/test.html"})
-    [comment]: # (step {"action":"goTo", "url":"https://doc-detective.com/reference/schemas/typeKeys.html"})
-    [comment]: # (step {"action":"find", "selector":"h2#description", "matchText":"Description"})
-    [comment]: # (step {"action":"find", "selector":"h2#fields", "matchText":"Fields"})
-    [comment]: # (step {"action":"find", "selector":"h2#examples", "matchText":"Examples"})
-
-![](reference.png)
-[comment]: # (step {"action":"saveScreenshot", "path":"reference.png", "directory":"samples", "maxVariation":5, "overwrite":"byVariation"})
-
+# Doc Detective documentation overview
+
+[comment]: # (test start {"id":"search-kittens", "detectSteps":false})
+
+[Doc Detective documentation](http://doc-detective.com) is split into a few key sections:
+
+[comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com"})
+
+-   The landing page discusses what Doc Detective is, what it does, and who might find it useful.
+-   [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
+
+    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/get-started.html"})
+
+-   The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
+
+    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/"})
+    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/config.html"})
+    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/specification.html"})
+    [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/test.html"})
+    [comment]: # (step {"action":"goTo", "url":"https://doc-detective.com/reference/schemas/typeKeys.html"})
+    [comment]: # (step {"action":"find", "selector":"h2#description", "matchText":"Description"})
+    [comment]: # (step {"action":"find", "selector":"h2#fields", "matchText":"Fields"})
+    [comment]: # (step {"action":"find", "selector":"h2#examples", "matchText":"Examples"})
+
+![](reference.png)
+[comment]: # (step {"action":"saveScreenshot", "path":"reference.png", "directory":"samples", "maxVariation":5, "overwrite":"byVariation"})
+
 [comment]: # (test end)

package/samples/doc-content.md

@@ -1,9 +1,9 @@
-# Doc Detective documentation overview
-
-[Doc Detective documentation](https://doc-detective.com) is split into a few key sections:
-
--   The landing page discusses what Doc Detective is, what it does, and who might find it useful.
--   [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
--   The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
-
+# Doc Detective documentation overview
+
+[Doc Detective documentation](https://doc-detective.com) is split into a few key sections:
+
+-   The landing page discusses what Doc Detective is, what it does, and who might find it useful.
+-   [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
+-   The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
+
 ![](reference.png)

package/samples/tests.spec.json

@@ -1,70 +1,70 @@
-{
-  "id": "Do all the things! - Spec",
-  "contexts": [
-    {
-      "app": {
-        "name": "firefox"
-      },
-      "platforms": ["windows", "mac", "linux"]
-    }
-  ],
-  "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": "find",
-          "selector": "[title=Search]",
-          "timeout": 10000,
-          "moveTo": true,
-          "click": true,
-          "typeKeys": {
-            "keys": ["shorthair cat", "$ENTER$"]
-          }
-        },
-        {
-          "action": "wait"
-        },
-        {
-          "action": "saveScreenshot",
-          "path": "screenshot.png",
-          "directory": "samples",
-          "maxVariation": 5,
-          "overwrite": "byVariation"
-        }
-      ]
-    }
-  ]
-}
+{
+  "id": "Do all the things! - Spec",
+  "contexts": [
+    {
+      "app": {
+        "name": "firefox"
+      },
+      "platforms": ["windows", "mac", "linux"]
+    }
+  ],
+  "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": "find",
+          "selector": "[title=Search]",
+          "timeout": 10000,
+          "moveTo": true,
+          "click": true,
+          "typeKeys": {
+            "keys": ["shorthair cat", "$ENTER$"]
+          }
+        },
+        {
+          "action": "wait"
+        },
+        {
+          "action": "saveScreenshot",
+          "path": "screenshot.png",
+          "directory": "samples",
+          "maxVariation": 5,
+          "overwrite": "byVariation"
+        }
+      ]
+    }
+  ]
+}

package/samples/variables.env

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

package/src/index.js

@@ -1,43 +1,43 @@
-#!/usr/bin/env node
-
-const { runTests, runCoverage } = require("doc-detective-core");
-const { setArgs, setConfig, outputResults } = require("./utils");
-const { argv } = require("node:process");
-const path = require("path");
-
-main(argv);
-
-// Run tests
-async function main(argv) {
-  // Find index of `doc-detective` or `run` in argv
-  let index = argv.indexOf("doc-detective");
-  if (index === -1) {
-    index = argv.findIndex((arg) => arg.endsWith("index.js"));
-  }
-  // `command` is the next argument after `doc-detective` or `src/index.js`
-  const command = argv[index + 1];
-  // Set args and config
-  argv = setArgs(argv);
-  const config = setConfig({}, argv);
-  // Run command
-  let results = {};
-  let outputDir;
-  let outputReportType;
-  if (command === "runCoverage") {
-    outputDir = config?.runCoverage?.output || config.output;
-    outputReportType = "coverageResults";
-    results = await runCoverage(config);
-  } else if (command === "runTests") {
-    outputDir = config?.runTests?.output || config.output;
-    outputReportType = "testResults";
-    results = await runTests(config);
-  } else {
-    throw new Error(`Command ${command} not found`);
-  }
-  // Output results
-  const outputPath = path.resolve(
-    outputDir,
-    `${outputReportType}-${Date.now()}.json`
-  );
-  await outputResults(config, outputPath, results);
-}
+#!/usr/bin/env node
+
+const { runTests, runCoverage } = require("doc-detective-core");
+const { setArgs, setConfig, outputResults } = require("./utils");
+const { argv } = require("node:process");
+const path = require("path");
+
+main(argv);
+
+// Run tests
+async function main(argv) {
+  // Find index of `doc-detective` or `run` in argv
+  let index = argv.indexOf("doc-detective");
+  if (index === -1) {
+    index = argv.findIndex((arg) => arg.endsWith("index.js"));
+  }
+  // `command` is the next argument after `doc-detective` or `src/index.js`
+  const command = argv[index + 1];
+  // Set args and config
+  argv = setArgs(argv);
+  const config = setConfig({}, argv);
+  // Run command
+  let results = {};
+  let outputDir;
+  let outputReportType;
+  if (command === "runCoverage") {
+    outputDir = config?.runCoverage?.output || config.output;
+    outputReportType = "coverageResults";
+    results = await runCoverage(config);
+  } else if (command === "runTests") {
+    outputDir = config?.runTests?.output || config.output;
+    outputReportType = "testResults";
+    results = await runTests(config);
+  } else {
+    throw new Error(`Command ${command} not found`);
+  }
+  // Output results
+  const outputPath = path.resolve(
+    outputDir,
+    `${outputReportType}-${Date.now()}.json`
+  );
+  await outputResults(config, outputPath, results);
+}

package/src/utils.js

@@ -1,157 +1,157 @@
-const yargs = require("yargs/yargs");
-const { hideBin } = require("yargs/helpers");
-const { validate } = require("doc-detective-common");
-const path = require("path");
-const fs = require("fs");
-const { spawn } = require("child_process");
-
-exports.setArgs = setArgs;
-exports.setConfig = setConfig;
-exports.outputResults = outputResults;
-exports.spawnCommand = spawnCommand;
-
-// Define args
-function setArgs(args) {
-  if (!args) return {};
-  let argv = yargs(hideBin(args))
-    .option("config", {
-      alias: "c",
-      description: "Path to a `config.json` file.",
-      type: "string",
-    })
-    .option("input", {
-      alias: "i",
-      description:
-        "Path to test specifications and documentation source files. May be paths to specific files or to directories to scan for files.",
-      type: "string",
-    })
-    .option("output", {
-      alias: "o",
-      description:
-        "Path of the directory in which to store the output of Doc Detective commands.",
-      type: "string",
-    })
-    .option("setup", {
-      description:
-        "Path to test specifications to perform before those specified by `input`. Useful for setting up testing environments.",
-      type: "string",
-    })
-    .option("cleanup", {
-      description:
-        "Path to test specifications to perform after those specified by input. Useful for cleaning up testing environments.",
-      type: "string",
-    })
-    .option("recursive", {
-      alias: "r",
-      description:
-        "Boolean.  If true searches input, setup, and cleanup paths recursively for test specificaions and source files. Defaults to `true`.",
-      type: "string",
-    })
-    .option("logLevel", {
-      alias: "l",
-      description:
-        "Detail level of logging events. Accepted values: silent, error, warning, info (default), debug",
-      type: "string",
-    })
-    .help()
-    .alias("help", "h").argv;
-
-  return argv;
-}
-
-// Override config values based on args
-function setConfig(config, args) {
-  // If no args, return config
-  if (!args) return config;
-
-  // Load config from file
-  if (args.config) {
-    const configPath = path.resolve(args.config);
-    configContent = require(configPath);
-    // Validate config
-    const validation = validate("config_v2", configContent);
-    if (validation.valid) {
-      config = configContent;
-    } else {
-      // Output validation errors
-      console.error("Invalid config file:");
-      validation.errors.forEach((error) => {
-        console.error(error);
-      });
-      process.exit(1);
-    }
-  }
-
-  // Override config values
-  if (args.input) config.input = args.input;
-  if (args.output) config.output = args.output;
-  if (args.recursive) config.recursive = args.recursive;
-  if (args.logLevel) config.logLevel = args.logLevel;
-  if ((args.setup || args.cleanup  || args.input || args.output ) && !config.runTests) config.runTests = {};
-  if (args.input) config.runTests.input = args.input;
-  if (args.output) config.runTests.output = args.output;
-  if (args.setup) config.runTests.setup = args.setup;
-  if (args.cleanup) config.runTests.cleanup = args.cleanup;
-
-  // Validate config
-  const validation = validate("config_v2", config);
-  if (!validation.valid) {
-    // Output validation errors
-    console.error("Invalid config.");
-    validation.errors.forEach((error) => {
-      console.error(error);
-    });
-    process.exit(1);
-  }
-
-  return config;
-}
-
-async function outputResults(config, path, results) {
-  let data = JSON.stringify(results, null, 2);
-  fs.writeFile(path, data, (err) => {
-    if (err) throw err;
-  });
-  console.log(`See results at ${path}`);
-}
-
-// Perform a native command in the current working directory.
-async function spawnCommand(cmd, args) {
-  // Split command into command and arguments
-  if (cmd.includes(" ")) {
-    const cmdArray = cmd.split(" ");
-    cmd = cmdArray[0];
-    cmdArgs = cmdArray.slice(1);
-    // Add arguments to args array
-    if (args) {
-      args = cmdArgs.concat(args);
-    } else {
-      args = cmdArgs;
-    }
-  }
-
-  const runCommand = spawn(cmd, args);
-
-  // Capture stdout
-  let stdout = "";
-  for await (const chunk of runCommand.stdout) {
-    stdout += chunk;
-  }
-  // Remove trailing newline
-  stdout = stdout.replace(/\n$/, "");
-
-  // Capture stderr
-  let stderr = "";
-  for await (const chunk of runCommand.stderr) {
-    stderr += chunk;
-  }
-  // Remove trailing newline
-  stderr = stderr.replace(/\n$/, "");
-
-  // Capture exit code
-  const exitCode = await new Promise((resolve, reject) => {
-    runCommand.on("close", resolve);
-  });
-
-  return { stdout, stderr, exitCode };
+const yargs = require("yargs/yargs");
+const { hideBin } = require("yargs/helpers");
+const { validate } = require("doc-detective-common");
+const path = require("path");
+const fs = require("fs");
+const { spawn } = require("child_process");
+
+exports.setArgs = setArgs;
+exports.setConfig = setConfig;
+exports.outputResults = outputResults;
+exports.spawnCommand = spawnCommand;
+
+// Define args
+function setArgs(args) {
+  if (!args) return {};
+  let argv = yargs(hideBin(args))
+    .option("config", {
+      alias: "c",
+      description: "Path to a `config.json` file.",
+      type: "string",
+    })
+    .option("input", {
+      alias: "i",
+      description:
+        "Path to test specifications and documentation source files. May be paths to specific files or to directories to scan for files.",
+      type: "string",
+    })
+    .option("output", {
+      alias: "o",
+      description:
+        "Path of the directory in which to store the output of Doc Detective commands.",
+      type: "string",
+    })
+    .option("setup", {
+      description:
+        "Path to test specifications to perform before those specified by `input`. Useful for setting up testing environments.",
+      type: "string",
+    })
+    .option("cleanup", {
+      description:
+        "Path to test specifications to perform after those specified by input. Useful for cleaning up testing environments.",
+      type: "string",
+    })
+    .option("recursive", {
+      alias: "r",
+      description:
+        "Boolean.  If true searches input, setup, and cleanup paths recursively for test specificaions and source files. Defaults to `true`.",
+      type: "string",
+    })
+    .option("logLevel", {
+      alias: "l",
+      description:
+        "Detail level of logging events. Accepted values: silent, error, warning, info (default), debug",
+      type: "string",
+    })
+    .help()
+    .alias("help", "h").argv;
+
+  return argv;
+}
+
+// Override config values based on args
+function setConfig(config, args) {
+  // If no args, return config
+  if (!args) return config;
+
+  // Load config from file
+  if (args.config) {
+    const configPath = path.resolve(args.config);
+    configContent = require(configPath);
+    // Validate config
+    const validation = validate("config_v2", configContent);
+    if (validation.valid) {
+      config = configContent;
+    } else {
+      // Output validation errors
+      console.error("Invalid config file:");
+      validation.errors.forEach((error) => {
+        console.error(error);
+      });
+      process.exit(1);
+    }
+  }
+
+  // Override config values
+  if (args.input) config.input = args.input;
+  if (args.output) config.output = args.output;
+  if (args.recursive) config.recursive = args.recursive;
+  if (args.logLevel) config.logLevel = args.logLevel;
+  if ((args.setup || args.cleanup  || args.input || args.output ) && !config.runTests) config.runTests = {};
+  if (args.input) config.runTests.input = args.input;
+  if (args.output) config.runTests.output = args.output;
+  if (args.setup) config.runTests.setup = args.setup;
+  if (args.cleanup) config.runTests.cleanup = args.cleanup;
+
+  // Validate config
+  const validation = validate("config_v2", config);
+  if (!validation.valid) {
+    // Output validation errors
+    console.error("Invalid config.");
+    validation.errors.forEach((error) => {
+      console.error(error);
+    });
+    process.exit(1);
+  }
+
+  return config;
+}
+
+async function outputResults(config, path, results) {
+  let data = JSON.stringify(results, null, 2);
+  fs.writeFile(path, data, (err) => {
+    if (err) throw err;
+  });
+  console.log(`See results at ${path}`);
+}
+
+// Perform a native command in the current working directory.
+async function spawnCommand(cmd, args) {
+  // Split command into command and arguments
+  if (cmd.includes(" ")) {
+    const cmdArray = cmd.split(" ");
+    cmd = cmdArray[0];
+    cmdArgs = cmdArray.slice(1);
+    // Add arguments to args array
+    if (args) {
+      args = cmdArgs.concat(args);
+    } else {
+      args = cmdArgs;
+    }
+  }
+
+  const runCommand = spawn(cmd, args);
+
+  // Capture stdout
+  let stdout = "";
+  for await (const chunk of runCommand.stdout) {
+    stdout += chunk;
+  }
+  // Remove trailing newline
+  stdout = stdout.replace(/\n$/, "");
+
+  // Capture stderr
+  let stderr = "";
+  for await (const chunk of runCommand.stderr) {
+    stderr += chunk;
+  }
+  // Remove trailing newline
+  stderr = stderr.replace(/\n$/, "");
+
+  // Capture exit code
+  const exitCode = await new Promise((resolve, reject) => {
+    runCommand.on("close", resolve);
+  });
+
+  return { stdout, stderr, exitCode };
 }

package/test/artifacts/cleanup.spec.json

@@ -0,0 +1,19 @@
+{
+    "id": "cleanup",
+    "tests": [
+      {
+        "steps": [
+          {
+            "action": "setVariables",
+            "path": ".env"
+          },
+          {
+            "action": "runShell",
+            "command": "echo",
+            "args": ["cleanup"]
+          }
+        ]
+      }
+    ]
+  }
+