testaro 60.4.0 → 60.5.0

package/procs/doTestAct.js

@@ -32,7 +32,8 @@
 
 // Module to perform file operations.
 const fs = require('fs/promises');
-const {launch} = require(`${__dirname}/../run`);
+//Modules to close and launch browsers.
+const {browserClose, launch} = require(`${__dirname}/../run`);
 // Module to set operating-system constants.
 const os = require('os');
 
@@ -60,7 +61,7 @@ const doTestAct = async () => {
   const act = report.acts[actIndex];
   // Get the tool name.
   const {which} = act;
-  // Launch a browser, navigate to the URL, and redefine the page export of the run module.
+  // Launch a browser, navigate to the URL, and update the page export of the run module.
   await launch(
     report,
     debug,
@@ -70,6 +71,8 @@ const doTestAct = async () => {
   );
   // If the launch aborted the job:
   if (report.jobData && report.jobData.aborted) {
+    // Close any existing browser.
+    await browserClose();
     // Save the revised report.
     const reportJSON = JSON.stringify(report);
     await fs.writeFile(reportPath, reportJSON);
@@ -78,37 +81,33 @@ const doTestAct = async () => {
   }
   // Otherwise, i.e. if the launch did not abort the job:
   else {
-    // Get the redefined page.
+    // Get the updated page.
     const {page} = require('../run');
     // If it exists:
     if (page) {
       try {
-        // If the page prevents the tool from testing:
-        if (page.prevented) {
-          // Report this.
-          process.send('ERROR: Page prevented testing');
-        }
-        // Otherwise, i.e. if the page permits testing:
-        else {
-          // Wait for the act reporter to perform the specified tests of the tool.
-          const actReport = await require(`../tests/${which}`).reporter(page, report, actIndex, 65);
-          // Add the data and result to the act.
-          act.data = actReport.data;
-          act.result = actReport.result;
-          // If the tool reported that the page prevented testing:
-          if (act.data && act.data.prevented) {
-            // Add prevention data to the job data.
-            report.jobData.preventions[which] = act.data.error;
-          }
-          const reportJSON = JSON.stringify(report);
-          // Save the revised report.
-          await fs.writeFile(reportPath, reportJSON);
-          // Send a completion message.
-          process.send('Act completed');
+        // Make the act reporter perform the specified tests of the tool.
+        const actReport = await require(`../tests/${which}`).reporter(page, report, actIndex, 65);
+        // Add the data and result to the act.
+        act.data = actReport.data;
+        act.result = actReport.result;
+        // If the tool reported that the page prevented testing:
+        if (act.data && act.data.prevented) {
+          // Add prevention data to the job data.
+          report.jobData.preventions[which] = act.data.error;
         }
+        // Close any existing browser.
+        await browserClose();
+        const reportJSON = JSON.stringify(report);
+        // Save the revised report.
+        await fs.writeFile(reportPath, reportJSON);
+        // Send a completion message.
+        process.send('Act completed');
       }
       // If the tool invocation failed:
       catch(error) {
+        // Close any existing browser.
+        await browserClose();
         // Save the revised report.
         const reportJSON = JSON.stringify(report);
         await fs.writeFile(reportPath, reportJSON);
@@ -126,8 +125,10 @@ const doTestAct = async () => {
       act.data.error = 'No page';
       // Add prevention data to the job data.
       report.jobData.preventions[which] = act.data.error;
-      // Save the revised report.
+      // Close any existing browser.
+      await browserClose();
       const reportJSON = JSON.stringify(report);
+      // Save the revised report.
       await fs.writeFile(reportPath, reportJSON);
       // Report this.
       const message = 'ERROR: No page';

package/procs/shoot.js

@@ -0,0 +1,51 @@
+/*
+  © 2025 Jonathan Robert Pool. All rights reserved.
+  Licensed under the MIT License. See LICENSE file for details.
+*/
+
+/*
+  shoot
+  Makes and saves as a PNG buffer file a full-page screenshot and returns the file path.
+*/
+
+// IMPORTS
+
+const fs = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const {PNG} = require('pngjs');
+const {screenShot} = require('./screenShot');
+
+// CONSTANTS
+
+const tmpDir = os.tmpdir();
+
+// FUNCTIONS
+
+exports.shoot = async (page, index) => {
+  // Make and get a screenshot as a buffer.
+  let shot = await screenShot(page);
+  // 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);
+    png = null;
+    // Force garbage collection if available and if --expose-gc was a node option.
+    if (global.gc) {
+      global.gc();
+    }
+    const fileName = `testaro-shoot-${index}.png`;
+    const pngPath = path.join(tmpDir, fileName);
+    // Save the PNG buffer.
+    await fs.writeFile(pngPath, pngBuffer);
+    // Return the result.
+    return pngPath;
+  }
+  // Otherwise, i.e. if it failed:
+  else {
+    // Return this.
+    return '';
+  }
+};

package/procs/tellServer.js

@@ -35,7 +35,7 @@ const agent = process.env.AGENT;
 
 // FUNCTIONS
 
-// Sends a notification to an observer.
+// Sends a notice to an observer.
 exports.tellServer = (report, messageParams, logMessage) => {
   const {serverID} = report.sources;
   const observerURL = typeof serverID === 'number' ? process.env[`NETWATCH_URL_${serverID}_OBSERVE`] : '';

package/procs/visChange.js

@@ -70,7 +70,7 @@ exports.visChange = async (page, options = {}) => {
       }
       catch(error) {
         return {
-          success: false,
+          prevented: true,
           error: 'Hovering failed'
         };
       }
@@ -91,7 +91,7 @@ exports.visChange = async (page, options = {}) => {
       const changePercent = 100 * pixelChanges / (width * height);
       // Return this.
       return {
-        success: true,
+        prevented: false,
         width,
         height,
         pixelChanges,
@@ -102,7 +102,6 @@ exports.visChange = async (page, options = {}) => {
     else {
       // Return this.
       return {
-        success: false,
         prevented: true,
         error: 'Second screenshot failed'
       };
@@ -112,7 +111,6 @@ exports.visChange = async (page, options = {}) => {
   else {
     // Return this.
     return {
-      success: false,
       prevented: true,
       error: 'First screenshot failed'
     };

package/run.js

@@ -114,6 +114,8 @@ let actCount = 0;
 // Facts about the current act.
 let actIndex = 0;
 let browser;
+let cleanupInProgress = false;
+let browserCloseIntentional = false;
 let browserContext;
 let page;
 let report;
@@ -257,7 +259,6 @@ const addError = (alsoLog, alsoAbort, report, actIndex, message) => {
   act.result.error ??= message;
   if (act.type === 'test') {
     act.data ??= {};
-    act.data.success = false;
     act.data.prevented = true;
     act.data.error = message;
     // Add prevention data to the job data.
@@ -269,20 +270,20 @@ const addError = (alsoLog, alsoAbort, report, actIndex, message) => {
     abortActs(report, actIndex);
   }
 };
-// Closes the current browser.
-const browserClose = async () => {
+// Closes any current browser.
+const browserClose = exports.browserClose = async () => {
+  // If a browser exists:
   if (browser) {
     browserCloseIntentional = true;
+    // Try to close all its contexts and ignore any messages that they are already closed.
     for (const context of browser.contexts()) {
       try {
         await context.close();
       }
       catch(error) {
-        console.log(
-          `ERROR trying to close context: ${error.message.slice(0, 200).replace(/\n.+/s, '')}`
-        );
       }
     }
+    // Close the browser.
     await browser.close();
     browserCloseIntentional = false;
     browser = null;
@@ -303,7 +304,7 @@ const launch = exports.launch = async (
     report.target.url = url;
     // Create a browser of the specified or default type.
     const browserType = playwrightBrowsers[browserID];
-    // Close the current browser, if any.
+    // Close any current browser.
     await browserClose();
     // Define browser options.
     const browserOptions = {
@@ -414,7 +415,7 @@ const launch = exports.launch = async (
           }
         });
       });
-      // Replace the page with the first page (tab) of the context (window).
+      // Reassign the page variable to a new page (tab) of the context (window).
       page = await browserContext.newPage();
       // Wait until it is stable.
       await page.waitForLoadState('domcontentloaded', {timeout: 5000});
@@ -678,6 +679,7 @@ const launchSpecs = (act, report) => [
 // Performs the acts in a report and adds the results to the report.
 const doActs = async (report, opts = {}) => {
   const {acts} = report;
+  // Get the granular observation options, if any.
   const {onProgress = null, signal = null} = opts;
   // Get the standardization specification.
   const standard = report.standard || 'only';
@@ -696,7 +698,7 @@ const doActs = async (report, opts = {}) => {
       if (report.observe) {
         const whichParam = which ? `&which=${which}` : '';
         const messageParams = `act=${type}${whichParam}`;
-        // If a progress callback has been provided:
+        // If a progress callback has been provided by a caller on this host:
         if (onProgress) {
           // Notify the observer of the act.
           try {
@@ -712,7 +714,7 @@ const doActs = async (report, opts = {}) => {
         }
         // Otherwise, i.e. if no progress callback has been provided:
         else {
-          // Notify the observer of the act and log it.
+          // Notify the remote observer of the act and log it.
           tellServer(report, messageParams, message);
         }
       }
@@ -769,7 +771,7 @@ const doActs = async (report, opts = {}) => {
           actLaunchSpecs[1]
         );
         // If this failed:
-        if (page.prevented) {
+        if (! page) {
           // Add this to the act.
           act.data ??= {};
           act.data.prevented = true;
@@ -1511,7 +1513,7 @@ const doActs = async (report, opts = {}) => {
     // For each browser ID/target URL class:
     for (const specString of Object.keys(launchSpecActs)) {
       const specs = specString.split('>');
-      // Launch a browser and navigate to the page.
+      // Replace the browser and navigate to the URL.
       await launch(
         report,
         debug,
@@ -1519,18 +1521,18 @@ const doActs = async (report, opts = {}) => {
         specs[0],
         specs[1]
       );
-      // For each test act with the class:
-      for (const specActIndex of launchSpecActs[specString]) {
-        const act = report.acts[specActIndex];
-        // Initialize the standard result.
-        act.standardResult = {
-          totals: [0, 0, 0, 0],
-          instances: []
-        };
-        // Populate it.
-        standardize(act);
-        // If the launch and navigation succeeded:
-        if (! page.prevented) {
+      // If the launch and navigation succeeded:
+      if (page) {
+        // For each test act in the class:
+        for (const specActIndex of launchSpecActs[specString]) {
+          const act = report.acts[specActIndex];
+          // Initialize the standard result.
+          act.standardResult = {
+            totals: [0, 0, 0, 0],
+            instances: []
+          };
+          // Populate it.
+          standardize(act);
           // Add a box ID and a path ID to each of its standard instances if missing.
           for (const instance of act.standardResult.instances) {
             const elementID = await identify(instance, page);
@@ -1541,18 +1543,22 @@ const doActs = async (report, opts = {}) => {
               instance.pathID = elementID ? elementID.pathID : '';
             }
           };
-        }
-        // If the original-format result is not to be included in the report:
-        if (standard === 'only') {
-          // Remove it.
-          delete act.result;
-        }
-      };
+          // If the original-format result is not to be included in the report:
+          if (standard === 'only') {
+            // Remove it.
+            delete act.result;
+          }
+        };
+      }
+      // Otherwise, i.e. if the launch or navigation failed:
+      else {
+        console.log(`ERROR: Launch or navigation to standardize ${specString} acts failed`);
+      }
     };
-    console.log('>>>> Standardization completed');
+    // Close the last browser launched for standardization.
+    await browserClose();
+    console.log('Standardization completed');
   }
-  // Close the browser.
-  await browserClose();
   // Delete the temporary report file.
   await fs.rm(reportPath, {force: true});
   return report;
@@ -1598,7 +1604,7 @@ exports.doJob = async (job, opts = {}) => {
         process.exit();
       }
     });
-    // Perform the acts and get a report.
+    // Perform the acts with any specified same-host observation options and get a report.
     report = await doActs(report, opts);
     // Add the end time and duration to the report.
     const endTime = new Date();
@@ -1623,10 +1629,6 @@ exports.doJob = async (job, opts = {}) => {
 
 // CLEANUP HANDLERS
 
-// Track whether cleanup is in progress.
-let cleanupInProgress = false;
-let browserCloseIntentional = false;
-
 // Force-kills any Playwright browser processes synchronously.
 const forceKillBrowsers = () => {
   if (cleanupInProgress) {

package/testaro/motion.js

@@ -6,7 +6,7 @@
 /*
   motion
   This test reports motion in a page by comparing the first and last of the screenshots previously
-  made by the shoot test.
+  made by the shoot0 and shoot1 tests.
 
   For minimal accessibility, standards require motion to be brief, or else stoppable by the user.
   But stopping motion can be difficult or impossible, and, by the time a user manages to stop
@@ -21,9 +21,18 @@
 
 // IMPORTS
 
-// Module to make a screenshot.
+// Module to process files.
+const fs = require('fs/promises');
+// Module to get operating-system properties.
+const os = require('os');
+// Module to compare screenshots.
 const pixelmatch = require('pixelmatch').default;
-const {result} = require('../tests/testaro');
+// Module to parse PNGs.
+const {PNG} = require('pngjs');
+
+// CONSTANTS
+
+const tmpDir = os.tmpdir();
 
 // FUNCTIONS
 
@@ -33,29 +42,32 @@ exports.reporter = async page => {
   const data = {};
   const totals = [0, 0, 0, 0];
   const standardInstances = [];
-  // Get the screenshots made by the shoot test.
-  const shootResult = result ? result.shoot || {} : {};
-  // If there are at least 2 of them:
-  if (shootResult.pngs && shootResult.pngs.length > 1) {
-    let {pngs} = shootResult;
-    // Choose the first and last of them for comparison.
-    const pngPair = [pngs[0], pngs[pngs.length - 1]];
-    // Get their dimensions.
-    const {width, height} = pngPair[0];
+  // Get the screenshot PNG buffers made by the shoot0 and shoot1 tests.
+  let shoot0PNGBuffer = await fs.readFile(`${tmpDir}/testaro-shoot-0.png`);
+  let shoot1PNGBuffer = await fs.readFile(`${tmpDir}/testaro-shoot-1.png`);
+  // Delete the buffers files.
+  await fs.unlink(`${tmpDir}/testaro-shoot-0.png`);
+  await fs.unlink(`${tmpDir}/testaro-shoot-1.png`);
+  // If both buffers exist:
+  if (shoot0PNGBuffer && shoot1PNGBuffer) {
+    // Parse them into PNG objects.
+    let shoot0PNG = PNG.sync.read(shoot0PNGBuffer);
+    let shoot1PNG = PNG.sync.read(shoot1PNGBuffer);
     // If their dimensions differ:
-    if (width !== pngPair[1].width || height !== pngPair[1].height) {
+    if (shoot1PNG.width !== shoot0PNG.width || shoot1PNG.height !== shoot0PNG.height) {
       // Report this.
       data.prevented = true;
-      data.error = 'Screenshots have differing dimensions';
+      data.error = 'Screenshot dimensions differ';
     }
     // Otherwise, i.e. if their dimensions are identical:
     else {
+      const {width, height} = shoot0PNG;
       // Get the count of differing pixels between the shots.
-      const pixelChanges = pixelmatch(pngPair[0].data, pngPair[1].data, null, width, height);
+      const pixelChanges = pixelmatch(shoot0PNG.data, shoot1PNG.data, null, width, height);
       // Get the ratio of differing to all pixels as a percentage.
       const changePercent = 100 * pixelChanges / (width * height);
       // Free the memory used by screenshots.
-      pngs = [];
+      shoot0PNG = shoot1PNG = shoot0PNGBuffer = shoot1PNGBuffer = null;
       // If any pixels were changed:
       if (pixelChanges) {
         // Get the ordinal severity from the fractional pixel change.
@@ -65,26 +77,31 @@ exports.reporter = async page => {
         // Get a summary standard instance.
         standardInstances.push({
           ruleID: 'motion',
-          what: 'Content moves or changes without user request',
+          what: `Content moves or changes spontaneously (${changePercent}% of pixels changed)`,
           count: 1,
           ordinalSeverity,
           tagName: 'HTML',
           id: '',
           location: {
-            doc: '',
-            type: '',
-            spec: ''
+            doc: 'dom',
+            type: 'box',
+            spec: {
+              x: 0,
+              y: 0,
+              width,
+              height
+            }
           },
-          excerpt: ''
+          excerpt: '<html>…</html>'
         });
       }
     }
   }
-  // Otherwise, i.e. if there are not at least 2 of them
+  // Otherwise, i.e. if they do not both exist:
   else {
     // Report this.
     data.prevented = true;
-    data.error = 'Fewer than 2 screenshots recorded';
+    data.error = 'At least 1 screenshot missing';
   }
   // Return the result.
   return {

package/testaro/motionSolo.js

@@ -61,7 +61,7 @@ exports.reporter = async page => {
     delayBetween: 3000
   });
   // If the screenshots succeeded:
-  if (data.success) {
+  if (! data.prevented) {
     // If any pixels were changed:
     if (data.pixelChanges) {
       // Get the ordinal severity from the fractional pixel change.

package/testaro/shoot0.js

@@ -0,0 +1,26 @@
+/*
+  © 2025 Jonathan Robert Pool. All rights reserved.
+  Licensed under the MIT License. See LICENSE file for details.
+*/
+
+/*
+  shoot0
+  This test makes and saves the first of two screenshots.
+*/
+
+// IMPORTS
+
+const {shoot} = require('../procs/shoot');
+
+// FUNCTIONS
+
+exports.reporter = async page => {
+  // Make and save the first screenshot.
+  const pngPath = await shoot(page, 0);
+  // Return the file path or a failure result.
+  return {
+    data: {
+      prevented: ! pngPath
+    }
+  };
+};

package/testaro/shoot1.js

@@ -0,0 +1,26 @@
+/*
+  © 2025 Jonathan Robert Pool. All rights reserved.
+  Licensed under the MIT License. See LICENSE file for details.
+*/
+
+/*
+  shoot1
+  This test makes and saves the second of two screenshots.
+*/
+
+// IMPORTS
+
+const {shoot} = require('../procs/shoot');
+
+// FUNCTIONS
+
+exports.reporter = async page => {
+  // Make and save the second screenshot.
+  const pngPath = await shoot(page, 1);
+  // Return the file path or a failure result.
+  return {
+    data: {
+      prevented: ! pngPath
+    }
+  };
+};

package/tests/testaro.js

@@ -42,8 +42,8 @@ const fs = require('fs/promises');
 // Metadata of all rules in default execution order.
 const allRules = [
   {
-    id: 'shoot',
-    what: 'page screenshot',
+    id: 'shoot0',
+    what: 'first page screenshot',
     contaminator: false,
     timeOut: 5,
     defaultOn: true
@@ -350,8 +350,8 @@ const allRules = [
     defaultOn: true
   },
   {
-    id: 'shoot',
-    what: 'page screenshot',
+    id: 'shoot1',
+    what: 'second page screenshot',
     contaminator: false,
     timeOut: 5,
     defaultOn: true
@@ -455,7 +455,7 @@ process.on('unhandledRejection', reason => {
   console.error(`ERROR: Unhandled Promise Rejection (${reason})`);
 });
 
-// ######## FUNCTIONS
+// FUNCTIONS
 
 // Conducts a JSON-defined test.
 const jsonTest = async (ruleID, ruleArgs) => {
@@ -503,7 +503,7 @@ exports.reporter = async (page, report, actIndex) => {
     rulesInvalid: [],
     ruleTestTimes: {}
   };
-  const result = exports.result = {};
+  const result = {};
   const allRuleIDs = allRules.map(rule => rule.id);
   // If the rule specification is invalid:
   if (! (
@@ -559,6 +559,7 @@ exports.reporter = async (page, report, actIndex) => {
     // Report crashes and disconnections during this test.
     let crashHandler;
     let disconnectHandler;
+    // Get the current browser.
     const {browser} = require('../run');
     if (page && ! page.isClosed()) {
       crashHandler = () => {
@@ -631,7 +632,10 @@ exports.reporter = async (page, report, actIndex) => {
             // Prevent a retry of the test.
             testSuccess = true;
             // If testing is to stop after a failure and the page failed the test:
-            if (stopOnFail && ruleOrTimeoutReport.totals.some(total => total)) {
+            if (
+              stopOnFail
+              && ruleOrTimeoutReport.totals
+              && ruleOrTimeoutReport.totals.some(total => total)) {
               // Stop testing.
               break;
             }
@@ -693,9 +697,11 @@ exports.reporter = async (page, report, actIndex) => {
       // Clear the error listeners.
       if (page && ! page.isClosed() && crashHandler) {
         page.off('crash', crashHandler);
+        crashHandler = null;
       }
       if (browser && disconnectHandler) {
         browser.off('disconnected', disconnectHandler);
+        disconnectHandler = null;
       }
     }
     // Otherwise, i.e. if the rule is undefined or doubly defined:
@@ -704,10 +710,22 @@ exports.reporter = async (page, report, actIndex) => {
       data.rulesInvalid.push(rule);
       console.log(`ERROR: Rule ${rule.id} not validly defined`);
       // Clear the crash listener.
-      if (page && ! page.isClosed()) {
+      if (page && ! page.isClosed() && crashHandler) {
         page.off('crash', crashHandler);
+        crashHandler = null;
+      }
+      if (browser && disconnectHandler) {
+        browser.off('disconnected', disconnectHandler);
+        disconnectHandler = null;
+      }
+    }
+    // Force a garbage collection.
+    try {
+      if (global.gc) {
+        global.gc();
       }
     }
+    catch(error) {}
   };
   // Record the test times in descending order.
   testTimes.sort((a, b) => b[1] - a[1]).forEach(pair => {

package/tests/wave.js

@@ -75,9 +75,10 @@ exports.reporter = async (page, report, actIndex) => {
           });
           // When they arrive:
           response.on('end', async () => {
+            let actResult = {};
             // Delete unnecessary properties.
             try {
-              const actResult = JSON.parse(rawReport);
+              actResult = JSON.parse(rawReport);
               const {categories, statistics} = actResult;
               delete categories.feature;
               delete categories.structure;
@@ -141,7 +142,7 @@ exports.reporter = async (page, report, actIndex) => {
             catch(error) {
               data.prevented = true;
               data.error = error.message;
-              resolve(result);
+              resolve(actResult);
             };
           });
         }