testilo 7.0.8 → 7.0.10

package/README.md

@@ -55,7 +55,7 @@ const aimScript = async () => {
     id: w3c
   };
   const {aim} = require('testilo/aim');
-  const scriptJSON = await fs.readFile(`${process.env.SCRIPTDIR}/tp25.json`, 'utf8');
+  const scriptJSON = await fs.readFile(`${process.env.SCRIPTDIR}/ts25.json`, 'utf8');
   const script = JSON.parse(scriptJSON);
   const aimedScript = aim(script, host, 'developer@w3c.org');
   await fs.writeFile(
@@ -69,10 +69,10 @@ aimScript();
 Execution by a user:
 
 ```bash
-node call aim tp25 https://w3.org/ 'World Wide Web Consortium' w3c developer@w3c.org
+node call aim ts25 https://w3.org/ 'World Wide Web Consortium' w3c developer@w3c.org
 ```
 
-In these examples, a copy of the script file named `tp25.json` in the `SCRIPTDIR` directory is aimed at the World Wide Web Consortium and then saved in the `JOBDIR` directory.
+In these examples, a copy of the script file named `ts25.json` in the `SCRIPTDIR` directory is aimed at the World Wide Web Consortium and then saved in the `JOBDIR` directory.
 
 The `aim` function neither reads nor writes files. Its arguments are a script object, a host object, and a requester-email-address string, and it returns a job object, aimed at the host.
 
@@ -107,7 +107,7 @@ Execution by a module:
 
 ```javaScript
 const {merge} = require('testilo/merge');
-merge('tp25', 'weborgs', 'developer@w3.org')
+merge('ts25', 'weborgs', 'developer@w3.org')
 .then(() => {
   console.log('Merger complete');
 });
@@ -116,10 +116,10 @@ merge('tp25', 'weborgs', 'developer@w3.org')
 Execution by a user:
 
 ```bash
-node call merge tp25 weborgs developer@w3.org
+node call merge ts25 weborgs developer@w3.org
 ```
 
-In these examples, a copy of the script file named `tp25.json` in the `SCRIPTDIR` directory is aimed at all the hosts in the batch file named `weborgs.json` in the `BATCHDIR` directory, and the resulting jobs are saved in the `JOBDIR` directory. Each job has a `sources` property that identifies an email address to be notified after the job has been run.
+In these examples, a copy of the script file named `ts25.json` in the `SCRIPTDIR` directory is aimed at all the hosts in the batch file named `weborgs.json` in the `BATCHDIR` directory, and the resulting jobs are saved in the `JOBDIR` directory. Each job has a `sources` property that identifies an email address to be notified after the job has been run.
 
 ### `score`
 
@@ -144,7 +144,7 @@ const scoreReport = async (scoreProcID, rawReportID) => {
   );
   console.log(`Report ${scoredReport.id} scored`);
 };
-scoreReport('sp25a', '756mr-tp25-w3c');
+scoreReport('sp25a', '756mr-ts25-w3c');
 ```
 
 Execution by a user:
@@ -154,7 +154,7 @@ node call score sp25a
 node call score sp25a 756mr
 ```
 
-In these examples, the `score` function applies a score proc named `sp25a`, of which a copy is in the file `sp25a.json` in the `SCOREPROCDIR` directory, to a raw report `756mr-tp25-w3c.json` in the `REPORTDIR_RAW` directory and returns the same report with score data added. The scored report is saved in the `REPORTDIR_SCORED` directory.
+In these examples, the `score` function applies a score proc named `sp25a`, of which a copy is in the file `sp25a.json` in the `SCOREPROCDIR` directory, to a raw report `756mr-ts25-w3c.json` in the `REPORTDIR_RAW` directory and returns the same report with score data added. The scored report is saved in the `REPORTDIR_SCORED` directory.
 
 The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_RAW` directory is the desired raw report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
 
@@ -203,17 +203,17 @@ const digestReport = async (digestProcID, scoredReportID) => {
   await fs.writeFile(`${process.env.REPORTDIR_DIGESTED}/${digestedReport.id}.html`, digestedReport);
   console.log(`Report ${digestedReport.id} digested`);
 };
-digestReport('dp25a', '756mr-tp25-w3c');
+digestReport('dp25a', '756mr-ts25-w3c');
 ```
 
 Execution by a user:
 
 ```bash
-node call digest sp25a
-node call digest sp25a 756mr
+node call digest dp25a
+node call digest dp25a 756mr
 ```
 
-In these examples, the `digest` function applies a digest proc named `dp25a`, of which a copy is in the file `dp25a.json` in the `DIGESTPROCDIR` directory, to a scored report `756mr-tp25-w3c.json` in the `REPORTDIR_SCORED` directory and returns an HTML digest for that same report. The digest is saved in the `REPORTDIR_DIGESTED` directory.
+In these examples, the `digest` function applies a digest proc named `dp25a`, of which a copy is in the file `dp25a.json` in the `DIGESTPROCDIR` directory, to a scored report `756mr-ts25-w3c.json` in the `REPORTDIR_SCORED` directory and returns an HTML digest for that same report. The digest is saved in the `REPORTDIR_DIGESTED` directory.
 
 The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_SCORED` directory is the desired scored report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
 

package/call.js

@@ -62,7 +62,7 @@ const callAim = async (scriptName, hostURL, hostName, hostID, requester) => {
       id: hostID,
       which: hostURL,
       what: hostName
-    }, 
+    },
     requester
   );
   const scriptID = job.sources.script;
@@ -95,7 +95,7 @@ const callScore = async (scoreProcID, reportIDStart = '') => {
       // Score it.
       const rawReportJSON = await fs.readFile(`${rawDir}/${rawReportName}`, 'utf8');
       const rawReport = JSON.parse(rawReportJSON);
-      const {scorer} = require(`${scoreProcDir}/${scoreProcID}.js`);
+      const {scorer} = require(`./${scoreProcDir}/${scoreProcID}.js`);
       const scoredReport = await score(scorer, rawReport);
       // Save it, scored.
       await fs.writeFile(
@@ -123,7 +123,7 @@ const callMultiScore = async scoreProcID => {
 // Prepares to fulfill a digesting request.
 const digestPrep = async digestProcID => {
   const {digest} = require('./digest');
-  const {makeQuery} = require(`${digestProcDir}/${digestProcID}/index`);
+  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);

package/compare.js

@@ -28,9 +28,11 @@ const replaceHolders = (content, query) => content
 // Creates and saves a web page containing a comparative table.
 exports.compare = async (compareProcID, comparisonNameBase) => {
   const comparisonDirAbs = `${__dirname}/${comparisonDir}`;
-  const {getQuery} = require(`./procs/compare/${compareProcID}/index`);
+  const {getQuery} = require(`./${process.env.COMPAREPROCDIR}/${compareProcID}/index`);
   const query = await getQuery();
-  const pageRaw = await fs.readFile(`${__dirname}/procs/compare/${compareProcID}/index.html`, 'utf8');
+  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`);

package/package.json

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

package/procs/digest/dp16b/index.html

@@ -0,0 +1,80 @@
+<!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="report of accessibility testing of a web page">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility test digest</title>
+    <link rel="icon" href="favicon.png">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility test digest</h1>
+        <h2>Synopsis</h2>
+        <div id="synopsis">
+          <p><strong>Page</strong>: __org__</p>
+          <p><strong>URL</strong>: __url__</p>
+          <p><strong>Score</strong>: __totalScore__</p>
+          <p><strong>Tested by</strong>: Testaro, procedure <code>tp16</code></p>
+          <p><strong>Scored by</strong>: Testilo, procedure <code>sp16c</code></p>
+          <p><strong>Digested by</strong>: Testilo, procedure <code>dp16b</code></p>
+        </div>
+      </header>
+      <h2>Introduction</h2>
+      <p>The <a href="https://www.npmjs.com/package/testaro">Testaro</a> application used its <code>tp16</code> testing procedure to test the <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/"><dfn>accessibility</dfn></a> (barrier-free design and coding) of the __org__ web page at <a href="__url__">__url__</a> on __dateSlash__. The procedure performed 1229 tests. Of these, 23 are custom tests or <q>quasi-tests</q> by Testaro, and the others belong to these eight other packages (programs that perform collections of tests):</p>
+      <ul>
+        <li><a href="https://github.com/Siteimprove/alfa">Alfa</a> by Siteimprove</li>
+        <li><a href="https://www.npmjs.com/package/axe-core">Axe-core</a> by Deque</li>
+        <li><a href="https://www.webaccessibility.com/tools/">Continuum</a> by Level Access</li>
+        <li>
+          <a href="https://www.npmjs.com/package/html_codesniffer">HTML CodeSniffer</a> by Squiz Labs
+        </li>
+        <li><a href="https://github.com/IBMa/equal-access">Equal Access</a> by IBM</li>
+        <li><a href="https://github.com/validator/validator">Nu Html Checker</a></li>
+        <li><a href="https://tenon.io/documentation/apiv2.php">Tenon</a> by Level Access</li>
+        <li><a href="https://wave.webaim.org/api/">WAVE</a> by WebAIM</li>
+      </ul>
+      <p>Testaro produced a report enumerating the test results.</p>
+      <p><a href="https://www.npmjs.com/package/testilo">Testilo</a> processed the report and used the <code>sp16c</code> scoring procedure to compute partial and total scores for the page. The total score is __totalScore__ (where 0 is the best possible score). The scored report is appended below.</p>
+      <p>Finally, Testilo used procedure <code>dp16b</code> to produce this digest, briefly explaining how <code>sp16c</code> computed the scores.</p>
+      <h2>Score summary</h2>
+      <table class="allBorder secondCellRight">
+        <caption>Score components</caption>
+        <tbody class="headersLeft">
+        __scoreRows__
+        </tbody>
+      </table>
+      <h2>Issue summary</h2>
+      <h3>Special issues</h3>
+      __specialSummary__
+      <h3>Classified issues</h3>
+      __groupSummary__
+      <h2>Discussion</h2>
+      <p>Although there are widely accepted <a href="https://www.w3.org/WAI/standards-guidelines/">accessibility standards</a>, there is no unanimity about how to define, test, and quantify accessibility. The failures reported in this digest merit investigation as potential opportunities for improved accessibility. Investigation may lead you to conclude that some of the reported failures do not actually harm accessibility. Conversely, some substantial accessibility faults can escape detection by any of these tests. You may question the attempt to assign an accessibility score to a web page, or you may prefer weightings and formulas different from those used by <code>sp16c</code>. You can modify and extend Testaro and Testilo to fit other theories and priorities.</p>
+      <p>Here, in brief, is how <code>sp16c</code> computes a score for a page.</p>
+      <ul>
+        <li>It finds all the defects and warnings (let&rsquo;s call them <q>issues</q>) recorded in the report.</li>
+        <li>It classifies them according to type. For example, a link that looks like the text around it is one issue category, while a video that has no captions is another issue category.</li>
+        <li>It also classifies the issues according to severity. For example, an issue that prevents a transaction is more severe than an issue that only complicates the transaction, and a warning about a possible issue is less severe than a definite finding of an issue. (Some packages rate the severity of each issue; for the other packages, <code>sp16c</code> assigns a severity weight to the issue type and uses that weight.)</li>
+        <li>It assigns quality ratings to particular tests that are judged abnormally reliable or unreliable.</li>
+        <li>It assigns a score to each issue reported by each test of each package.</li>
+        <li>It aggregates the issue scores, weighting them by severity, test quality, and redundancy. Redundancy occurs, and causes downweighting, when two or more packages contain tests that are designed to discover the same or mostly the same issues. So the score for a category is not simply the sum of the scores of the tests in that category.</li>
+        <li>It assigns a score for issues in the page logged by the browser.</li>
+        <li>It assigns an estimated score each time the page prevents one of the packages or one of the Testaro tests from being run on the page.</li>
+        <li>It adds the scores together to obtain a total score.</li>
+      </ul>
+      <p>The precise rules of <code>sp16c</code> are found in the <a href="https://github.com/jrpool/testilo/blob/main/procs/score/sp16c.js">code itself</a>.</p>
+      <h2>Report</h2>
+      <pre>__report__</pre>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/digest/dp16b/index.js

@@ -0,0 +1,126 @@
+/*
+  index: digester for scoring procedure sp16c.
+  Creator of parameters for substitution into index.html.
+  Usage example for selected files in REPORTDIR_SCORED: node digest dp16b 35k1r
+  Usage example for all files in REPORTDIR_SCORED: node digest dp16b
+*/
+
+// CONSTANTS
+
+  // Newlines with indentations.
+  const joiner = '\n      ';
+  const innerJoiner = '\n        ';
+  const specialMessages = {
+    log: 'This is based on the amount of browser error logging and miscellaneous logging during the tests.',
+    preventions: 'This is based on tests that the page did not allow to be run. That impedes accessibility progress and risks interfering with tools that users with disabilities need.',
+    solos: 'This is based on issues reported by unclassified tests. Details are in the report.'
+  };
+
+// FUNCTIONS
+
+// Makes strings HTML-safe.
+const htmlEscape = textOrNumber => textOrNumber
+.toString()
+.replace(/&/g, '&')
+.replace(/</g, '&lt;');
+// Gets a row of the score-summary table.
+const getScoreRow = (component, score) => `<tr><th>${component}</th><td>${score}</td></tr>`;
+// Gets the start of a paragraph about a special score.
+const getSpecialPStart = (summary, scoreID) =>
+`<p><span class="componentID">${scoreID}</span>: Score ${summary[scoreID]}.`;
+// Adds parameters to a query for a digest.
+exports.makeQuery = (report, query) => {
+  // Add an HTML-safe copy of the host report to the query to be appended to the digest.
+  const {job, host, score} = report;
+  const reportJSON = JSON.stringify(report, null, 2);
+  const reportJSONSafe = htmlEscape(reportJSON);
+  query.report = reportJSONSafe;
+  // Add the job data to the query.
+  query.dateISO = report.jobData.endTime.slice(0, 10);
+  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  if (host && host.what && host.which) {
+    query.org = host.what;
+    query.url = host.which;
+  }
+  else {
+    const firstURLCommand = job.commands.find(command => command.type === 'url');
+    if (firstURLCommand && firstURLCommand.what && firstURLCommand.which) {
+      query.org = firstURLCommand.what;
+      query.url = firstURLCommand.which;
+    }
+    else {
+      console.log('ERROR: host missing or invalid');
+      return;
+    }
+  }
+  const {groupDetails, summary} = score;
+  const {total, groups} = summary;
+  if (typeof total === 'number') {
+    query.totalScore = total;
+  }
+  else {
+    console.log('ERROR: missing or invalid total score');
+    return;
+  }
+  // Add the total and any special rows of the score-summary table to the query.
+  const scoreRows = [];
+  const specialComponentIDs = ['log', 'preventions', 'solos'];
+  ['total'].concat(specialComponentIDs).forEach(item => {
+    if (summary[item]) {
+      scoreRows.push(getScoreRow(item, summary[item]));
+    }
+  });
+  // Add the group rows of the score-summary table to the query.
+  groups.forEach(group => {
+    scoreRows.push(getScoreRow(`${group.groupName}`, group.score));
+  });
+  query.scoreRows = scoreRows.join(innerJoiner);
+  // If the score has any special components:
+  const scoredSpecialIDs = specialComponentIDs.filter(item => summary[item]);
+  if (scoredSpecialIDs.length) {
+    // Add paragraphs about them for the issue summary to the query.
+    const specialPs = [];
+    scoredSpecialIDs.forEach(id => {
+      specialPs.push(`${getSpecialPStart(summary, id)} ${specialMessages[id]}`);
+    });
+    query.specialSummary = specialPs.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no special components:
+  else {
+    // Add a paragraph stating this for the issue summary to the query.
+    query.specialSummary = '<p>No special issues contributed to the score.</p>'
+  }
+  // If the score has any classified issues as components:
+  if (groups.length) {
+    // Add paragraphs about them for the special summary to the query.
+    const groupSummaryItems = [];
+    groups.forEach(group => {
+      const {groupName, score} = group;
+      const groupP = `<p><span class="componentID">${groupName}</span>: Score ${score}. Issues reported by tests in this category:</p>`;
+      const groupListItems = [];
+      const groupData = groupDetails.groups[groupName];
+      const packageIDs = Object.keys(groupData);
+      packageIDs.forEach(packageID => {
+        const testIDs = Object.keys(groupData[packageID]);
+        testIDs.forEach(testID => {
+          const testData = groupData[packageID][testID];
+          const {score, what} = testData;
+          const listItem = `<li>Package <code>${packageID}</code>, test <code>${testID}</code>, score ${score} (${what})</li>`;
+          groupListItems.push(listItem);
+        });
+      });
+      const groupList = [
+        '<ul>',
+        groupListItems.join('\n  '),
+        '</ul>'
+      ].join(joiner);
+      groupSummaryItems.push(groupP, groupList);
+    });
+    query.groupSummary = groupSummaryItems.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no classified issues as components:
+  else {
+    // Add a paragraph stating this for the group summary to the query.
+    query.groupSummary = '<p>No classified issues contributed to the score.</p>'
+  }
+};