testilo 7.1.1 → 9.0.0

package/call.js

@@ -1,204 +1,130 @@
 /*
-  do.js
+  call.js
   Invokes Testilo modules with arguments.
   This is the universal module for use of Testilo from a command line.
   Arguments:
     0. function to execute.
     1+. arguments to pass to the function.
   Usage examples:
-    node call aim tp25 https://www.w3c.org/ 'World Wide Web Consortium' w3c developer@w3.org
-    node call merge script454 webOrgs
-    node call score sp25a (to score the first raw report)
-    node call score sp25a 8ep9f (to score the first raw report whose name starts with 8ep9f)
-    node call multiScore sp25a
-    node call digest dp25a (to digest the first scored report)
-    node call digest dp25a 8ep9f (to digest the first scored report whose name starts with 8ep9f)
-    node call multiDigest dp25a
-    node call compare cp25a weborgs (to write weborgs.html, comparing all scored reports)
+    node call merge ts25 webOrgs user@domain.tld true
+    node call score sp25a
+    node call digest dp25a
+    node call compare cp25a weborgs
 */
 
 // ########## IMPORTS
 
 // Module to keep secrets.
 require('dotenv').config();
-// Function to process a script aiming.
+// Function to process files.
 const fs = require('fs/promises');
-const {aim} = require('./aim');
-// Function to process a script-batch merger.
+// Function to process a merger.
 const {merge} = require('./merge');
-// Function to score a report.
+// Function to score reports.
 const {score} = require('./score');
-// Function to score multiple reports.
-const {multiScore} = require('./multiScore');
-// Function to digest a report.
+// Function to digest reports.
 const {digest} = require('./digest');
-// Function to digest multiple reports.
-const {multiDigest} = require('./multiDigest');
 // Function to compare scores.
 const {compare} = require('./compare');
 
 // ########## CONSTANTS
 
-const scriptDir = process.env.SCRIPTDIR;
-const scoreProcDir = process.env.SCOREPROCDIR;
-const digestProcDir = process.env.DIGESTPROCDIR;
+const specDir = process.env.SPECDIR;
+const functionDir = process.env.FUNCTIONDIR;
 const jobDir = process.env.JOBDIR;
-const rawDir = process.env.REPORTDIR_RAW;
-const scoredDir = process.env.REPORTDIR_SCORED;
-const digestedDir = process.env.REPORTDIR_DIGESTED;
-const comparisonDir = process.env.COMPARISONDIR;
+const reportDir = process.env.REPORTDIR;
 const fn = process.argv[2];
 const fnArgs = process.argv.slice(3);
 
 // ########## FUNCTIONS
 
-// Fulfills an aiming request.
-const callAim = async (scriptName, hostURL, hostName, hostID, requester) => {
-  const scriptJSON = await fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8');
+// Fulfills a merging request.
+const callMerge = async (scriptID, batchID, requester, withIsolation = false) => {
+  // Get the script and the batch.
+  const scriptJSON = await fs.readFile(`${specDir}/scripts/${scriptID}.json`, 'utf8');
   const script = JSON.parse(scriptJSON);
-  const job = aim(
-    script,
-    {
-      id: hostID,
-      which: hostURL,
-      what: hostName
-    },
-    requester
+  const batchJSON = await fs.readFile(`${specDir}/batches/${batchID}.json`, 'utf8');
+  const batch = JSON.parse(batchJSON);
+  // Merge them into an array of jobs.
+  const jobs = merge(script, batch, requester, withIsolation);
+  // Save the jobs.
+  for (const job of jobs) {
+    const jobJSON = JSON.stringify(job, null, 2);
+    await fs.writeFile(`${jobDir}/todo/${job.id}.json`, jobJSON);
+  }
+  const {timeStamp} = jobs[0];
+  console.log(
+    `Script ${scriptID} and batch ${batchID} merged; jobs ${timeStamp}… saved in ${jobDir}/todo`
   );
-  const scriptID = job.sources.script;
-  const jobID = job.id;
-  await fs.writeFile(`${jobDir}/${jobID}.json`, `${JSON.stringify(job, null, 2)}\n`);
-  console.log(`Script ${scriptID} aimed at ${hostName} saved as job ${jobID}.json in ${jobDir}`);
 };
-// Fulfills a merger request.
-const callMerge = async (scriptName, batchName, requester) => {
-  await merge(scriptName, batchName, requester);
-  console.log(`Batch ${batchName}.json merged into script ${scriptName} in ${jobDir}`);
+// Get selected reports.
+const getReports = async (type, selector = '') => {
+  const allFileNames = await fs.readdir(`${reportDir}/${type}`);
+  const reportIDs = allFileNames
+  .filter(fileName => fileName.endsWith('.json'))
+  .filter(fileName => fileName.startsWith(selector))
+  .map(fileName => fileName.slice(0, -5));
+  const reports = [];
+  for (const reportID of reportIDs) {
+    const reportJSON = await fs.readFile(`${reportDir}/${type}/${reportID}.json`, 'utf8');
+    const report = JSON.parse(reportJSON);
+    reports.push(report);
+  }
+  return reports;
 };
 // Fulfills a scoring request.
-const callScore = async (scoreProcID, reportIDStart = '') => {
-  // Identify the raw reports.
-  const rawFileNames = await fs.readdir(rawDir);
-  const rawReportNames = rawFileNames.filter(fileName => fileName.endsWith('.json'));
+const callScore = async (scorerID, selector = '') => {
+  // Get the raw reports to be scored.
+  const reports = getReports('raw', selector);
   // If any exist:
-  if (rawReportNames.length) {
-    // Identify the one to be scored.
-    let rawReportName = '';
-    if (reportIDStart) {
-      rawReportName = rawReportNames.find(reportName => reportName.startsWith(reportIDStart));
-    }
-    else {
-      rawReportName = rawReportNames[0];
-    }
-    // If it exists:
-    if (rawReportName) {
-      // Score it.
-      const rawReportJSON = await fs.readFile(`${rawDir}/${rawReportName}`, 'utf8');
-      const rawReport = JSON.parse(rawReportJSON);
-      const {scorer} = require(`./${scoreProcDir}/${scoreProcID}.js`);
-      const scoredReport = await score(scorer, rawReport);
-      // Save it, scored.
+  if (reports.length) {
+    // Get the scorer.
+    const {scorer} = require(`${functionDir}/score/${scorerID}`);
+    // Score the reports.
+    const scoredReports = score(scorer, reports);
+    const scoredReportDir = `${reportDir}/scored`;
+    // For each scored report:
+    for (const scoredReport of scoredReports) {
+      // Save it.
       await fs.writeFile(
-        `${scoredDir}/${scoredReport.job.id}.json`, JSON.stringify(scoredReport, null, 2)
+        `${scoredReportDir}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
       );
-      console.log(`Scored report ${rawReport.job.id} saved in ${scoredDir}`);
-    }
-    // Otherwise, i.e. if it does not exist:
-    else {
-      // Report this.
-      console.log('ERROR: Specified raw report not found');
-    }
+    };
   }
-  // Otherwise, i.e. if no raw report found:
+  // Otherwise, i.e. if no raw reports are to be scored:
   else {
     // Report this.
-    console.log('ERROR: No raw report found');
+    console.log('ERROR: No raw reports to be scored');
   }
 };
-// Fulfills a multiple-report scoring request.
-const callMultiScore = async scoreProcID => {
-  // Score all raw reports.
-  await multiScore(scoreProcID);
-};
-// Prepares to fulfill a digesting request.
-const digestPrep = async digestProcID => {
-  const {digest} = require('./digest');
-  const {makeQuery} = require(`./${digestProcDir}/${digestProcID}/index`);
-  const digestTemplate = await fs.readFile(`${digestProcDir}/${digestProcID}/index.html`, 'utf8');
-  // Identify the scored reports.
-  const scoredFileNames = await fs.readdir(scoredDir);
-  const scoredReportNames = scoredFileNames.filter(fileName => fileName.endsWith('.json'));
-  // Return the data required for the fulfillment of the request.
-  return {
-    anyScoredReports: scoredReportNames.length > 0,
-    digest,
-    makeQuery,
-    digestTemplate,
-    scoredReportNames
-  };
-};
-// Digests and saves a report.
-const digestReport = async (scoredReportName, prepData) => {
-  // Digest the specified report.
-  const scoredReportJSON = await fs.readFile(`${scoredDir}/${scoredReportName}`, 'utf8');
-  const scoredReport = JSON.parse(scoredReportJSON);
-  const digestedReport = digest(prepData.digestTemplate, prepData.makeQuery, scoredReport);
-  // Save it, digested.
-  await fs.writeFile(`${digestedDir}/${scoredReport.job.id}.html`, digestedReport);
-  console.log(`Digested report ${scoredReport.job.id} saved in ${digestedDir}`);
-};
 // Fulfills a digesting request.
-const callDigest = async (digestProcID, reportIDStart = '') => {
-  const prepData = await digestPrep(digestProcID);
-  // If any scored reports exist:
-  if (prepData.anyScoredReports) {
-    // Identify the one to be digested.
-    let scoredReportName = '';
-    if (reportIDStart) {
-      scoredReportName = prepData.scoredReportNames.find(
-        reportName => reportName.startsWith(reportIDStart)
+const callDigest = async (digesterID, selector = '') => {
+  // Get the scored reports to be digested.
+  const reports = getReports('scored', selector);
+  // If any exist:
+  if (reports.length) {
+    const digesterDir = `${functionDir}/digest/${digesterID}`;
+    // Get the digester.
+    const {digester} = require(`${digesterDir}/index`);
+    // Get the template.
+    const template = await fs.readFile(`${digesterDir}/index.html`);
+    // Digest the reports.
+    const digestedReports = digest(template, digester, reports);
+    const digestedReportDir = `${reportDir}/digested`;
+    // For each digested report:
+    for (const digestedReport of digestedReports) {
+      // Save it.
+      await fs.writeFile(
+        `${digestedReportDir}/${digestedReport.id}.json`, JSON.stringify(digestedReport, null, 2)
       );
-    }
-    else {
-      scoredReportName = prepData.scoredReportNames[0];
-    }
-    // If it exists:
-    if (scoredReportName) {
-      // Digest and save it.
-      await digestReport(scoredReportName, prepData);
-    }
-    // Otherwise, i.e. if it does not exist:
-    else {
-      // Report this.
-      console.log('ERROR: Specified scored report not found');
-    }
+    };
   }
-  // Otherwise, i.e. if no scored report exists:
+  // Otherwise, i.e. if no scored reports are to be digested:
   else {
     // Report this.
-    console.log('ERROR: No scored report found');
+    console.log('ERROR: No scored reports to be digested');
   }
 };
-// Fulfills a multiple-report digesting request.
-const callMultiDigest = async digestProcID => {
-  const prepData = await digestPrep(digestProcID);
-  // If any scored reports exist:
-  if (prepData.anyScoredReports) {
-    // For each of them:
-    for (const scoredReportName of prepData.scoredReportNames) {
-      // Digest and save it.
-      await digestReport(scoredReportName, prepData);
-    }
-  }
-  // Otherwise, i.e. if no raw report exists:
-  else {
-    // Report this.
-    console.log('ERROR: No raw report found');
-  }
-  console.log(
-    `Digesting completed. Digest proc: ${digestProcID}. Report count: ${prepData.scoredReportNames.length}. Directory: ${digestedDir}.`
-  );
-};
 // Fulfills a comparison request.
 const callCompare = async (compareProcID, comparisonNameBase) => {
   await compare(compareProcID, comparisonNameBase);
@@ -216,7 +142,7 @@ if (fn === 'aim' && fnArgs.length === 5) {
     console.log('Execution completed');
   });
 }
-else if (fn === 'merge' && fnArgs.length > 1 && fnArgs.length < 4) {
+else if (fn === 'merge' && fnArgs.length > 2 && fnArgs.length < 5) {
   callMerge(... fnArgs)
   .then(() => {
     console.log('Execution completed');

package/compare.js

@@ -1,39 +1,22 @@
 /*
   compare.js
-  Creates comparisons from scored reports.
-  Reads reports in process.env.REPORTDIR_SCORED and outputs into process.env.COMPARISONDIR.
-  Arguments:
-    0. Base of name of compare proc located in procs/compare.
-    1. Base of name of comparative report to be written.
-  Usage example: node compare cp18a usFedExec
-  Note: Compares all reports in process.env.REPORTDIR_SCORED (but not in its subdirectories).
+  Creates a comparative report from scored reports.
 */
 
-// ########## IMPORTS
-
-// Module to keep secrets.
-require('dotenv').config();
-// Module to read and write files.
-const fs = require('fs/promises');
-
-// ########## CONSTANTS
-
-const comparisonDir = process.env.COMPARISONDIR || 'reports/comparative';
-
 // ########## FUNCTIONS
 
-// Replaces the placeholders in content with eponymous query parameters.
-const replaceHolders = (content, query) => content
+// Replaces the placeholders in a template with eponymous query parameters.
+const replaceHolders = (template, query) => template
 .replace(/__([a-zA-Z]+)__/g, (ph, qp) => query[qp]);
-// Creates and saves a web page containing a comparative table.
-exports.compare = async (compareProcID, comparisonNameBase) => {
-  const comparisonDirAbs = `${__dirname}/${comparisonDir}`;
-  const {getQuery} = require(`./${process.env.COMPAREPROCDIR}/${compareProcID}/index`);
-  const query = await getQuery();
-  const pageRaw = await fs.readFile(
-    `${__dirname}/${process.env.COMPAREPROCDIR}/${compareProcID}/index.html`, 'utf8'
-  );
-  const page = replaceHolders(pageRaw, query);
-  await fs.writeFile(`${comparisonDirAbs}/${comparisonNameBase}.html`, page);
-  console.log(`Page ${comparisonNameBase}.html created and saved`);
+// Compares the scored reports and returns a comparison.
+exports.compare = (comparisonTemplate, comparer, reports) => {
+  // Create a query.
+  const query = {};
+  // Populate the query.
+  comparer(reports, query);
+  // Use it to create a comparison.
+  const comparison = replaceHolders(comparisonTemplate, query);
+  // Return the comparison.
+  console.log(`Comparison complete. Report count: ${reports.length}`);
+  return comparison;
 };

package/digest.js

@@ -1,10 +1,10 @@
 /*
   digest.js
-  Creates a digest from a scored report.
+  Creates digests from a scored reports.
   Arguments:
     0. Digest template.
-    1. Digest proc.
-    2. Scored report.
+    1. Digesting function.
+    2. Array of scored reports.
 */
 
 // ########## FUNCTIONS
@@ -12,14 +12,22 @@
 // Replaces the placeholders in content with eponymous query parameters.
 const replaceHolders = (content, query) => content
 .replace(/__([a-zA-Z]+)__/g, (ph, qp) => query[qp]);
-// Creates a digest.
-exports.digest = (digestTemplate, digestProc, scoredReport) => {
+// Digests the scored reports and returns them, digested.
+exports.digest = (digestTemplate, digester, reports) => {
+  const digests = [];
   // Create a query.
   const query = {};
-  digestProc(scoredReport, query);
-  // Use it to replace the placeholders in the template.
-  const digestedReport = replaceHolders(digestTemplate, query);
-  // Return the digest.
-  console.log(`Report ${scoredReport.job.id} digested`);
-  return digestedReport;
+  // For each report:
+  for (const report of reports) {
+    // Populate the query.
+    digester(report, query);
+    // Use it to create a digest.
+    const digestedReport = replaceHolders(digestTemplate, query);
+    // Add the digest to the array of digests.
+    digests.push(digestedReport);
+    console.log(`Report ${report.id} digested`);
+  };
+  // Return the digests.
+  console.log(`Digesting complete. Report count: ${reports.length}`);
+  return digests;
 };

package/merge.js

@@ -1,53 +1,128 @@
 /*
   merge.js
-  Merges a batch and a script to produce jobs.
+  Merges a script and a batch and returns jobs.
   Arguments:
-    0. base of name of script located in process.env.SCRIPTDIR.
-    1. base of name of batch located in process.env.BATCHDIR.
-    2. email address to be notified of completion.
-  Usage examples:
-    node call merge ts25 weborgs developer@w3.org
-    node call merge ts25 weborgs
-  Note: The subdirectory for jobs will be created if it does not exist.
+    0. script
+    1. batch
+    2. whether to provide test isolation (no if omitted)
 */
 
 // ########## IMPORTS
 
 // Module to keep secrets.
 require('dotenv').config();
-// Module to read and write files.
-const fs = require('fs/promises');
-// Module to aim a script at a host.
-const {aim} = require('./aim');
 
 // ########## CONSTANTS
 
-const scriptDir = process.env.SCRIPTDIR || 'scripts';
-const batchDir = process.env.BATCHDIR || 'batches';
-const jobDir = process.env.JOBDIR || 'watch';
 const stdRequester = process.env.REQUESTER;
+const contaminantNames = new Set([
+  'axe',
+  'continuum',
+  'focAll',
+  'focInd',
+  'focOp',
+  'hover',
+  'htmlcs',
+  'ibm',
+  'menuNav',
+  'textNodes',
+  'wave'
+]);
 
 // ########## FUNCTIONS
 
-// Merges a batch into a script and writes jobs.
-exports.merge = async (scriptName, batchName, requester = stdRequester) => {
-  // Get the script and the batch.
-  const scriptJSON = await fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8');
-  const batchJSON = await fs.readFile(`${batchDir}/${batchName}.json`, 'utf8');
-  const script = JSON.parse(scriptJSON);
-  const batch = JSON.parse(batchJSON);
+// Merges a script and a batch and returns jobs.
+exports.merge = (script, batch, requester, isolate = false) => {
+  if (isolate === 'false') {
+    isolate = false;
+  }
+  // If the requester is unspecified, make it the standard requester.
+  requester ||= stdRequester;
+  // Create a timestamp.
   const timeStamp = Math.floor((Date.now() - Date.UTC(2022, 1)) / 2000).toString(36);
-  // Create the job directory if it does not exist.
-  await fs.mkdir(jobDir, {recursive: true});
-  // For each host in the batch:
-  const {hosts} = batch;
-  for (const host of hosts) {
-    // Aim the script at the host.
-    const job = await aim(script, host, requester, timeStamp);
-    // Add the batch name to the job.
-    job.sources.batch = batchName;
-    // Save the job.
-    await fs.writeFile(`${jobDir}/${job.id}.json`, JSON.stringify(job, null, 2));
+  // Create a time description.
+  const creationTime = (new Date()).toISOString().slice(0, 19);
+  // Initialize a target-independent job.
+  const protoJob = JSON.parse(JSON.stringify(script));
+  // Add the timestamp to the ID of the job.
+  protoJob.id = `${timeStamp}-${protoJob.id}-`;
+  // Add a sources property to the job.
+  protoJob.sources = {
+    script: script.id,
+    batch: batch.id,
+    target: {
+      id: '',
+      what: ''
+    },
+    requester
   };
-  console.log(`Merger completed. Job count: ${hosts.length}. Time stamp ${timeStamp}.`);
+  // Add time properties to the job.
+  protoJob.creationTime = creationTime;
+  protoJob.timeStamp = timeStamp;
+  // If isolation was requested:
+  if (isolate) {
+    // Append a copy of the previous placeholder to each eligible contaminating test in the script.
+    let {acts} = protoJob;
+    let lastPlaceholder = {};
+    for (const actIndexString in acts) {
+      const actIndex = Number.parseInt(actIndexString);
+      const act = acts[actIndex];
+      if (act.type === 'placeholder') {
+        lastPlaceholder = act;
+      }
+      else if (
+        act.type === 'test'
+        && contaminantNames.has(act.which)
+        && actIndex < acts.length - 1
+        && acts[actIndex + 1].type !== 'placeholder'
+      ) {
+        acts[actIndex] = JSON.parse(JSON.stringify([act, lastPlaceholder]));
+      }
+    };
+    protoJob.acts = acts.flat();
+  }
+  // Initialize an array of jobs.
+  const jobs = [];
+  // For each target in the batch:
+  const {targets} = batch;
+  for (const target of targets) {
+    // Initialize a job.
+    const job = JSON.parse(JSON.stringify(protoJob));
+    // Add the target ID to the job ID.
+    job.id += target.id;
+    // Add data on the target to the sources property of the job.
+    job.sources.target.id = target.id;
+    job.sources.target.what = target.what;
+    // Replace each placeholder object in the job with the named replacer array of the target.
+    let {acts} = job;
+    for (const actIndex in acts) {
+      const act = acts[actIndex];
+      if (act.type === 'placeholder') {
+        const replacerName = act.which;
+        if (replacerName && target.acts) {
+          let replacerActs = target.acts[replacerName];
+          if (replacerActs) {
+            // Add a which property to any launch act in the replacer.
+            replacerActs = JSON.parse(JSON.stringify(replacerActs));
+            for (const replacerAct of replacerActs) {
+              if (replacerAct.type === 'launch') {
+                replacerAct.which = act.launch;
+              }
+            }
+            acts[actIndex] = replacerActs;
+          }
+          else {
+            console.log(`ERROR: Target ${target.id} has no ${replacerName} replacer`);
+          }
+        }
+        else {
+          console.log(`ERROR: Placeholder for target ${target.id} not replaceable`);
+        }
+      }
+    }
+    job.acts = acts.flat();
+    // Append the job to the array of jobs.
+    jobs.push(job);
+  };
+  return jobs;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testilo",
-  "version": "7.1.1",
+  "version": "9.0.0",
   "description": "Client that scores and digests Testaro reports",
   "main": "aim.js",
   "scripts": {

package/procs/compare/cp20sqrt/index.html

@@ -0,0 +1,48 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="author" content="Testilo">
+    <meta name="creator" content="Testilo">
+    <meta name="publisher" name="Testilo">
+    <meta name="description" content="comparison of accessibility scores">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility score comparison</title>
+    <link rel="icon" href="favicon.png">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility score comparison</h1>
+      </header>
+      <h2>Introduction</h2>
+      <p>The table below compares __pageCount__ web pages on <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/">accessibility</a>. The page names are links to the pages on the web. The scores are links to digests that explain in detail how the scores were computed.</p>
+      <p>The pages were:</p>
+      <ol id="summary">
+        <li>Tested by <a href="https://www.npmjs.com/package/testaro">Testaro</a> with script <code>ts20</code></li>
+        <li>Scored by <a href="https://www.npmjs.com/package/testilo">Testilo</a> with procedure <code>sp20b</code></li>
+        <li>Digested by Testilo with procedure <code>dp20d</code></li>
+        <li>Compared by Testilo with procedure <code>cp20a</code></li>
+      </ol>
+      <p>The script made Testaro perform 1230 automated accessibility tests drawn from nine different packages: Alfa, Axe, Continuum, Equal Access, HTML CodeSniffer, Nu Html Checker, Tenon, Testaro, and WAVE. The scoring procedure made Testilo assign a score to each page, with 0 being perfect.</p>
+      <h2>Comparison</h2>
+      <table class="allBorder">
+        <caption>Accessibility scores of web pages</caption>
+        <thead>
+          <tr><th scope="col">Page</th><th scope="col" colspan="2">Score (lower is better)</tr>
+        </thead>
+        <tbody class="linkSmaller secondCellRight">
+          __tableBody__
+        </tbody>
+      </table>
+      <h2>Discussion</h2>
+      <p>The widths of the bars in the above table are proportional to the square roots of the scores that the bars represent. For example, if score A is 4 times score B, then bar A is 2 times as wide as bar B.</p>
+      <p>Tests and scoring formulae are fallible and subjective. The reported faults merit investigation as potential opportunities for improved accessibility. But some may not actually harm accessibility, and some other accessibility faults are not detectable with these tests. Different reasonable procedures could yield different test results and different scores. Testaro and Testilo can be customized to fit different definitions and weightings of types of accessibility.</p>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>