testaro 74.2.3 → 75.0.0

package/LICENSE

@@ -2,6 +2,8 @@ MIT License
 
 © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.
 © 2025–2026 Jonathan Robert Pool.
+© 2025 Juan S. Casado.
+© 2026 Jeff Witt.
 
 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:
 

package/README.md

@@ -2,17 +2,15 @@
 
 Ensemble testing for web accessibility
 
-## Breaking change notice
+## Breaking change notices
 
-Version 68.0.0 introduced major breaking changes.
+Version 75.0.0 introduced a breaking change in the methods for making screenshots of web pages.
 
-Any application that has successfully relied on version 67.1.0 is likely to fail if it updates the `testaro` dependency to version 68.0.0 or later. To prevent such failures, pin `testaro` to version 67.1.0 in your `package.json` file.
-
-Revision of this `README` document to reflect the latest version is in progress but is incomplete.
+Version 68.0.0 introduced a breaking change in the format of reports.
 
 ## Purposes
 
-Testaro is an application that performs ensemble testing of web pages, primarily for accessibility.
+Testaro is an application that performs ensemble testing of web pages for accessibility, usability, and conformity to HTML and CSS specifications.
 
 The purposes of Testaro are to:
 
@@ -28,20 +26,20 @@ Testaro is described in two papers:
 
 ## Functionality
 
-Testaro performs tasks defined by a _job_. Typically, a job identifies the URL of a web page and asks Testaro to call an ensemble of tools to test the page. Testaro adds the results of the testing to the job, thereby converting the job into a _report_.
+Testaro performs tasks defined by a _job_. Typically, a job identifies the URL of a web page and asks Testaro to call an ensemble of tools to test the page. Testaro adds the results of the testing to the job, thereby converting the job to a _report_.
 
 Testaro can be given a job to perform, in which case it performs the job, delivers the report, and quits.
 
 Alternatively, testaro can run as a daemon, polling a server or a directory for new jobs and performing them when they are provided or when they appear in the directory.
 
-A practical application that leverages Testaro will use other software to prepare jobs, schedule them, post-process the reports as needed, and manage the report files. Some utilities for such purposes can be found in the [Testilo project](https://www.npmjs.com/package/testilo). One application that leverages Testaro for a web service is [Kilotest](https://github.com/jrpool/kilotest).
+A practical application that leverages Testaro will use other software to prepare jobs, schedule them, post-process the reports as needed, and manage the report files. Some utilities for such purposes can be found in the [Testilo project](https://www.npmjs.com/package/testilo). One application that leverages Testaro for a web service is [Kilotest](https://www.npmjs.com/package/@jrpool/kilotest).
 
 ## Dependencies
 
 Testaro uses:
 
 - [Playwright](https://playwright.dev/) to launch browsers, perform user actions in them, and perform tests
-- [playwright-extra](https://www.npmjs.com/package/playwright-extra) and [puppeteer-extra-plugin-stealth](https://www.npmjs.com/package/puppeteer-extra-plugin-stealth) to make a Playwright-controlled browser more indistinguishable from a human-operated browser and thus make their requests more likely to succeed
+- [playwright-extra](https://www.npmjs.com/package/playwright-extra) and [puppeteer-extra-plugin-stealth](https://www.npmjs.com/package/puppeteer-extra-plugin-stealth) to make a Playwright-controlled browser more indistinguishable from a human-operated browser and thus make its requests more likely to succeed
 - [playwright-dompath](https://www.npmjs.com/package/playwright-dompath) to retrieve XPaths of elements
 - [BlazeDiff](https://blazediff.dev/) to measure motion
 - [dotenv](https://www.npmjs.com/package/dotenv) to load environment variables
@@ -68,16 +66,16 @@ As shown, Testaro is not only an integrator but also one of the integrated tools
 The main concepts of Testaro are:
 
 - `job`: a document that tells Testaro what to do.
-- `act`: one step in a job
+- `act`: one step in a job.
 - `report`: a job that Testaro has added results to.
-- `tool`: one of the testing applications in the ensemble that Testaro has created.
+- `tool`: one of the testing applications in the ensemble assembled by Testaro.
 - `rule`: a success or failure criterion defined by a tool (currently about 1300 across all tools).
 - `test`: the software that a tool uses to apply a rule.
 - `target`: a web page that a job tells Testaro to test.
-- `result`: the information that Testaro adds to a job to describe the test outcomes.
-- `native result`: the test outcomes of a tool in the native form of that tool.
-- `standard result`: the test outcomes of a tool in a uniform Testaro-defined form.
-- `catalog`: a collection of data on the HTML elements relevant to one or more tests.
+- `result`: the information that Testaro adds to a job to describe the outcomes of the tests of a tool.
+- `native result`: the outcomes of the tests of a tool in exactly or approximately the original form.
+- `standard result`: the outcomes of the tests of a tool in a uniform Testaro-defined form.
+- `catalog`: a collection of data on the HTML elements of a target relevant to one or more tests.
 
 ## System requirements
 
@@ -99,7 +97,7 @@ One way to cope with this prohibition is to configure Playwright and Puppeteer t
 - 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.
 
-Non-sandboxed browsers are less secure than sandboxed ones, particularly when there is no restriction on who can use Testaro and what web pages they can test with it.
+Non-sandboxed browsers are less secure than sandboxed ones, particularly when there is no restriction on who can use Testaro and what targets (web pages) they can test with it.
 
 ### Option B
 
@@ -115,13 +113,11 @@ EOF
 sudo sysctl --system
 ```
 
-This repository implements option B.
-
-## Installation
+This application implements option B.
 
-### As an independent application
+## Installation an independent application
 
-To install Testaro as an independent application, clone the [Testaro repository](https://github.com/jrpool/testaro). To ensure that the binary browsers of its Playwright dependency get installed, execute `(p)npx playwright install` after executing `(p)npm install`.
+To install Testaro as an independent application, rather than a dependency, clone the [Testaro repository](https://github.com/jrpool/testaro). To ensure that the binary browsers of its Playwright dependency get installed, execute `(p)npx playwright install` after executing `(p)npm install`.
 
 To update Testaro when it is an independent application, execute:
 
@@ -131,19 +127,13 @@ git pull
 (p)npm run deps
 ```
 
-### As a dependency
-
-You can make `testaro` a dependency in another application. As noted at the beginning of this file, the entry in `package.json` should be `"testaro": "67.1.0"` if your application has not been designed to work with version 68.0.0 or later.
-
 ## Environment configuration
 
 The `.env` file stores your decisions about the environment in which Testaro runs. The variables that can be defined there are documented in the `env.example` file.
 
 ## Jobs
 
-Jobs tell Testaro what and how to test.
-
-### Job example
+Jobs tell Testaro what to do.
 
 Here is a sample job, showing properties that you can set:
 
@@ -204,8 +194,8 @@ Here is a sample job, showing properties that you can set:
         }
       },
       which: 'qualWeb',
-      withNewContent: false,
-      rules: ['QW-BP25', 'QW-BP26']
+      withNewContent: false, // An argument required by this tool
+      rules: ['QW-BP25', 'QW-BP26'] // Which rules of the tool to test for
     }
   ]
 }
@@ -213,11 +203,11 @@ Here is a sample job, showing properties that you can set:
 
 The `device` property lets you choose among [about 125 devices recognized by Playwright](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json).
 
-There are 18 act types. They and their options are documented in the `etc` property of the [actSpecs.js](actSpecs.js) object. Documentation for the `actSpecs.js` file is located in the `actSpecs-doc.md` file.
+The act types and their options are documented in the `etc` property of the [actSpecs.js](actSpecs.js) object and in the [actSpecs-doc.md](actSpecs-doc.md) file.
 
-### Running jobs
+## Running jobs
 
-#### Job as an object
+### Job as an object
 
 An application can execute a job with:
 
@@ -231,35 +221,39 @@ doJob(job)
 });
 ```
 
-#### Job as a file
+### Job as a file
 
-#### Immediate execution
+Jobs can be stored as JSON files in the `todo` subdirectory of a directory identified by the `JOBDIR` environment variable. After Testaro performs such a job, Testaro moves the job file to the `done` subdirectory of the same directory and saves the report in the `raw` subdirectory of the directory identified by the `REPORTDIR` environment variable.
 
-A user can make Testaro execute a job from a file with a command like either of:
+### Immediate performance
+
+A user can make Testaro perform a job from a file with a command like either of:
 
 ```bash
 node call run
 node call run 250725T
 ```
 
-An application can watch a directory for jobs with::
+Testaro will find the first file in the `todo` subdirectory, or, if the second form of the command is used, the first file there whose name begins with the specified string.
+
+### Directory polling
+
+An application can poll the `todo` subdirectory for jobs with:
 
 ```javaScript
 const {dirWatch} = require('testaro/dirWatch');
 dirWatch(true, 300);
 ```
 
-A user can make Testaro watch a directory for jobs with::
+A user can make Testaro start to poll that subdirectory with:
 
 ```javaScript
 node call dirWatch true 300
 ```
 
-In both cases, the first argument of `dirWatch` tells Testaro whether to continue watching after performing one job, and the second argument tells Testaro how many secods to wait after not finding a job to perform before checking again.
+In both cases, the first argument of `dirWatch` tells Testaro whether to continue polling after performing one job, and the second argument tells Testaro how many seconds to wait after not finding a job to perform, before polling again.
 
-Testaro finds a file containing a job in the `todo` subdirectory of the `process.env.JOBDIR` directory and saves the report of that job in the `done/raw` subdirectory. In the `node call run` case, the job selected will be the first one whose file name begins with the argument of `run`, or the first one if that argument is absent.
-
-#### Job from a server
+### Server polling
 
 Testaro can poll a server for jobs to be performed. The server can act as the “controller” described in [How to run a thousand accessibility tests](https://medium.com/cvs-health-tech-blog/how-to-run-a-thousand-accessibility-tests-63692ad120c3). The server is responsible for preparing Testaro jobs, assigning them to Testaro agents, receiving reports back from those agents, and performing any further processing of the reports, including enhancement, storage, and disclosure to audiences. It can be any server reachable with a URL. That includes a server running on the same host as Testaro, with a URL such as `localhost:3000`.
 
@@ -273,7 +267,7 @@ The job request sent to the server can be a `POST` request, in which the `agentP
 
 Testaro will send the report as a `POST` request whose payload is a JSON object with two properties: `agentPW` (the password) and `report` (the report). However, if the environment does not contain a password, the payload is a JSON object containing only the report.
 
-An application can poll a server for jobs with:
+An application can make Testaro poll a server for jobs with:
 
 ```javaScript
 const {netWatch} = require('testaro/netWatch');
@@ -286,24 +280,22 @@ A user can make Testaro poll a server for jobs with:
 node call netWatch true 300 true
 ```
 
-The first argument of `netWatch` tells Testaro whether to continue polling after performing the first job. The second argument tells Testaro how many seconds to wait after receiving a no-jobs response. The third argument tells Testaro whether to be certificate-tolerant, i.e. to accept SSL certificates that fail verification against a list of certificate authorities (the default is `true`).
+The first argument of `netWatch` tells Testaro whether to continue polling after performing the first job. The second argument tells Testaro how many seconds to wait after receiving a no-jobs response before polling again. The third argument tells Testaro whether to be certificate-tolerant, i.e. to accept SSL certificates that fail verification against a list of certificate authorities (the default is `true`).
 
 ## Reports
 
 A report is a job with information about the results of the performance of the job inserted by Testaro into the job.
 
-### Whole-job insertions
+### Whole-job data
 
 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`: 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.
+- `catalog`: A collection of data about the HTML elements of the target that are relevant to any test failures
 
-#### Catalog
+Testaro inserts the `jobData` property into every job.
 
-Whenever a job requires any testing and requires the production of standard results, Testaro inserts a _catalog_ into the report before calling any of the testing tools. The catalog is an inventory of HTML elements in the DOM of the target.
+Testaro inserts the `catalog` property only into jobs that instruct Testaro to produce standard results. The catalog is an inventory of HTML elements in the DOM of the target.
 
 The `catalog` property has an object value. Here is an example:
 
@@ -330,9 +322,10 @@ The catalog is a mechanism for the integration of the tools. Most rule violation
 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.
+- `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-xpath` attributes, in the reported violations.
+- `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.
+- `axe`: It reports a selector for each element, and Testaro adds `data-xpath` attributes to all elements. Testaro finds each element in the page via its selector and uses the `data-xpath` attribute. When this fails, Testaro uses the `data-xpath` attribute if its complete value is included in the reported `node.html` value.
 - `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.
@@ -343,14 +336,14 @@ In some cases no catalog entry can be found. The reasons may include:
 - The element is inside a `noscript` element and therefore not considered an element in the DOM.
 - The violation is not ascribed to a single element.
 
-### Act insertions
+### Act data
 
-As Testaro performs the acts of a job, information about the results of each act is inserted into that act. For acts of type `test`, the added properties are:
+As Testaro performs the acts of a job, information about the result of each act is inserted into that act. For acts of type `test`, the added properties are:
 
 - `startTime`: When Testaro began to perform the act
 - `actualURL`: The tested URL (different from the target URL if the request was redirected)
 - `data`: Data generated by the tool
-- `result`: Results of the testing by the tool
+- `result`: Result of the testing by the tool
 
 The `result` property is an object with one or two (depending on the value of `standard`, as described above) subproperties:
 
@@ -453,7 +446,7 @@ In a previous version of the package, the tool operated on the page content when
 
 ### Nu Html Checker
 
-The `nuVal` and `nuVnu` tools perform the tests of the Nu Html Checker.
+The `nuVal` and `nuVnu` tools perform the tests of the Nu Html Checker. The `nuVal` tool is a remote service with an API. The `nuVnu` tool is installed as a dependency. A job can choose either one, or can try `nuVal` and if it fails then invoke `nuVnu`.
 
 Its `rules` argument is **not** an array of rule IDs, but instead is an array of rule _specifications_. A rule specification for `nuVal` or `nuVnu` is a string with the format `=ruleID` or `~ruleID`. The `=` prefix indicates that the rule ID is invariable. The `~` prefix indicates that the rule ID is variable, in which case the `ruleID` part of the specification is a matching regular expression, rather than the exact text of a message. This `rules` format arises from the fact that `nuVal` and `nuVnu` generate customized messages and do not accompany them with rule identifiers.
 
@@ -482,7 +475,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 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.
+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.
 
 ### Testaro
 
@@ -545,7 +538,7 @@ The Playwright “Receives Events” actionability check does **not** check whet
 
 ### Test prevention
 
-Test targets employ mechanisms to prevent scraping, multiple requests within a short time, automated form submission, and other automated actions. These mechanisms may interfere with testing. When a test act is prevented by a target, Testaro reports this prevention.
+Test targets employ mechanisms to prevent scraping, multiple requests within a short time, automated form submission, and other automated actions. These mechanisms may interfere with testing. When a test act is prevented, Testaro reports this prevention.
 
 Some targets prohibit the execution of alien scripts unless the client can demonstrate that it is the requester of the page. Failure to provide that evidence results in the script being blocked and an error message being logged, saying “Refused to execute a script because its hash, its nonce, or unsafe-inline does not appear in the script-src directive of the Content Security Policy”. This mechanism affects tools that insert scripts into a target in order to test it. To comply with this requirement, Testaro obtains a _nonce_ from the response that serves the target. Then the file that runs the tool adds that nonce to the script as the value of a `nonce` attribute when it inserts its script into the target.
 
@@ -615,7 +608,7 @@ From 12 February 2024 through 30 September 2025, contributors of code to Testaro
 
 ## Future work
 
-Future work on this project is being considered. Strategic recommendations for such work are recorded in the `UPGRADES.md` file.
+Future work contemplated for this project is described in its [issues](https://github.com/jrpool/testaro/issues) and also discussed in the [UPGRADES.md](UPGRADES.md) file.
 
 ## Etymology
 

package/actSpecs-doc.md

@@ -30,7 +30,10 @@ link: [
 ]
 ```
 
-The rule is an array with two elements: a string ('Click a link') describing the act and an object containing requirements for any act of type `link`.
+The rule is an array with two elements:
+
+- a string ('Click a link' in this case) describing the act
+- an object containing requirements for any act of the type identified by the key (`link` in this case).
 
 The requirement `which: [true, 'string', 'hasLength', 'substring of the link text']` specifies what is required for the `which` property of a `link`-type act. The requirement is an array.
 
@@ -52,6 +55,27 @@ The validity criterion named in item 2 may be any of these:
 - `'isWaitable'`: is `'url'`, `'title'`, or `'body'`
 - `'areStrings'`: is an array of strings
 
+## testaro tool
+
+The `tools.testaro` object has an `args` property specifying that a `testaro` test act may include an `args` property with an object value.
+
+If it does, the property names of the object value must be `testaro` rule IDs. Any property value must be an array of the positional arguments to be concatenated to the four default arguments (`page`, `report`, `actIndex`, and `withItems`) in the signature of the `reporter` function of each `testaro` rule.
+
+The rules of `testaro` that accept additional arguments are `autocomplete`, `buttonMenu`, `focInd`, and `hover`.
+
+## Screenshots
+
+An act of type `shoot` creates a full-page screenshot and converts it to a base64 encoding of a PNG image. With its arguments, you can decide:
+
+- Whether to mask certain elements (using a CSS selector)
+- The color type (grayscale, RGB, grayscale alpha, or RGBA)
+- What action to take to dispose of the base64 string:
+  - return it to the `shoot` act and save it in the result of the act (`return`)
+  - concatenate it to an `images` array in the report and return its index in the array (`report`)
+  - save it as a file in the temporary directory and return the file path (`file`)
+
+  Both the `return` and the `report` actions save the base64 string in the report, but in different places. The `file` action would permit you to create a custom act that retrieves and uses the image without the image being added to the report.
+
 ## License
 
 © 2026 Jonathan Robert Pool.

package/actSpecs.js

@@ -45,6 +45,7 @@ exports.actSpecs = {
       {
         target: [false, 'object', '', 'target different from target of the job'],
         browserID: [false, 'string', 'isBrowserID', 'browser type different from browserID of the job'],
+        shoot: [false, 'object', '', 'if screenshot to be made, exclusionSelector, colorType, and action'],
         what: [false, 'string', 'hasLength', 'comment']
       }
     ],
@@ -123,10 +124,11 @@ exports.actSpecs = {
       }
     ],
     shoot: [
-      'Save a full-page screenshot to <tmpdir>/testaro-shoot-<which>.png',
+      'Create and dispose of a full-page screenshot as a base-64-encoded PNG',
       {
-        which: [true, 'string', 'hasLength', 'screenshot label, used in the filename'],
-        exclusion: [false, 'string', 'hasLength', 'CSS selector for an element to mask'],
+        exclusionSelector: [false, 'string', 'hasLength', 'CSS selector for an element to mask'],
+        colorType: [false, 'number', '', '0=grayscale, 2=RGB, 4=grayscale alpha, 6=RGBA'],
+        action: [true, 'string', 'hasLength', 'disposition: return, report, file'],
         what: [false, 'string', 'hasLength', 'comment']
       }
     ],
@@ -208,7 +210,7 @@ exports.actSpecs = {
       {
         withItems: [true, 'boolean', '', 'itemize'],
         stopOnFail: [true, 'boolean', '', 'whether testing is to stop after first failure'],
-        args: [false, 'object', 'areArrays', 'extra args (object; property names are rule IDs and values are arrays of additional argument values ({autocomplete: [["first name", "forename", "given name"], ["last name", "surname", "family name"], ["email"]], buttonMenu: [], focInd: [false, 250], hover: [20]}) by default'],
+        args: [false, 'object', 'areArrays', 'extra arguments of rules taking any']
       }
     ],
     wave: [

package/package.json

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

package/procs/catalog.js

@@ -25,7 +25,6 @@
 
 // Module to close and launch browsers.
 const {browserClose, launch} = require('./launch');
-const {getXPathCatalogIndex} = require('./xPath');
 
 // FUNCTIONS
 

package/procs/dateTime.js

@@ -32,5 +32,7 @@ exports.dateOf = timeStamp => {
     return null;
   }
 };
-// Returns a string representing the date and time.
-exports.nowString = () => (new Date()).toISOString().slice(2, 16);
+// Returns a human-friendly representation of the current date and time.
+const nowString = exports.nowString = () => (new Date()).toISOString().slice(2, 16);
+// Returns a compact representation of the current date and time.
+exports.nowStamp = () => nowString().replace(/[:-]/g, '');

package/procs/doActs.js

@@ -289,13 +289,14 @@ exports.doActs = async report => {
       }
       // Otherwise, if the act is a launch:
       else if (type === 'launch') {
-        // Launch a browser, navigate to a page, and add the result to the act.
+        // Launch a browser, navigate, optionally make a screenshot, and add the result to the act.
         page = await launch({
-          tempReport,
+          report: tempReport,
           actIndex,
           tempBrowserID: getActBrowserID(tempReport, actIndex),
           tempURL: getActTargetURL(tempReport, actIndex),
-          xPathNeed: 'none'
+          xPathNeed: 'none',
+          shoot: act.shoot
         });
         // If this failed:
         if (! page) {
@@ -641,11 +642,17 @@ exports.doActs = async report => {
           }
           // 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};
+            const {exclusionSelector, colorType, action} = act;
+            // Make and dispose of a full-page screenshot.
+            const shotInfo = await shoot(page, tempReport, {
+              exclusion: exclusionSelector ? page.locator(exclusionSelector) : null,
+              colorType: [0, 2, 4, 6].includes(colorType) ? colorType : null,
+              action: ['return', 'report', 'file'].includes(action) ? action : 'report'
+            });
+            // Add the PNG base-64 encoding, image index, or file path to the act result.
+            act.result = shotInfo !== ''
+            ? {success: true, shotInfo}
+            : {success: false, prevented: true};
           }
           // Otherwise, if the act is a move:
           else if (moves[type]) {

package/procs/launch.js

@@ -16,7 +16,6 @@
 
 // IMPORTS
 
-// Module to handle errors.
 const {addError} = require('./error');
 const headedBrowser = process.env.HEADED_BROWSER === 'true';
 // Two flavors of Playwright:

package/procs/shoot.js

@@ -6,57 +6,35 @@
 
 /*
   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).
+  Manages the production and disposition of screenshots of a page.
 */
 
 // IMPORTS
 
 // Shared configuration for timeout multiplier.
 const {applyMultiplier} = require('./config');
+const {nowStamp} = require('./dateTime');
 const fs = require('fs/promises');
 const path = require('path');
 const {PNG} = require('pngjs');
 
 // 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;
+// Returns a probably unique file name.
+const randomFileName = (suffixLength = 3) => {
+  const fileName = `${nowStamp()}-${Math.random().toString(36).slice(2, 2 + suffixLength)}`;
+  return fileName;
 };
-
 // Creates and returns a screenshot.
-const screenShot = async (page, exclusion = null) => {
+const screenShot = async (page, exclusionLocator = null) => {
   const options = {
     fullPage: true,
     omitBackground: true,
+    scale: 'css',
     timeout: applyMultiplier(4000)
   };
-  if (exclusion) {
-    options.mask = [exclusion];
+  if (exclusionLocator) {
+    options.mask = [exclusionLocator];
   }
   // Make and return a screenshot as a buffer.
   return await page.screenshot(options)
@@ -65,28 +43,55 @@ const screenShot = async (page, exclusion = null) => {
     return '';
   });
 };
-exports.shoot = async (page, label, tmpDir, options = {}) => {
-  const exclusion = options.exclusion || null;
-  const dir = options.dir || tmpDir;
+// Creates and disposes of the PNG of a screenshot.
+exports.shoot = async (page, report, {
+  // Playwright locator of a mask.
+  exclusionSelector = null,
+  // Color fidelity: 0 (grayscale), 2 (RGB), 4 (grayscale alpha), 6 (RGBA).
+  colorType = 0,
+  // Disposition: return, report, file.
+  action = 'return'
+} = {}) => {
   // Make and get a screenshot as a buffer.
-  let shot = await screenShot(page, exclusion);
+  let shot = await screenShot(page, exclusionSelector ? page.locator(exclusionSelector) : null);
   // If it succeeded:
   if (shot.length) {
     // Get the screenshot as an object representation of a PNG image.
     let png = PNG.sync.read(shot);
     shot = null;
-    const pngBuffer = PNG.sync.write(png);
+    // Convert the PNG object to a buffer, applying the specified color type.
+    const pngBuffer = PNG.sync.write(png, {colorType});
     png = null;
     // Force garbage collection if available and if --expose-gc was a node option.
     if (global.gc) {
       global.gc();
     }
-    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.
-    return pngPath;
+    // Convert the buffer to a base64 string.
+    const base64 = pngBuffer.toString('base64');
+    // If the string is to be returned:
+    if (action === 'return') {
+      // Return it.
+      return base64;
+    }
+    // Otherwise, if it is to be appended to the report:
+    if (action === 'report') {
+      report.images ??= [];
+      // Append it to the images array in the report.
+      report.images.push(base64);
+      // Return the index of the added image in the array.
+      return report.images.length - 1;
+    }
+    // Otherwise, if it is to be saved in a file:
+    if (action === 'file') {
+      const fileName = randomFileName(4);
+      const filePath = path.join(report.jobData.tmpDir, fileName);
+      // Save it in a file.
+      await fs.writeFile(filePath, base64);
+      // Return the file name.
+      return fileName;
+    }
+    // Otherwise, i.e. if the action is invalid, return this.
+    return '';
   }
   // Otherwise, i.e. if it failed:
   else {

package/testaro/adbID.js

@@ -22,7 +22,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, catalog, withItems) => {
+exports.reporter = async (page, report, _, withItems) => {
   const getBadWhat = element => {
     // Get the IDs in the aria-describedby attribute of the element.
     const IDs = element.getAttribute('aria-describedby').trim().split(/\s+/).filter(Boolean);
@@ -57,6 +57,6 @@ exports.reporter = async (page, catalog, withItems) => {
   };
   const whats = 'Elements have aria-describedby attributes with missing or invalid id values';
   return await doTest(
-    page, catalog, withItems, 'adbID', 'body [aria-describedby]', whats, 3, getBadWhat.toString()
+    page, report.catalog, withItems, 'adbID', 'body [aria-describedby]', whats, 3, getBadWhat.toString()
   );
 };

package/testaro/allCapStyle.js

@@ -20,7 +20,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, catalog, withItems) => {
+exports.reporter = async (page, report, _, withItems) => {
   const getBadWhat = element => {
     // Get the style declaration of the element.
     const styleDec = window.getComputedStyle(element);
@@ -46,6 +46,6 @@ exports.reporter = async (page, catalog, withItems) => {
   const selector = 'body, body *:not(style, script, svg)';
   const whats = 'Elements have an all-capital text transformation style';
   return await doTest(
-    page, catalog, withItems, 'allCapStyle', selector, whats, 0, getBadWhat.toString()
+    page, report.catalog, withItems, 'allCapStyle', selector, whats, 0, getBadWhat.toString()
   );
 };