testaro 72.5.1 → 74.0.0

package/AGENTS.md

@@ -27,7 +27,7 @@
 
 ## License
 
-© 2025 Jonathan Robert Pool.
+© 2025–2026 Jonathan Robert Pool.
 
 Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
 at the project root for details.

package/CLAUDE.md

@@ -114,3 +114,12 @@ Long comments are not broken into multiple lines per paragraph.
 | `tests/testaro.js` | `allRules` registry for the testaro tool |
 | `testaro/<ruleID>.js` | One file per Testaro rule |
 | `validation/validateTest.js` | Core validation harness |
+
+## License
+
+© 2026 Jonathan Robert Pool.
+
+Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
+at the project root for details.
+
+SPDX-License-Identifier: MIT

package/CONTRIBUTING.md

@@ -69,7 +69,7 @@ From 12 February 2024 through 30 September 2025, contributors of code to Testaro
 ## License
 
 © 2023–2024 CVS Health and/or one of its affiliates. All rights reserved.
-© 2025 Jonathan Robert Pool.
+© 2025–2026 Jonathan Robert Pool.
 
 Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
 at the project root for details.

package/README.md

@@ -83,13 +83,11 @@ The main concepts of Testaro are:
 
 ### Operating system and Node.js version
 
-Testaro can be installed under a MacOS, Windows, Debian, or Ubuntu operating system.
-
-Testaro is tested with the latest long-term-support version of [Node.js](https://nodejs.org/en/).
+Testaro can be installed under a MacOS, Windows, Debian, or Ubuntu operating system with the latest long-term-support version of [Node.js](https://nodejs.org/en/).
 
 ### Browser security
 
-Testaro is configured so that, when Playwright or Puppeteer (a dependency of Playwright and of some tools, including QualWeb) launches a `chromium` browser, the browser is [sandboxed](https://www.geeksforgeeks.org/ethical-hacking/what-is-browser-sandboxing/) for improved security. That is the default for Playwright and Puppeteer, and Testaro does not override that default. The host must therefore permit sandboxed browsers.  If you try to run Testaro on a host that prohibits sandboxed browsers, each attempted launch of a `chromium` browser will throw an error with a message complaining about the unavailability of a sandbox.
+Testaro is configured so that, when Playwright or Puppeteer (a dependency of Playwright and of some tools, including QualWeb) launches a `chromium` browser, the browser is [sandboxed](https://www.geeksforgeeks.org/ethical-hacking/what-is-browser-sandboxing/) for improved security. That is the default for Playwright and Puppeteer, and Testaro does not override that default. The host must therefore permit sandboxed browsers. If you try to run Testaro on a host that prohibits sandboxed browsers, each attempted launch of a `chromium` browser will throw an error with a message complaining about the unavailability of a sandbox.
 
 In some operating systems a sandboxed browser requires an [unprivileged user namespace](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces). In one case, a `…userns.conf` file in the `/etc/sysctl.d` directory with the content `kernel.apparmor_restrict_unprivileged_userns = 1` prohibits unprivileged user namespaces and thereby makes sandboxed browsers unlaunchable.
 
@@ -97,7 +95,7 @@ In some operating systems a sandboxed browser requires an [unprivileged user nam
 
 One way to cope with this prohibition is to configure Playwright and Puppeteer to launch `chromium` non-sandboxed. In both cases, launch arguments `'--no-sandbox'` and `'--disable-setuid-sandbox'` are available to specify this.
 
-- For Playwright, `'--no-sandbox'` and `'--disable-setuid-sandbox'` is added to the arguments of `browserOptionArgs.push` in the Testaro `run.js` file.
+- For Playwright, `'--no-sandbox'` and `'--disable-setuid-sandbox'` are added to the arguments of `browserOptionArgs.push` in the Testaro `run.js` file.
 - For the `qualWeb` tool, this is done in the Testaro `tests/qualweb.js` file, where the `qualWeb.start` method is called with an options argument. Its `args` array property is modified to include `'--no-sandbox'` and `'--disable-setuid-sandbox'`.
 - The `ibm` tool, too, can launch a Puppeteer `chromium` browser, if page content instead of a Playwright page is passed to the `accessibilityChecker.getCompliance` method, or if the implementation of the tool is changed in the future. For anticipation of such a case, the Testaro `aceconfig.js` file is modified. That file defines a `module.exports` object with a `puppeteerArgs` property, and, `--no-sandbox` and `--disable-setuid-sandbox` are added to its array value.
 
@@ -105,7 +103,7 @@ Non-sandboxed browsers are less secure than sandboxed ones, particularly when th
 
 ### Option B
 
-The `chromium` configuration was left unchanged, but the operating system is configured to permit a sandboxed browser to be launched. In one case, this is implemented with:
+Another solution is to leave the `chromium` configuration unchanged, but configure the operating system to permit a sandboxed browser to be launched. In one case, this is implemented with:
 
 ```bash
 sudo sysctl -w kernel.unprivileged_userns_clone=1
@@ -117,6 +115,8 @@ EOF
 sudo sysctl --system
 ```
 
+This repository implements option B.
+
 ## Installation
 
 ### As an independent application
@@ -214,7 +214,7 @@ There are 18 act types. They and their options are documented in the `etc` prope
 
 #### Job as an object
 
-An application can execute a job with::
+An application can execute a job with:
 
 ```javascript
 const {doJob} = require('testaro/run');
@@ -291,8 +291,8 @@ A report is a job with information about the results of the performance of the j
 
 As Testaro performs a job, information about the job as a whole is inserted into the job. That information is organized into one or two properties:
 
-- `jobData`: Miscellaneous facts about the completed job
-- `catalog`: A collection of data about the elements on the target that are relevant to any test failures
+- `jobData`: Facts about the performance of the job
+- `catalog`: A collection of data about the HTML elements on the target that are relevant to any test failures
 
 Testaro inserts the `jobData` property into every job, but inserts the `catalog` property only into jobs that instruct Testaro to produce standard results.
 
@@ -327,7 +327,7 @@ Testaro uses the following techniques to make the tools calculate XPaths:
 - `alfa` and `aslint`: They report XPaths, so Testaro needs only to normalize them.
 - `ed11y`: Testaro adds it and a `window.getXPath` method to the page; when the tool reports an element, Testaro computes its XPath.
 - `wave`: It reports a selector for each element; Testaro finds each element in the page via its selector and executes `window.getXPath` on the element.
-- `axe`, `htmlcs`, `ibm`, `nuVal`, `nuVnu`, `qualWeb`: Testaro adds `data-xpath` attributes to all elements; the tools include code excerpts, with the `data-expath` attributes, in the reported violations.
+- `axe`, `htmlcs`, `ibm`, `nuVal`, `nuVnu`, `qualWeb`: Testaro adds `data-xpath` attributes to all elements; the tools include code excerpts, with the `data-xpath` attributes, in the reported violations.
 - `testaro`: Testaro designs each of its own tests to report element XPaths.
 
 By attaching a catalog entry to each reported element, Testaro allows an application that uses Testaro to tell users, for any particular HTML element, which tools ascribed violations of which rules to that element. An application could, for example, use a screenshot or a text-fragment link or could ask the user to paste the XPath into a browser developer tool.
@@ -477,7 +477,7 @@ Thus, when the `rules` argument is omitted, QualWeb will test for all of the rul
 
 The target can be provided to QualWeb either as HTML or as a URL. Experience indicates that the results can differ between these methods, with each method reporting some rule violations or some instances that the other method does not report. For at least some cases, more rules are reported violated when HTML is provided (`withNewItems: false`).
 
-QualWeb creates sandboxed Puppeteer pages to perform its tests on. Therefore, the host must permit sandboxed browsers to be launched. See the pertinent [Kilotest documentation](https://github.com/jrpool/kilotest/blob/main/SERVICE.md#browser-privileges) for information about the configuration of an Ubuntu Linux host for this purpose.
+QualWeb creates sandboxed Puppeteer pages to perform its tests on. Therefore, the host must permit sandboxed browsers to be launched. See the discussion above about browser security. Also see the pertinent [Kilotest documentation](https://github.com/jrpool/kilotest/blob/main/SERVICE.md#browser-privileges) for information about the configuration of an Ubuntu Linux host for this purpose.
 
 ### Testaro
 
@@ -571,7 +571,7 @@ Testaro normally performs tests with headless browsers. Some experiments appear
 
 ## Repository exclusions
 
-The files in the `temp` directory are presumed ephemeral and are not tracked by `git`.
+Any files in the `temp` or `tmp` directory are presumed ephemeral and are not tracked by `git`. Jobs create temporary files in subdirectories of `tmp` and delete those subdirectories on termination.
 
 ## Related work
 
@@ -588,6 +588,10 @@ Testilo contains procedures that reorganize report data by issue and by element,
 
 Report standardization could be performed by other software rather than by Testaro. That would require sending the original reports to the server. They are typically larger than standardized reports. Whenever users want only standardized reports, the fact that Testaro standardizes them eliminates the need to send the original reports anywhere.
 
+### Kilotest
+
+[Kilotest](https://www.npmjs.com/package/kilotest) is an application that offers a simplified interface to Testaro. At present it is [deployed as a public service](https://kilotest.com/).
+
 ## Code style
 
 The JavaScript code in this project generally conforms to the ESLint configuration file `.eslintrc.json`. However, the `htmlcs/HTMLCS.js` file implements an older version of JavaScript. Its style is regulated by the `htmlcs/.eslintrc.json` file.
@@ -617,7 +621,6 @@ Future work on this project is being considered. Strategic recommendations for s
 © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
 © 2025–2026 Jonathan Robert Pool.
 
-Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
-at the project root for details.
+Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file at the project root for details.
 
 SPDX-License-Identifier: MIT

package/VALIDATION.md

@@ -94,7 +94,7 @@ Preparing a PR:
 ## License
 
 © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
-© 2025 Jonathan Robert Pool.
+© 2025–2026 Jonathan Robert Pool.
 
 Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
 at the project root for details.

package/aceconfig.js

@@ -1,6 +1,6 @@
 /*
   © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
-  © 2025 Jonathan Robert Pool.
+  © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
   https://opensource.org/license/mit/ for details.

package/actSpecs-doc.md

@@ -51,3 +51,12 @@ The validity criterion named in item 2 may be any of these:
 - `'isTest'`: is the name of a tool
 - `'isWaitable'`: is `'url'`, `'title'`, or `'body'`
 - `'areStrings'`: is an array of strings
+
+## License
+
+© 2026 Jonathan Robert Pool.
+
+Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file
+at the project root for details.
+
+SPDX-License-Identifier: MIT

package/actSpecs.js

@@ -121,6 +121,14 @@ exports.actSpecs = {
         what: [true, 'string', 'hasLength', 'substring of option text content']
       }
     ],
+    shoot: [
+      'Save a full-page screenshot to <tmpdir>/testaro-shoot-<which>.png',
+      {
+        which: [true, 'string', 'hasLength', 'screenshot label, used in the filename'],
+        exclusion: [false, 'string', 'hasLength', 'CSS selector for an element to mask'],
+        what: [false, 'string', 'hasLength', 'comment']
+      }
+    ],
     state: [
       'Wait until the page reaches a load state',
       {

package/call.js

@@ -1,5 +1,6 @@
 /*
   © 2022–2024 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
   https://opensource.org/license/mit/ for details.
@@ -42,7 +43,7 @@ const rawDir = `${reportDir}/raw`;
 
 // FUNCTIONS
 
-// Fulfills a testing request.
+// Fulfills a request to perform a job.
 const callRun = async jobIDStart => {
   // Find the job.
   const jobDirFileNames = await fs.readdir(todoDir);
@@ -56,7 +57,7 @@ const callRun = async jobIDStart => {
     // Get it.
     const jobJSON = await fs.readFile(`${todoDir}/${jobFileName}`, 'utf8');
     let report = JSON.parse(jobJSON);
-    // Run it.
+    // Run the job.
     report = await doJob(report);
     // Archive it.
     await fs.rename(`${todoDir}/${jobFileName}`, `${jobDir}/done/${jobFileName}`);

package/env.example

@@ -26,7 +26,15 @@ JOBDIR=__placeholder__
 REPORTDIR=__placeholder__
 # Multiplier for time limits (normally 1).
 TIMEOUT_MULTIPLIER=1
-# Name of the directory at the project root used for temporary files.
-TMPDIRNAME=scratch
 # Whether to abort the job when any test act fork crashes (default false).
 ABORT_ASSERTIVELY=false
+
+## License
+
+# © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
+# © 2026 Jeff Witt.
+# © 2026 Jonathan Robert Pool.
+
+# Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file at the project root for details.
+
+# SPDX-License-Identifier: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testaro",
-  "version": "72.5.1",
+  "version": "74.0.0",
   "description": "Run 1300 web accessibility tests from 10 tools and get a standardized report",
   "main": "index.js",
   "scripts": {

package/procs/config.js

@@ -1,5 +1,5 @@
 /*
-  © 2025 Jonathan Robert Pool.
+  © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
   https://opensource.org/license/mit/ for details.
@@ -12,16 +12,7 @@
   Shared configuration values for Testaro.
 */
 
-// Timeout multiplier from environment variable.
-// Set TIMEOUT_MULTIPLIER > 1 for slow networks/sites, < 1 for fast environments.
+// Amount to multiply by specified time limits (normally 1) to adapt to network/site speed.
 const timeoutMultiplier = Number.parseFloat(process.env.TIMEOUT_MULTIPLIER) || 1;
-
-// Helper to apply multiplier to a timeout value.
-// Use for navigation, interaction, and long-running operation timeouts.
-// Do NOT use for very short "fail-fast" timeouts (< 100ms).
-const applyMultiplier = (baseTimeout) => Math.round(baseTimeout * timeoutMultiplier);
-
-module.exports = {
-  timeoutMultiplier,
-  applyMultiplier
-};
+// Multiplies a time limit by the configured amount.
+exports.applyMultiplier = (baseTimeout) => Math.round(baseTimeout * timeoutMultiplier);

package/procs/doActs.js

@@ -1,5 +1,6 @@
 /*
   © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jeff Witt.
   © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or  https://opensource.org/license/mit/ for details.
@@ -18,9 +19,13 @@ const {addError} = require('./error');
 const {getNonce, goTo, launch, wait} = require('./launch');
 const {tools} = require('./job');
 const {fork} = require('child_process');
-const os = require('os');
 const {pruneCatalog} = require('./catalog');
+// Function to take a full-page screenshot.
+const {shoot} = require('./shoot');
+// Module to handle file system operations.
+const {applyMultiplier} = require('./config');
 const fs = require('fs/promises');
+const path = require('path');
 
 // CONSTANTS
 
@@ -51,8 +56,6 @@ const timeLimits = {
   testaro: 200 + Math.round(6 * waits / 1000),
   wave: 25
 };
-// Timeout multiplier.
-const timeoutMultiplier = Number.parseFloat(process.env.TIMEOUT_MULTIPLIER) || 1;
 // Abort aggressiveness.
 const abortAssertively = process.env.ABORT_ASSERTIVELY === 'true';
 
@@ -231,31 +234,11 @@ exports.doActs = async report => {
   let {acts} = tempReport;
   // Get the standardization specification.
   const standard = tempReport.standard || 'only';
-  const tmpDirs = [`${__dirname}/../${process.env.TMPDIRNAME || 'scratch'}`, os.tmpdir(), '/tmp'];
-  let tmpDir = null;
-  // For each potential temporary directory:
-  for (const tmpDirAlternative of tmpDirs) {
-    try {
-      // Verify that it is writable.
-      await fs.access(tmpDirAlternative, fs.constants.W_OK);
-      tmpDir = tmpDirAlternative;
-      break;
-    }
-    // If it is not:
-    catch(error) {
-      // Report this.
-      console.log(`ERROR: ${tmpDirAlternative} is not a writable directory for temporary reports`);
-    }
-  }
-  // If no writable temporary directory was found:
-  if (! tmpDir) {
-    // Report this.
-    console.log('ERROR: No writable temporary directory was found; quitting');
-    // Quit.
-    process.exit(1);
-  }
+  // Get the path to a writable temporary directory.
+  const {tmpDir} = report.jobData;
+  let reportPath;
   // Get a path for temporary reports.
-  const reportPath = `${tmpDir}/${tempReport.id}.json`;
+  reportPath = path.join(tmpDir, `${tempReport.id}.json`);
   // Initialize the count of completed acts.
   let actCount = 0;
   // For each act in the temporary report:
@@ -332,7 +315,7 @@ exports.doActs = async report => {
         // Save a copy of the temporary report, which the child process will read.
         await fs.writeFile(reportPath, tempReportJSON);
         let timedOut = false;
-        const limitMs = timeoutMultiplier * 1000 * (timeLimits[act.which] || 15);
+        const limitMs = applyMultiplier(1000 * (timeLimits[act.which] || 15));
         const actResult = await new Promise(resolve => {
           let closed = false;
           // Create a child process to perform the act.
@@ -656,6 +639,14 @@ exports.doActs = async report => {
               act.result.success = false;
             });
           }
+          // Otherwise, if the act is a screenshot:
+          else if (type === 'shoot') {
+            const exclusion = act.exclusion ? page.locator(act.exclusion) : null;
+            const pngPath = await shoot(page, act.which, {exclusion});
+            act.result = pngPath
+              ? {success: true, path: pngPath}
+              : {success: false, prevented: true};
+          }
           // Otherwise, if the act is a move:
           else if (moves[type]) {
             const selector = typeof moves[type] === 'string' ? moves[type] : act.what;

package/procs/job.js

@@ -181,7 +181,8 @@ exports.isValidJob = job => {
       executionTimeStamp,
       target,
       sources,
-      acts
+      acts,
+      jobData
     } = job;
     // Return an error for the first missing or invalid property.
     if (! id || typeof id !== 'string') {
@@ -260,6 +261,12 @@ exports.isValidJob = job => {
         error: `Invalid act:\n${JSON.stringify(invalidAct, null, 2)}`
       };
     }
+    if (jobData && typeof jobData !== 'object') {
+      return {
+        isValid: false,
+        error: 'Bad job jobData'
+      };
+    }
     return {
       isValid: true
     };

package/procs/launch.js

@@ -1,5 +1,6 @@
 /*
   © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jeff Witt.
   © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or

package/procs/shoot.js

@@ -6,6 +6,17 @@
 /*
   shoot
   Makes and saves as a PNG buffer file a full-page screenshot and returns the file path.
+
+  Call shape:
+    shoot(page, label, options?)
+      label:   string|number used in the saved filename. Sanitized to
+               testaro-shoot-<safe>.png — characters outside [A-Za-z0-9._-]
+               collapse to '_', leading/trailing dots and underscores are
+               stripped, length is capped at 100, and an empty result becomes
+               'unnamed'.
+      options: optional object:
+        exclusion: a Playwright Locator to mask in the screenshot.
+        dir:       output directory (defaults to the OS temp dir).
 */
 
 // IMPORTS
@@ -13,16 +24,27 @@
 // Shared configuration for timeout multiplier.
 const {applyMultiplier} = require('./config');
 const fs = require('fs/promises');
-const os = require('os');
 const path = require('path');
 const {PNG} = require('pngjs');
 
-// CONSTANTS
-
-const tmpDir = os.tmpdir();
-
 // FUNCTIONS
 
+// Coerces a label into a filesystem-safe string. Runs of any character outside
+// [A-Za-z0-9._-] collapse to one underscore; leading and trailing dots and
+// underscores are stripped (no hidden files, no traversal); capped at 100
+// characters; falls back to 'unnamed' if nothing usable remains.
+const sanitizeLabel = (label) => {
+  const raw = String(label);
+  const cleaned = raw
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .replace(/^[._]+|[._]+$/g, '')
+    .slice(0, 100) || 'unnamed';
+  if (cleaned !== raw) {
+    console.log(`>> shoot: label sanitized from "${raw}" to "${cleaned}"`);
+  }
+  return cleaned;
+};
+
 // Creates and returns a screenshot.
 const screenShot = async (page, exclusion = null) => {
   const options = {
@@ -40,9 +62,11 @@ const screenShot = async (page, exclusion = null) => {
     return '';
   });
 };
-exports.shoot = async (page, index) => {
+exports.shoot = async (page, label, tmpDir, options = {}) => {
+  const exclusion = options.exclusion || null;
+  const dir = options.dir || tmpDir;
   // Make and get a screenshot as a buffer.
-  let shot = await screenShot(page);
+  let shot = await screenShot(page, exclusion);
   // If it succeeded:
   if (shot.length) {
     // Get the screenshot as an object representation of a PNG image.
@@ -54,8 +78,8 @@ exports.shoot = async (page, index) => {
     if (global.gc) {
       global.gc();
     }
-    const fileName = `testaro-shoot-${index}.png`;
-    const pngPath = path.join(tmpDir, fileName);
+    const fileName = `testaro-shoot-${sanitizeLabel(label)}.png`;
+    const pngPath = path.join(dir, fileName);
     // Save the PNG buffer.
     await fs.writeFile(pngPath, pngBuffer);
     // Return the result.

package/run.js

@@ -1,5 +1,6 @@
 /*
   © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jeff Witt.
   © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
@@ -15,19 +16,14 @@
 
 // IMPORTS
 
-// Module to perform acts.
 const {doActs} = require('./procs/doActs');
-// Module to keep secrets.
 require('dotenv').config({quiet: true});
-// Function to validate jobs.
 const {isValidJob} = require('./procs/job');
-// Module to create catalogs.
 const {getCatalog} = require('./procs/catalog');
-// Module to process dates and times.
 const {nowString} = require('./procs/dateTime');
-// Module to create browsers.
 const {chromium, webkit, firefox} = require('playwright-extra');
-// Module to evade automation detection.
+const fs = require('fs').promises;
+const os = require('os');
 const StealthPlugin = require('puppeteer-extra-plugin-stealth');
 chromium.use(StealthPlugin());
 webkit.use(StealthPlugin());
@@ -35,11 +31,51 @@ firefox.use(StealthPlugin());
 
 // FUNCTIONS
 
+// Returns an operating-system-compatible absolute path to a temporary directory.
+const getTmpDirPath = async jobName => {
+  let jobTmpDir = `${__dirname}/tmp/${jobName}`;
+  try {
+    // Ensure that a temporary directory exists.
+    await fs.mkdir(jobTmpDir, {recursive: true});
+  }
+  catch (error) {
+    console.log(`ERROR: Could not create temporary directory (${error.message})`);
+    jobTmpDir = null;
+  }
+  const tmpDirs = [os.tmpdir(), '/tmp'];
+  if (jobTmpDir) {
+    tmpDirs.unshift(jobTmpDir);
+  }
+  let tmpDir = null;
+  // For each potential temporary directory:
+  for (const tmpDirAlternative of tmpDirs) {
+    try {
+      // Verify that it is writable.
+      await fs.access(tmpDirAlternative, fs.constants.W_OK);
+      tmpDir = tmpDirAlternative;
+      // If it is, stop checking alternatives.
+      break;
+    }
+    // If it is not:
+    catch(error) {
+      // Report this and continue checking alternatives.
+      console.log(`ERROR: ${tmpDirAlternative} not writable for temporary files`);
+    }
+  }
+  // If no writable temporary directory was found:
+  if (! tmpDir) {
+    // Report this.
+    console.log('ERROR: No writable temporary directory was found');
+  }
+  // Return the directory path or a failure.
+  return tmpDir;
+};
 // Runs a job and returns a report.
 exports.doJob = async (job, opts = {}) => {
   // Initialize a report as a copy of the job.
   let report = JSON.parse(JSON.stringify(job));
-  const jobData = report.jobData = {};
+  report.jobData ??= {};
+  const {jobData} = report;
   // Get whether the job is valid and, if not, why not.
   const jobInvalidity = isValidJob(job);
   // If it is invalid:
@@ -54,9 +90,11 @@ exports.doJob = async (job, opts = {}) => {
   else {
     // Report this.
     console.log(`Starting job ${job.id} (${job.target.what})`);
+    const tmpDir = await getTmpDirPath(job.id);
     // Add initialized job data to the report.
     const startTime = new Date();
     report.jobData = {
+      tmpDir,
       startTime: nowString(),
       endTime: '',
       elapsedSeconds: 0,
@@ -89,6 +127,8 @@ exports.doJob = async (job, opts = {}) => {
     }
     // Perform the acts and revise the report.
     report = await doActs(report, opts);
+    // Delete the temporary directory.
+    await fs.rm(tmpDir, {recursive: true, force: true});
     // Add the end time and duration to the report.
     const endTime = new Date();
     report.jobData.endTime = nowString();

package/testaro/motion.js

@@ -16,18 +16,13 @@
 
 const {getXPathCatalogIndex} = require('../procs/xPath');
 const fs = require('fs/promises');
-const os = require('os');
 const blazediff = require('@blazediff/core').diff;
 const {PNG} = require('pngjs');
 
-// CONSTANTS
-
-const tmpDir = os.tmpdir();
-
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (_, catalog) => {
+exports.reporter = async (_0, catalog, _1, tmpDir) => {
   // Initialize the totals and standard instances.
   const data = {};
   const totals = [0, 0, 0, 0];

package/testaro/shoot0.js

@@ -15,9 +15,9 @@ const {shoot} = require('../procs/shoot');
 // FUNCTIONS
 
 // Makes and saves the first screenshot.
-exports.reporter = async page => {
+exports.reporter = async (page, _, __, tmpDir) => {
   // Make and save the screenshot.
-  const pngPath = await shoot(page, 0);
+  const pngPath = await shoot(page, 0, tmpDir);
   // Return whether the screenshot was prevented.
   return {
     data: {

package/testaro/shoot1.js

@@ -11,23 +11,18 @@
 // IMPORTS
 
 const fs = require('fs/promises');
-const os = require('os');
 const {shoot} = require('../procs/shoot');
 
-// CONSTANTS
-
-const tmpDir = os.tmpdir();
-
 // FUNCTIONS
 
 // Make and save the second screenshot.
-exports.reporter = async page => {
+exports.reporter = async (page, _0, _1, tmpDir) => {
   const tempFileNames = await fs.readdir(tmpDir);
   let pngPath = '';
   // If there is a shoot0 file:
   if (tempFileNames.includes('testaro-shoot-0.png')) {
     // Make and save the screenshot.
-    pngPath = await shoot(page, 1);
+    pngPath = await shoot(page, 1, tmpDir);
   }
   // Return whether the screenshot was prevented.
   return {

package/tests/nuVnu.js

@@ -16,15 +16,11 @@
 
 // IMPORTS
 
-const fs = require('fs/promises');
-const os = require('os');
-const {vnu} = require('vnu-jar');
 const {curate, getContent} = require('../procs/nu');
 const {getAttributeXPath, getXPathCatalogIndex} = require('../procs/xPath');
-
-// CONSTANTS
-
-const tmpDir = os.tmpdir();
+const fs = require('fs/promises');
+const path = require('path');
+const {vnu} = require('vnu-jar');
 
 // FUNCTIONS
 
@@ -58,7 +54,7 @@ exports.reporter = async (page, report, actIndex) => {
     const {testTarget} = content;
     // If it was obtained and contains a test target:
     if (testTarget) {
-      const pagePath = `${tmpDir}/nuVnu-page-${report.id}.html`;
+      const pagePath = path.join(report.jobData.tmpDir, 'nuVnu-page.html');
       // Save the test target in a temporary file.
       await fs.writeFile(pagePath, testTarget);
       let nuData;

package/tests/testaro.js

@@ -16,7 +16,7 @@
 // IMPORTS
 
 // Shared configuration for timeout multiplier.
-const {timeoutMultiplier} = require('../procs/config');
+const {applyMultiplier} = require('../procs/config');
 const {launch} = require('../procs/launch');
 
 // CONSTANTS
@@ -28,6 +28,7 @@ const allRules = [
     what: 'first page screenshot',
     contaminates: false,
     needsAccessibleName: false,
+    needsTmpDir: true,
     timeOut: 5,
     defaultOn: true
   },
@@ -332,6 +333,7 @@ const allRules = [
     what: 'second page screenshot',
     contaminates: false,
     needsAccessibleName: false,
+    needsTmpDir: true,
     timeOut: 5,
     defaultOn: true
   },
@@ -340,6 +342,7 @@ const allRules = [
     what: 'motion without user request, measured across tests',
     contaminates: false,
     needsAccessibleName: false,
+    needsTmpDir: true,
     timeOut: 5,
     defaultOn: true
   },
@@ -569,6 +572,11 @@ exports.reporter = async (page, report, actIndex) => {
       }
       // Initialize an argument array for the reporter.
       const ruleArgs = [page, report.catalog, withItems];
+      // If the rule needs a temporary directory:
+      if (rule.needsTmpDir) {
+        // Add its path to the argument array.
+        ruleArgs.push(report.jobData.tmpDir);
+      }
       // If the rule has extra arguments:
       if (argRules?.includes(ruleResult.id)) {
         // Add them to the argument array.
@@ -578,7 +586,7 @@ exports.reporter = async (page, report, actIndex) => {
       let timer;
       try {
         // Apply a time limit to the test.
-        const timeLimit = 1000 * timeoutMultiplier * rule.timeOut;
+        const timeLimit = applyMultiplier(1000 * rule.timeOut);
         let timeout;
         // If the time limit expires during the test:
         timer = new Promise(resolve => {

package/validation/jobs/todo/240101T1300-shoot-example.json

@@ -0,0 +1,46 @@
+{
+  "id": "240101T1300-shoot-example",
+  "what": "Demonstrate the shoot action: full-page screenshots interleaved with scripted steps",
+  "strict": true,
+  "timeLimit": 30,
+  "acts": [
+    {
+      "type": "launch",
+      "which": "chromium",
+      "url": "https://example.edu/",
+      "what": "Chromium browser"
+    },
+    {
+      "type": "shoot",
+      "which": "before",
+      "what": "Snapshot the landing page before any interaction"
+    },
+    {
+      "type": "shoot",
+      "which": "before-masked",
+      "exclusion": "header",
+      "what": "Same view with the page header masked out"
+    },
+    {
+      "type": "test",
+      "which": "testaro",
+      "withItems": false,
+      "stopOnFail": true,
+      "rules": [
+        "y",
+        "bulk"
+      ]
+    },
+    {
+      "type": "shoot",
+      "which": "after-tests",
+      "what": "Snapshot the page after Testaro tests have run"
+    }
+  ],
+  "sources": {},
+  "standard": "only",
+  "observe": false,
+  "sendReportTo": "http://localhost:3007/api",
+  "timeStamp": "240101T1300",
+  "creationTimeStamp": "240101T1300"
+}

package/scratch/README.md

@@ -1,12 +0,0 @@
-# scratch
-
-This directory is used for temporary files produced during execution of jobs.
-
-## License
-
-© 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
-© 2025–2026 Jonathan Robert Pool.
-
-Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](../../LICENSE) file at the project root for details.
-
-SPDX-License-Identifier: MIT