testaro 73.0.0 → 74.0.0

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/package.json

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

package/procs/doActs.js

@@ -20,6 +20,9 @@ const {getNonce, goTo, launch, wait} = require('./launch');
 const {tools} = require('./job');
 const {fork} = require('child_process');
 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');
@@ -636,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/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
@@ -18,6 +29,22 @@ 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;
+};
+
 // Creates and returns a screenshot.
 const screenShot = async (page, exclusion = null) => {
   const options = {
@@ -35,9 +62,11 @@ const screenShot = async (page, exclusion = null) => {
     return '';
   });
 };
-exports.shoot = async (page, index, tmpDir) => {
+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.
@@ -49,8 +78,8 @@ exports.shoot = async (page, index, tmpDir) => {
     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/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