testaro 72.4.4 → 72.5.1

package/CLAUDE.md

@@ -82,7 +82,7 @@ Key variables:
 - `WAVE_KEY` — API key for the WAVE subscription API
 - `JOBDIR` / `REPORTDIR` — root directories for job files and report output
 - `AGENT` — instance name used in network-watch mode
-- `NETWATCH_URL_<N>_JOB/OBSERVE/REPORT/AUTH`, `NETWATCH_URLS` — server polling configuration
+- `NETWATCH_URL_<N>_JOB/REPORT/AUTH`, `NETWATCH_URLS` — server polling configuration
 - `TIMEOUT_MULTIPLIER` — scales all per-tool time limits (default 1)
 
 ## Code style

package/README.md

@@ -137,38 +137,7 @@ You can make `testaro` a dependency in another application. As noted at the begi
 
 ## Environment configuration
 
-The `.env` file stores your decisions about the environment in which Testaro runs. The variables that can be defined there are:
-
-```conf
-# Whether the browsers launched by Testaro should have visible windows.
-HEADED_BROWSER=false
-# Whether console logging in launched browsers should be mirrored to the Testaro console.
-DEBUG=false
-# Whether to disable Puppeteer log warnings of a future headless-mode deprecation.
-PUPPETEER_DISABLE_HEADLESS_WARNING=true
-# How much time, in milliseconds, to insert between Playwright operations for debugging.
-WAITS=0
-# API key to enable the WAVE tool.
-WAVE_KEY=yourwavekey (get it from [WebAim](https://wave.webaim.org/api/)).
-#----------------------------
-# When Testaro listens for new jobs in a directory:
-# Directory where it listens for them.
-JOBDIR=../testing/jobs
-# Directory into which Testaro saves the reports of those jobs.
-REPORTDIR=../testing/reports
-# Name of this Testaro instance when it listens for jobs and sends reports to requesting hosts.
-AGENT=agentabc
-#----------------------------
-# When Testaro polls a network host to ask for new jobs, data on the host.
-# URL to poll.
-NETWATCH_JOB=http://localhost:3000/api/assignJob/agentabc
-# URL to which to send progress reports during jobs.
-NETWATCH_OBSERVE=http://localhost:3000/api/granular/agentabc
-# URL to which to send completed job reports.
-NETWATCH_REPORT=http://localhost:3000/api/takeReport/agentabc
-# Password to give to the host to authenticate this instance.
-NETWATCH_AUTH=abcxyz
-```
+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
 
@@ -184,7 +153,6 @@ Here is a sample job, showing properties that you can set:
   what: 'monthly health check', // Job description
   strict: true, // Whether to reject redirections from the target URL
   standard: 'also', // or 'only' or 'no' (whether to report a standard result)
-  observe: false, // Whether to send progress notices to the requesting host
   device: { // Device to emulate
     id: 'iPhone 8',
     windowOptions: {

package/call.js

@@ -56,8 +56,6 @@ const callRun = async jobIDStart => {
     // Get it.
     const jobJSON = await fs.readFile(`${todoDir}/${jobFileName}`, 'utf8');
     let report = JSON.parse(jobJSON);
-    // Ensure it does not specify server properties.
-    report.observe = false;
     // Run it.
     report = await doJob(report);
     // Archive it.

package/dirWatch.js

@@ -100,9 +100,6 @@ exports.dirWatch = async (isForever, intervalInSeconds) => {
           try {
             const job = JSON.parse(jobJSON);
             let report = JSON.parse(jobJSON);
-            // Ensure it has no server properties.
-            job.observe = false;
-            report.observe = false;
             const {id} = job;
             console.log(`\n\nDirectory job ${id} ready to do (${nowString()})`);
             // Perform it and get a report.

package/env.example

@@ -0,0 +1,32 @@
+# You can get a WAVE API key at https://wave.webaim.org/api.
+WAVE_KEY=__placeholder__
+# You can get an Anthropic API key at https://console.anthropic.com/.
+ANTHROPIC_API_KEY=__placeholder__
+# Name to identify this Testaro instance to a server.
+AGENT=__placeholder__
+# Whether to make the browser visible (normally false).
+HEADED_BROWSER=false
+# Whether to output even forked-job logging to the primary log (normally false).
+DEBUG=false
+# Number of seconds to wait between actions (normally 0).
+WAITS=0
+# See https://nodejs.org/api/cli.html#options for all permitted options.
+NODE_OPTIONS='--trace-uncaught --trace-warnings'
+# Suppresses a routine warning from QualWeb.
+PUPPETEER_DISABLE_HEADLESS_WARNING=true
+# URL to poll for available jobs when watching the network.
+NETWATCH_JOB=__placeholder__/api/testaro-agent/job
+# URL to report results to when watching the network.
+NETWATCH_REPORT=__placeholder__/api/testaro-agent/report
+# Password of this Testaro agent
+NETWATCH_AUTH=__placeholder__
+# Directory (relative to project root) to watch for jobs.
+JOBDIR=__placeholder__
+# Directory (relative to project root) to write reports to when watching a directory for jobs.
+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

package/package.json

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

package/procs/doActs.js

@@ -14,22 +14,13 @@
 
 // IMPORTS
 
-// Module to handle errors.
-const {abortActs, addError} = require('./error');
-// Function to close a browser and/or its context.
+const {addError} = require('./error');
 const {getNonce, goTo, launch, wait} = require('./launch');
-// Constant describing the tools.
 const {tools} = require('./job');
-// Module to create child processes.
 const {fork} = require('child_process');
 const os = require('os');
-// Function to prune a catalog.
 const {pruneCatalog} = require('./catalog');
-// Module to handle file system operations.
 const fs = require('fs/promises');
-const httpClient = require('http');
-const httpsClient = require('https');
-const agent = process.env.AGENT;
 
 // CONSTANTS
 
@@ -62,27 +53,11 @@ const timeLimits = {
 };
 // Timeout multiplier.
 const timeoutMultiplier = Number.parseFloat(process.env.TIMEOUT_MULTIPLIER) || 1;
+// Abort aggressiveness.
+const abortAssertively = process.env.ABORT_ASSERTIVELY === 'true';
 
 // FUNCTIONS
 
-// Sends a notice to a network observer.
-const tellServer = (report, messageParams, logMessage) => {
-  const observerURL = process.env.NETWATCH_URL_OBSERVE;
-  if (observerURL) {
-    const whoParams = `agent=${agent}&jobID=${report.id || ''}`;
-    const wholeURL = `${observerURL}?${whoParams}&${messageParams}`;
-    const client = wholeURL.startsWith('https://') ? httpsClient : httpClient;
-    client.request(wholeURL)
-    // If the notification threw an error:
-    .on('error', error => {
-      // Report the error.
-      const errorMessage = 'ERROR notifying the server';
-      console.log(`${errorMessage} (${error.message})`);
-    })
-    .end();
-    console.log(`${logMessage} (server notified)`);
-  }
-};
 // Normalizes spacing characters and cases in a string.
 const debloat = string => string.replace(/\s/g, ' ').trim().replace(/ {2,}/g, ' ').toLowerCase();
 // Returns the first line of an error message.
@@ -249,83 +224,50 @@ const waitError = (page, act, error, what) => {
   return false;
 };
 // Performs the acts in a report and adds the results to the report.
-exports.doActs = async (report, opts = {}) => {
-  // Make a local copy of the report.
-  let localReport = JSON.parse(JSON.stringify(report));
+exports.doActs = async report => {
+  // Make a temporary copy of the report. Precondition: report is valid.
+  let tempReport = JSON.parse(JSON.stringify(report));
   let page = null;
-  let {acts} = localReport;
-  // Get the granular observation options, if any.
-  const {onProgress = null, signal = null} = opts;
+  let {acts} = tempReport;
   // Get the standardization specification.
-  const standard = localReport.standard || 'only';
-  // Set the temporary directory.
-  let tmpDir = `${__dirname}/../${process.env.TMPDIRNAME || 'scratch'}`;
-  try {
-    await fs.access(tmpDir, fs.constants.W_OK);
-  }
-  catch(error) {
-    console.log(`ERROR: ${tmpDir} is not writable`);
-    tmpDir = os.tmpdir();
+  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 {
-      await fs.access(tmpDir, fs.constants.W_OK);
+      // Verify that it is writable.
+      await fs.access(tmpDirAlternative, fs.constants.W_OK);
+      tmpDir = tmpDirAlternative;
+      break;
     }
+    // If it is not:
     catch(error) {
-      console.log(`ERROR: ${tmpDir} is not writable`);
-      tmpDir = '/tmp';
-      try {
-        await fs.access(tmpDir, fs.constants.W_OK);
-      }
-      catch(error) {
-        console.log(`ERROR: ${tmpDir} is not writable; quitting`);
-        process.exit(1);
-      }
+      // 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 a path for temporary reports.
-  const reportPath = `${tmpDir}/${localReport.id}.json`;
+  const reportPath = `${tmpDir}/${tempReport.id}.json`;
   // Initialize the count of completed acts.
   let actCount = 0;
-  // For each act in the local report:
+  // For each act in the temporary report:
   for (const actIndex in acts) {
-    // If the job has been aborted by a signal:
-    if (signal && signal.aborted) {
-      // Report this.
-      throw new Error('doActs aborted');
-    }
-    // Otherwise, and if the job has not been aborted internally:
-    if (localReport.jobData && ! localReport.jobData.aborted) {
+    // If the job has not been aborted:
+    if (tempReport?.jobData && ! tempReport.jobData.aborted) {
       let act = acts[actIndex];
       const {type, which} = act;
       const actSuffix = type === 'test' ? ` ${which}` : '';
       const message = `>>>> ${type}${actSuffix}`;
-      // If granular reporting has been specified:
-      if (localReport.observe) {
-        const whichParam = which ? `&which=${which}` : '';
-        const messageParams = `act=${type}${whichParam}`;
-        // If a progress callback has been provided by a caller on this host:
-        if (onProgress) {
-          // Notify the observer of the act.
-          try {
-            onProgress({
-              type,
-              which
-            });
-          }
-          catch (error) {
-            console.log(`${message} (observer notification failed: ${errorStart(error)})`);
-          }
-        }
-        // Otherwise, i.e. if no progress callback has been provided:
-        else {
-          // Notify the remote observer of the act and log it.
-          tellServer(localReport, messageParams, message);
-        }
-      }
-      // Otherwise, i.e. if granular reporting has not been specified:
-      else {
-        // Log the act.
-        console.log(message);
-      }
+      // Log the act.
+      console.log(message);
       // If the act is an index changer:
       if (type === 'next') {
         const condition = act.if;
@@ -347,7 +289,7 @@ exports.doActs = async (report, opts = {}) => {
         if (truth[1]) {
           // If the performance of acts is to stop:
           if (act.jump === 0) {
-            // Quit.
+            // Stop processing acts.
             break;
           }
           // Otherwise, if there is a numerical jump:
@@ -366,16 +308,16 @@ exports.doActs = async (report, opts = {}) => {
       else if (type === 'launch') {
         // Launch a browser, navigate to a page, and add the result to the act.
         page = await launch({
-          localReport,
+          tempReport,
           actIndex,
-          tempBrowserID: getActBrowserID(localReport, actIndex),
-          tempURL: getActTargetURL(localReport, actIndex),
+          tempBrowserID: getActBrowserID(tempReport, actIndex),
+          tempURL: getActTargetURL(tempReport, actIndex),
           xPathNeed: 'none'
         });
         // If this failed:
         if (! page) {
-          // Add this to the act.
-          addError(false, false, localReport, actIndex, page.error ?? '');
+          // Report this.
+          addError(false, false, tempReport, actIndex, page.error ?? '');
         }
       }
       // Otherwise, if the act is a test act:
@@ -386,9 +328,9 @@ exports.doActs = async (report, opts = {}) => {
         const startTime = Date.now();
         // Add it to the act.
         act.startTime = startTime;
-        let localReportJSON = JSON.stringify(localReport);
-        // Save a copy of the local report, which the child process will read.
-        await fs.writeFile(reportPath, localReportJSON);
+        let tempReportJSON = JSON.stringify(tempReport);
+        // 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 actResult = await new Promise(resolve => {
@@ -459,55 +401,70 @@ exports.doActs = async (report, opts = {}) => {
         });
         // If the child process sent a message:
         if (actResult.kind === 'message') {
-          // Get the revised localReport file.
-          localReportJSON = await fs.readFile(reportPath, 'utf8');
+          // Get the revised tempReport file.
+          tempReportJSON = await fs.readFile(reportPath, 'utf8');
           try {
-            // Reassign it to the local report.
-            localReport = JSON.parse(localReportJSON);
-            // Redefine the acts as those in the revised local report.
-            ({acts} = localReport);
+            // Reassign it to the temporary report.
+            tempReport = JSON.parse(tempReportJSON);
+            // Redefine the acts as those in the revised temporary report.
+            ({acts} = tempReport);
           }
-          // If the conversion fails, leaving the local report and its acts unchanged:
+          // If the reassignment fails, leaving the temporary report and its acts unchanged:
           catch (error) {
             // Report this.
             console.log(
-              `ERROR: Tool sent message ${actResult.message}. Report is no longer JSON (${error.message}) but is instead a(n) ${typeof localReportJSON} of length ${localReportJSON.length}:\n${localReportJSON}`
+              `ERROR: Tool sent message ${actResult.message}. Report is no longer JSON (${error.message}) but is instead a(n) ${typeof tempReportJSON} of length ${tempReportJSON.length}:\n${tempReportJSON}`
             );
-            // Add the error data to the act.
+            // Report this and that the job was aborted.
             addError(
               false,
-              false,
-              localReport,
+              true,
+              tempReport,
               actIndex,
-              `Non-JSON local report file after message ${actResult.message}`
+              `Non-JSON temporary report file after message ${actResult.message}`
             );
+            // Stop processing acts.
+            break;
           }
         }
         // Otherwise, i.e. if the child process closed abnormally:
         else {
-          // Add the error data to the act.
+          // Report this and, if so configured, that the job was aborted.
           const {code, error, kind, signal} = actResult;
           if (kind === 'close' && timedOut) {
             addError(
-              false, false, localReport, actIndex, `Timed out at ${Math.round(limitMs / 1000)} seconds`
+              false,
+              abortAssertively,
+              tempReport,
+              actIndex,
+              `Timed out at ${Math.round(limitMs / 1000)} seconds`
             );
           }
           else if (kind === 'close') {
             addError(
-              true, false, localReport, actIndex, `Closed with code ${code} and signal ${signal})`
+              true,
+              abortAssertively,
+              tempReport,
+              actIndex,
+              `Closed with code ${code} and signal ${signal})`
             );
           }
           else {
             addError(
-              true, false, localReport, actIndex, `Terminated with error ${error}`
+              true, abortAssertively, tempReport, actIndex, `Terminated with error ${error}`
             );
           }
+          // If the job was aborted:
+          if (abortAssertively) {
+            // Stop processing acts.
+            break;
+          }
         }
         // Get the (usually revised) act.
         act = acts[actIndex];
-        // Add the elapsed time of the tool to the local report.
+        // Add the elapsed time of the tool to the temporary report.
         const time = Math.round((Date.now() - startTime) / 1000);
-        const {toolTimes} = localReport.jobData;
+        const {toolTimes} = tempReport.jobData;
         toolTimes[act.which] ??= 0;
         toolTimes[act.which] += time;
         // If the act was not prevented:
@@ -545,16 +502,16 @@ exports.doActs = async (report, opts = {}) => {
           const resolved = act.which.replace('__dirname', __dirname);
           requestedURL = resolved;
           // Visit it and wait until the DOM is loaded.
-          const navResult = await goTo(localReport, page, requestedURL, 15000, 'domcontentloaded');
+          const navResult = await goTo(tempReport, page, requestedURL, 15000, 'domcontentloaded');
           // If the visit succeeded:
           if (navResult.success) {
-            // Revise the local report URL to this URL.
-            localReport.target.url = requestedURL;
+            // Revise the temporary report URL to this URL.
+            tempReport.target.url = requestedURL;
             // Add the script nonce, if any, to the act.
             const {response} = navResult;
             const scriptNonce = getNonce(response);
             if (scriptNonce) {
-              localReport.jobData.lastScriptNonce = scriptNonce;
+              tempReport.jobData.lastScriptNonce = scriptNonce;
             }
             // Add the resulting URL to the act.
             if (! act.result) {
@@ -564,13 +521,13 @@ exports.doActs = async (report, opts = {}) => {
             // If a prohibited redirection occurred:
             if (response.exception === 'badRedirection') {
               // Report this.
-              addError(true, false, localReport, actIndex, 'ERROR: Navigation illicitly redirected');
+              addError(true, false, tempReport, actIndex, 'ERROR: Navigation illicitly redirected');
             }
           }
           // Otherwise, i.e. if the visit failed:
           else {
             // Report this.
-            addError(true, false, localReport, actIndex, 'ERROR: Visit failed');
+            addError(true, false, tempReport, actIndex, 'ERROR: Visit failed');
           }
         }
         // Otherwise, if the act is a wait for text:
@@ -588,8 +545,7 @@ exports.doActs = async (report, opts = {}) => {
             }
             // If the wait times out:
             catch(error) {
-              // Quit.
-              abortActs(localReport, actIndex);
+              // Report this.
               waitError(page, act, error, 'text in the URL');
             }
           }
@@ -612,8 +568,7 @@ exports.doActs = async (report, opts = {}) => {
             }
             // If the wait times out:
             catch(error) {
-              // Quit.
-              abortActs(localReport, actIndex);
+              // Report this.
               waitError(page, act, error, 'text in the title');
             }
           }
@@ -635,8 +590,7 @@ exports.doActs = async (report, opts = {}) => {
             }
             // If the wait times out:
             catch(error) {
-              // Quit.
-              abortActs(localReport, actIndex);
+              // Report this.
               waitError(page, act, error, 'text in the body');
             }
           }
@@ -650,13 +604,13 @@ exports.doActs = async (report, opts = {}) => {
           )
           // If the wait times out:
           .catch(async error => {
-            // Report this and abort the job.
+            // Report this.
             console.log(`ERROR waiting for page to be ${act.which} (${error.message})`);
-            addError(true, false, localReport, actIndex, `ERROR waiting for page to be ${act.which}`);
+            addError(true, false, tempReport, actIndex, `ERROR waiting for page to be ${act.which}`);
           });
           // If the wait succeeded:
           if (actIndex > -2) {
-            // Add state data to the local report.
+            // Add state data to the temporary report.
             act.result = {
               success: true,
               state: act.which
@@ -739,7 +693,7 @@ exports.doActs = async (report, opts = {}) => {
                     }
                     // If no element satisfied the specifications:
                     if (! act.result.found) {
-                      // Add the failure data to the local report.
+                      // Add the failure data to the temporary report.
                       act.result.success = false;
                       act.result.error = 'exhausted';
                       act.result.typeElementCount = selections.length;
@@ -752,7 +706,7 @@ exports.doActs = async (report, opts = {}) => {
                   }
                   // Otherwise, i.e. if there are too few such elements to make a match possible:
                   else {
-                    // Add the failure data to the local report.
+                    // Add the failure data to the temporary report.
                     act.result.success = false;
                     act.result.error = 'fewer';
                     act.result.typeElementCount = selections.length;
@@ -761,7 +715,7 @@ exports.doActs = async (report, opts = {}) => {
                 }
                 // Otherwise, i.e. if there are no elements of the specified type:
                 else {
-                  // Add the failure data to the local report.
+                  // Add the failure data to the temporary report.
                   act.result.success = false;
                   act.result.error = 'none';
                   act.result.typeElementCount = 0;
@@ -770,7 +724,7 @@ exports.doActs = async (report, opts = {}) => {
               }
               // Otherwise, i.e. if the page no longer exists:
               else {
-                // Add the failure data to the local report.
+                // Add the failure data to the temporary report.
                 act.result.success = false;
                 act.result.error = 'gone';
                 act.result.message = 'Page gone';
@@ -795,8 +749,8 @@ exports.doActs = async (report, opts = {}) => {
                 }
                 // If the move fails:
                 catch(error) {
-                  // Add the error result to the act and abort the job.
-                  addError(true, false, localReport, actIndex, `ERROR: ${move} failed`);
+                  // Report this.
+                  addError(true, false, tempReport, actIndex, `ERROR: ${move} failed`);
                 }
                 if (act.result.success) {
                   try {
@@ -880,16 +834,15 @@ exports.doActs = async (report, opts = {}) => {
                   }
                   // If the click or load failed:
                   catch(error) {
-                    // Quit and add failure data to the local report.
+                    // Report this.
                     console.log(`ERROR clicking link (${errorStart(error)})`);
                     act.result.success = false;
                     act.result.error = 'unclickable';
                     act.result.message = 'ERROR: click or load timed out';
-                    abortActs(localReport, actIndex);
                   }
                   // If the link click succeeded:
                   if (! act.result.error) {
-                    // Add success data to the local report.
+                    // Add success data to the temporary report.
                     act.result.success = true;
                     act.result.move = 'clicked';
                   }
@@ -938,7 +891,7 @@ exports.doActs = async (report, opts = {}) => {
                 }
                 // Enter the text.
                 await selection.type(what);
-                localReport.jobData.presses += what.length;
+                tempReport.jobData.presses += what.length;
                 act.result.success = true;
                 act.result.move = 'entered';
                 // If the input is a search input:
@@ -957,19 +910,18 @@ exports.doActs = async (report, opts = {}) => {
             }
             // Otherwise, i.e. if no match was found:
             else {
-              // Quit and add failure data to the local report.
+              // RLeport this.
               act.result.success = false;
               act.result.error = 'absent';
               act.result.message = 'ERROR: specified element not found';
               console.log('ERROR: Specified element not found');
-              abortActs(localReport, actIndex);
             }
           }
           // Otherwise, if the act is a keypress:
           else if (type === 'press') {
             // Identify the number of times to press the key.
             let times = 1 + (act.again || 0);
-            localReport.jobData.presses += times;
+            tempReport.jobData.presses += times;
             const key = act.which;
             // Press the key.
             while (times--) {
@@ -1123,26 +1075,26 @@ exports.doActs = async (report, opts = {}) => {
             if (withItems) {
               act.result.items = items;
             }
-            // Add the totals to the local report.
-            localReport.jobData.presses += presses;
-            localReport.jobData.amountRead += amountRead;
+            // Add the totals to the temporary report.
+            tempReport.jobData.presses += presses;
+            tempReport.jobData.amountRead += amountRead;
           }
           // Otherwise, i.e. if the act type is unknown:
           else {
-            // Add the error result to the act and abort the job.
-            addError(true, false, localReport, actIndex, 'ERROR: Invalid act type');
+            // Report this.
+            addError(true, false, tempReport, actIndex, 'ERROR: Invalid act type');
           }
         }
         // Otherwise, a page URL is required but does not exist, so:
         else {
-          // Add an error result to the act and abort the job.
-          addError(true, false, localReport, actIndex, 'ERROR: Page has no URL');
+          // Report this.
+          addError(true, false, tempReport, actIndex, 'ERROR: Page has no URL');
         }
       }
       // Otherwise, i.e. if no page exists:
       else {
-        // Add an error result to the act and abort the job.
-        addError(true, false, localReport, actIndex, 'ERROR: No page identified');
+        // Report this.
+        addError(true, false, tempReport, actIndex, 'ERROR: No page identified');
       }
       // Add the end time to the act.
       act.endTime = Date.now();
@@ -1156,20 +1108,20 @@ exports.doActs = async (report, opts = {}) => {
     // If the native results are not to be included in the report:
     if (standard === 'only') {
       // Remove them.
-      localReport.acts.forEach(act => {
+      tempReport.acts.forEach(act => {
         if (act.result?.nativeResult) {
           delete act.result.nativeResult;
         }
       });
     }
     // If a catalog was created:
-    if (localReport.catalog) {
-      let {catalog} = localReport;
+    if (tempReport.catalog) {
+      let {catalog} = tempReport;
       // Get its element count.
       const elementCount = Object.keys(catalog).length;
       // Prune it, removing elements with no reported violations.
-      pruneCatalog(localReport);
-      ({catalog} = localReport);
+      pruneCatalog(tempReport);
+      ({catalog} = tempReport);
       // Get properties of the pruned catalog.
       const textCount = Object.values(catalog).filter(entry => entry.text).length;
       const linkableTextCount = Object.values(catalog).filter(entry => entry.textLinkable).length;
@@ -1186,7 +1138,7 @@ exports.doActs = async (report, opts = {}) => {
         },
         tools: {}
       };
-      const {acts} = localReport;
+      const {acts} = tempReport;
       // For each act:
       for (const act of acts) {
         // If it is a test act:
@@ -1219,12 +1171,12 @@ exports.doActs = async (report, opts = {}) => {
           }
         }
       }
-      // Add the catalog data to the local report.
-      localReport.jobData.catalogData = catalogData;
+      // Add the catalog data to the temporary report.
+      tempReport.jobData.catalogData = catalogData;
     }
   }
-  // Delete the temporary local report file.
+  // Delete the temporary temporary report file.
   await fs.rm(reportPath, {force: true});
-  // Return the local report.
-  return localReport;
+  // Return the temporary report.
+  return tempReport;
 };

package/procs/doTestAct.js

@@ -73,9 +73,9 @@ const sendMessage = message => {
     );
   }
 };
-// Performs the tests of an act.
+// Performs tests of a test act.
 const doTestAct = async (reportPath, actIndex) => {
-  // Get the report from the temporary directory.
+  // Get the temporary report.
   const reportJSON = await fs.readFile(reportPath, 'utf8');
   const report = JSON.parse(reportJSON);
   // Get a reference to the act in the report.

package/procs/error.js

@@ -12,14 +12,22 @@
   Handles errors.
 */
 
+// IMPORTS
+
+const {nowString} = require('./dateTime');
+
+// FUNCTIONS
+
 // Reports a job being aborted.
-const abortActs = exports.abortActs = (report, actIndex) => {
+const abortActs = (report, actIndex, message = '') => {
   // Add data on the aborted act to the report.
   report.jobData.abortTime = nowString();
-  report.jobData.abortedAct = actIndex;
+  report.jobData.abortedAct = actIndex ?? 'none';
   report.jobData.aborted = true;
-  // Report that the job is aborted.
-  console.log(`ERROR: Job aborted on act ${actIndex}`);
+  report.jobData.abortMessage = message;
+  const abortedActString = typeof actIndex === 'number' ? ` on act ${actIndex}` : '';
+  // Log that the job is aborted.
+  console.log(`ERROR: Job aborted${abortedActString}`);
 };
 // Adds an error result to an act.
 exports.addError = (alsoLog, alsoAbort, report, actIndex, message) => {
@@ -48,6 +56,6 @@ exports.addError = (alsoLog, alsoAbort, report, actIndex, message) => {
   // If the job is to be aborted:
   if (alsoAbort) {
     // Add this to the report.
-    abortActs(report, actIndex);
+    abortActs(report, actIndex, message);
   }
 };

package/procs/job.js

@@ -175,7 +175,6 @@ exports.isValidJob = job => {
       id,
       strict,
       standard,
-      observe,
       device,
       browserID,
       creationTimeStamp,
@@ -203,12 +202,6 @@ exports.isValidJob = job => {
         error: 'Bad job standard'
       };
     }
-    if (typeof observe !== 'boolean') {
-      return {
-        isValid: false,
-        error: 'Bad job observe'
-      }
-    }
     if (! isDeviceID(device.id)) {
       return {
         isValid: false,

package/procs/launch.js

@@ -50,6 +50,7 @@ const errorWords = [
 ];
 // Seconds to wait between actions.
 const waits = Number(process.env.WAITS) ?? 0;
+const abortAssertively = process.env.ABORT_ASSERTIVELY === 'true';
 
 // FUNCTIONS
 
@@ -80,6 +81,29 @@ const browserClose = exports.browserClose = async page => {
     }
   }
 };
+// Normalizes a file URL in case it has the Windows path format.
+const normalizeURL = url => {
+  // If a URL was provided:
+  if (url) {
+    // If it is that of a local file:
+    if (url.toLowerCase().startsWith('file:')) {
+      let path = url.replace(/^file:\/+/i, '');
+      path = path.replace(/\\/g, '/');
+      // Return the URL normalized.
+      return 'file:///' + path.replace(/^\//, '');
+    }
+    // Otherwise, i.e. if it is not that of a local file:
+    else {
+      // Return it.
+      return url;
+    }
+  }
+  // Otherwise, i.e. if no URL was provided:
+  else {
+    // Return this.
+    return undefined;
+  }
+};
 // Visits a URL and returns the response of the server.
 const goTo = exports.goTo = async (report, page, url, timeout, waitUntil) => {
   // If the URL is a file path relative to the project root:
@@ -96,11 +120,11 @@ const goTo = exports.goTo = async (report, page, url, timeout, waitUntil) => {
     });
     report.jobData.visitLatency += Math.round((Date.now() - startTime) / 1000);
     const httpStatus = response.status();
-    // If the response status was normal:
+    // If the response status was normal or the URL points to a local file:
     if ([200, 304].includes(httpStatus) || url.startsWith('file:')) {
       const actualURL = page.url();
-      const actualNorm = actualURL.startsWith('file:') ? normalizeFile(actualURL) : actualURL;
-      const urlNorm = url.startsWith('file:') ? normalizeFile(url) : url;
+      const actualNorm = actualURL.startsWith('file:') ? normalizeURL(actualURL) : actualURL;
+      const urlNorm = url.startsWith('file:') ? normalizeURL(url) : url;
       // If the browser was redirected in violation of a strictness requirement:
       if (report.strict && deSlash(actualNorm) !== deSlash(urlNorm)) {
         // Return an error.
@@ -151,11 +175,10 @@ const goTo = exports.goTo = async (report, page, url, timeout, waitUntil) => {
     // Otherwise, i.e. if the response status was otherwise abnormal:
     else {
       // Return an error.
-      console.log(`ERROR: Visit to ${url} got status ${httpStatus}`);
       report.jobData.visitRejectionCount++;
       return {
         success: false,
-        error: 'badStatus'
+        error: `ERROR: Visit to ${url} got status ${httpStatus}`
       };
     }
   }
@@ -165,7 +188,7 @@ const goTo = exports.goTo = async (report, page, url, timeout, waitUntil) => {
     }
     return {
       success: false,
-      error: 'noVisit'
+      error: `ERROR visiting ${url} (${error.message.slice(0, 200)})`
     };
   }
 };
@@ -208,15 +231,13 @@ const launchOnce = async opts => {
   const {device} = report;
   const deviceID = device?.id;
   const browserID = tempBrowserID || report.browserID || '';
-  const url = tempURL || report.target?.url || '';
+  const url = normalizeURL(tempURL || report.target?.url || '');
   let page;
   // If the specified browser and device types and URL are valid:
   if (isBrowserID(browserID) && isDeviceID(deviceID) && isURL(url)) {
-    // Replace the report target URL with this URL.
+    // Replace the report target URL with the specified URL.
     report.target.url = url;
-    // Create a browser of the specified or default type.
     const browserType = playwrightBrowsers[browserID];
-    // Define the browser-option args, depending on the browser type and head-emulation level.
     const browserOptionArgs = [];
     if (browserID === 'chromium') {
       browserOptionArgs.push(
@@ -244,7 +265,7 @@ const launchOnce = async opts => {
         );
       }
     }
-    // Define the browser options.
+    // Get the browser options.
     const browserOptions = {
       logger: {
         isEnabled: () => false,
@@ -462,34 +483,31 @@ const launchOnce = async opts => {
         throw new Error(`Navigation failed (${navResult.error})`);
       }
     }
-    // If an error occurred:
+    // If the browser and page creation and navigation threw an error:
     catch(error) {
-      // Report this.
-      console.log(`ERROR launching or navigating (${error.message})`);
       // Close the browser and its context, if they exist.
       await browserClose(page);
-      // Return a failure.
+      // Return the error.
       return {
         success: false,
         error: error.message
       };
     }
   }
-  // If the launch and navigation succeeded, return the page.
+  // Otherwise, i.e. if the specified browser or device type or URL is invalid:
+  else {
+    // Return this.
+    return {
+      success: false,
+      error: 'Invalid browser, device type, or URL'
+    };
+  }
+  // If the browser and page creation and navigation succeeded, return the page.
   return {
     success: true,
     page
   };
 };
-// Normalizes a file URL in case it has the Windows path format.
-const normalizeFile = u => {
-  if (!u) return u;
-  if (!u.toLowerCase().startsWith('file:')) return u;
-  // Ensure forward slashes and three slashes after file:
-  let path = u.replace(/^file:\/+/i, '');
-  path = path.replace(/\\/g, '/');
-  return 'file:///' + path.replace(/^\//, '');
-};
 // Manages browser launching and navigating and returns a page.
 exports.launch = async (opts = {}) => {
   const {
@@ -527,9 +545,9 @@ exports.launch = async (opts = {}) => {
     // Otherwise, i.e. if the launch or navigation failed:
     else {
       let retriesLeft = retries;
+      let {error} = launchResult;
       // As long as retries remain, decrement the allowed retry count and:
-      while (retriesLeft--) {
-        const {error} = launchResult;
+      while (retriesLeft) {
         // Prepare to wait 1 second before a retry.
         let waitSeconds = 1;
         // If the error was a visit failure due to rate limiting:
@@ -543,7 +561,7 @@ exports.launch = async (opts = {}) => {
         }
         // Report the wait.
         console.log(
-          `WARNING: Waiting ${waitSeconds} sec. before retrying (retries left: ${retries})`
+          `WARNING: Waiting ${waitSeconds} sec. before retrying (retries left: ${retriesLeft--})`
         );
         // Wait as specified.
         await wait(1000 * waitSeconds);
@@ -567,14 +585,17 @@ exports.launch = async (opts = {}) => {
         }
         // Otherwise, i.e. if the launch or navigation failed:
         else {
+          error = launchResult.error;
           // Report this.
-          console.log(`WARNING: Retry failed; retries left: ${retries}`);
+          console.log(`WARNING: Retry failed (${error})`);
         }
       }
       // If the retries were exhausted:
-      if (retriesLeft === -1) {
-        // Report this.
-        addError(true, false, report, actIndex, 'ERROR: No retries left');
+      if (! retriesLeft) {
+        // Report this and, if so configured, that the job was aborted.
+        addError(
+          true, abortAssertively, report, actIndex, `Launch or navigation failed; retries exhausted`
+        );
       }
       // Return a failure.
       return null;
@@ -582,13 +603,13 @@ exports.launch = async (opts = {}) => {
   }
   // Otherwise, i.e. if the report is invalid:
   else {
-    // Report this.
+    // Report this and that the job was aborted.
     addError(
       true,
-      false,
+      true,
       report,
       actIndex,
-      `ERROR: Cannot launch browser for invalid job (${jobValidation.error})`
+      `ERROR: Job invalid (${jobValidation.error})`
     );
     // Return a failure.
     return null;

package/run.js

@@ -48,7 +48,7 @@ exports.doJob = async (job, opts = {}) => {
     console.log(`ERROR: ${jobInvalidity.error}`);
     jobData.aborted = true;
     jobData.abortedAct = null;
-    jobData.abortError = jobInvalidity.error;
+    jobData.abortMessage = jobInvalidity.error;
   }
   // Otherwise, i.e. if it is valid:
   else {
@@ -69,6 +69,8 @@ exports.doJob = async (job, opts = {}) => {
       visitRejectionCount: 0,
       aborted: false,
       abortedAct: null,
+      abortTime: '',
+      abortMessage: '',
       presses: 0,
       amountRead: 0,
       toolTimes: {},

package/tests/testaro.js

@@ -501,11 +501,7 @@ exports.reporter = async (page, report, actIndex) => {
     && ['y', 'n'].includes(ruleSpec[0])
     && ruleSpec.slice(1).every(ruleID => allRuleIDs.includes(ruleID))
   ) {
-    // Wait 1 second to prevent out-of-order logging with granular reporting.
-    await wait(1000);
-    // Get the rules to be tested for and their execution order.
-    // 'y' = include-list: run exactly the rules in ruleSpec.slice(1).
-    // 'n' = exclude-list: run all defaultOn rules EXCEPT those in ruleSpec.slice(1).
+    // Get the rules to be (y) or not to be (n) tested for and their execution order.
     const excludeIDs = ruleSpec.slice(1);
     const jobRuleIDs = ruleSpec[0] === 'y'
     ? excludeIDs

package/validation/jobs/todo/240101T1200-simple-example.json

@@ -23,7 +23,6 @@
   ],
   "sources": {},
   "standard": "only",
-  "observe": false,
   "sendReportTo": "http://localhost:3007/api",
   "timeStamp": "240101T1500",
   "creationTimeStamp": "240101T1200"

package/validation/validateTest.js

@@ -26,7 +26,6 @@ const job = {
   what: '',
   strict: true,
   standard: 'only',
-  observe: false,
   device: {
     id: 'default',
     windowOptions: {

package/validation/watch/done/240101T1200-simple-example.json

@@ -23,7 +23,6 @@
   ],
   "sources": {},
   "standard": "only",
-  "observe": false,
   "timeStamp": "240101T1500",
   "creationTimeStamp": "240101T1200",
   "sendReportTo": ""