testaro 72.4.3 → 72.5.0

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

@@ -162,8 +162,6 @@ 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.
@@ -184,7 +182,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.3",
+  "version": "72.5.0",
   "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/testaro/linkUl.js

@@ -9,7 +9,7 @@
 
 /*
   linkUl
-  This test reports failures to underline inline links. Underlining and color are the traditional style properties that identify links. Lists of links containing only links may be recognizable without underlines, but other links are difficult or impossible to distinguish visually from surrounding text if not underlined. Underlining adjacent links only on hover provides an indicator valuable only to mouse users, and even they must traverse the text with a mouse merely to discover which passages are links.
+  This test reports failures to underline links that have adjacent text. Underlining and color are the traditional style properties that identify links. A link whose text is the entire text of its block may be recognizable without underlining, but otherwise links are difficult or impossible to distinguish visually from surrounding text if not underlined. Underlining links only on hover provides an indicator valuable only to mouse users, and even they must traverse the text with a mouse merely to discover which passages are links.
 */
 
 // IMPORTS
@@ -21,24 +21,28 @@ const {doTest} = require('../procs/testaro');
 // Runs the test and returns the result.
 exports.reporter = async (page, catalog, withItems) => {
   const getBadWhat = element => {
-    const liAncestor = element.closest('li');
-    // If the element is not the only link inside a list item:
-    if (! (liAncestor && liAncestor.getElementsByTagName('a').length === 1)) {
-      const styleDec = window.getComputedStyle(element);
-      const {textDecoration} = styleDec;
-      // If the element text is not underlined:
-      if (! textDecoration.includes('underline')) {
-        const styleDec = window.getComputedStyle(element);
-        const {display} = styleDec;
-        // If the element has does not have a block display style:
-        if (display !== 'block') {
-          // Return a violation description.
-          return 'Element is not a list item but is not underlined';
-        }
+    let {display, textDecorationLine} = window.getComputedStyle(element);
+    // If the element is not underlined:
+    if (! textDecorationLine.includes('underline')) {
+      let ancestor = element;
+      // Get its closest non-inline ancestor.
+      while (display === 'inline') {
+        ancestor = ancestor.parentElement;
+        display = ancestor ? window.getComputedStyle(ancestor).display : null;
+      }
+      // Removes superfluous whitespace from a string.
+      const compact = string => string?.replace(/\s+/g, ' ')?.trim();
+      // If the rendered compacted text of that ancestor includes more than that of the element:
+      if (
+        compact(element.textContent) !== compact(ancestor?.textContent)
+        && compact(element.innerText) !== compact(ancestor?.innerText)
+      ) {
+        // Return a violation description.
+        return 'Element has adjacent text but is not underlined';
       }
     }
   };
-  const whats = 'Links that are not list items are not underlined';
+  const whats = 'Links with adjacent text are not underlined';
   return await doTest(
     page, catalog, withItems, 'linkUl', 'body a', whats, 1, getBadWhat.toString()
   );

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": ""