testilo 3.12.3 → 4.0.0

package/README.md

@@ -1,72 +1,147 @@
 # testilo
-Scorer and digester of Testaro reports
+Utilities for Testaro
 
 ## Introduction
 
-This application enriches [Testaro](https://www.npmjs.com/package/testaro) reports. Testaro performs digital accessibility tests on web artifacts and creates reports in JSON format. To make those reports more useful, this application, Testilo, computes scores, converts the scored reports to human-readable web pages (_digests_), and compiles human-readable web pages comparing the scores of multiple artifacts.
+The Testilo package contains utilities that facilitate the use of the [Testaro package](https://www.npmjs.com/package/testaro).
+
+Testaro performs digital accessibility tests on web artifacts and creates reports in JSON format. The utilities in Testilo prepare jobs for Testaro to run and create additional value from the reports that Testaro produces.
 
 ## Dependencies
 
-The `dotenv` dependency lets you set environment variables in an untracked `.env` file.
+The `dotenv` dependency lets you set environment variables in an untracked `.env` file. This prevents secret data, such as passwords, from being shared as part of this package.
 
 ## Architecture
 
-The routines that perform scoring, digesting, and comparing are _procs_ and are located in the `procs` directory.
+Testilo is written in Node.js. Commands are given to Testilo in a command-line (terminal) interface or programmatically.
+
+Shared routines that perform scoring, digesting, and comparing are _procs_ and are located in the `procs` directory.
+
+Testilo can be installed wherever Node.js (version 14 or later) is installed. This can be a server or the same workstation on which Testaro is installed.
+
+The reason for Testilo being an independent package, rather than part of Testaro, is that Testilo can be installed on any host, while Testaro can run successfully only on a Windows or Macintosh workstation (and perhaps on some workstations with Ubuntu operating systems). Testaro runs tests similar to those that a human accessibility tester would run, using whatever browsers, input devices, system settings, simulated and attached devices, and assistive technologies tests may require. Thus, Testaro is limited to functionalities that require workstation attributes. For maximum flexibility in the management of Testaro jobs, all other functionalities are located outside of Testaro. You could have software such as Testilo running on a server, communicating with multiple workstations running Testaro, receiving job orders from the server and returning job results to the server for further processing.
+
+## Utilities
+
+### `merge`
+
+Testaro runs _jobs_. A job gives Testaro instructions.
+
+Sometimes you may want Testaro to perform a set of tests on multiple targets. The `merge` utility in Testilo facilitates this. It creates Testaro jobs out of a _script_ and a _batch_.
+
+A script tells Testaro where to go and what to do. If the where-to-go part identifies a specific URL, the script can be a job, ready for Testaro to run. But the where-to-go part can also be generic, such as `http://*.*`. Then the script needs to be converted to a job by having its generic destination replaced with a specific URL. A batch is a list of _hosts_ (URLs and metadata). Merging a batch and a script means generating from the script as many jobs as there are hosts in the batch. In each job, one host from the batch becomes the specific target.
+
+A script is a JSON file representing a `script` object, which contains a sequence of _commands_. Scripts are documented in detail in the Testaro `README.md` file.
+
+A batch is a JSON file representing a `batch` object, which contains an array of _hosts_. Each host is an object with three properties:
+- `id`: a string unique in the batch
+- `which`: a URL
+- `what`: a string naming the entity associated with the URL
+
+The batch as a whole also has three properties:
+- `id`: a string composed of ASCII letters and digits
+- `what`: a string describing the batch
+- `hosts`: an array of host objects
+
+Here is an example of a batch:
+
+```json
+{
+  "id": "usFedExec1",
+  "what": "United States federal executive agencies",
+  "hosts": [
+    {
+      "id": "achp",
+      "which": "https://www.achp.gov/",
+      "what": "Advisory Council on Historic Preservation (ACHP)"
+    },
+    {
+      "id": "agm",
+      "which": "https://www.usagm.gov/",
+      "what": "Agency for Global Media"
+    }
+  ]
+}
+```
+
+The `merge` utility finds all the `url` commands in a script (telling the browser what to visit), replaces them with one of the hosts in the batch, and outputs the modified script as a job. It then does the same with each of the other hosts in the batch.
+
+To execute `merge`, you need to have three environment variables defined to tell `merge` where files are located. You can define the environment variables in the `.env` file. Here is an example:
+
+```
+SCRIPTDIR=../testing/scripts
+BATCHDIR=../testing/batches
+JOBDIR=../testing/jobs
+```
+
+In this example, the script, batch, and job files are located in directories named `scripts`, `batches`, and `jobs` within `testing`, which is a sibling directory of the Testilo project directory.
+
+The syntax of the `merge` statement is documented in `merge.js`.
+
+Suppose that:
+- The environment variables are defined as in the above example.
+- There is a script file named `testall.json`.
+- The above batch example is in a file named `usFedExec1.json`.
+
+The statement `node merge testall usFedExec1 allFedExec` would tell Testilo to merge the batch `../testing/batches/usFedExec1.json` and the script `../testing/scripts/testall.json` and write the two job files in `../testing/jobs/allFedExec`.
+
+### `score`
 
-To score reports, Testilo needs to be told which reports to score and which scoring procedure (or _score proc_) to use.
+Testaro performs tests and produces reports of test results. Testilo can add scores to those reports. In this way, each report can not only detail successes and failures of individual tests but also assign scores to those results and combine the partial scores into total scores.
 
-Similarly, once reports have been scored, Testilo can digest them. For this purpose, Testilo needs to be told which scored reports to digest and which _digest proc_ to use.
+The `score` utility performs scoring. It depends on score procs to define the scoring rules. Some score procs are in the Testilo package (in the `procs/score` directory), and you can create more score procs to implement different rules.
 
-Likewise, Testilo can compare scored reports. It needs to be told which reports to compare and which _comparison proc_ to use.
+You can score multiple reports with a single invocation of `score`.
 
-Testilo includes some score procs, digest procs, and comparison procs. You can add others.
+To execute `score`, you need to have two environment variables defined to tell `score` where files are located. You can define the environment variables in the `.env` file. Here is an example:
 
-## Execution
+```
+REPORTDIR_RAW=../testing/reports/raw
+REPORTDIR_SCORED=../testing/reports/scored
+```
 
-### Scoring
+The named directories must already exist.
 
-#### Process
+The syntax of the `score` statement is documented in `score.js`.
 
-To score Testaro reports, execute the statement `node score procID reportNameStart`. Replace (here and below) `procID` with the base of the name of the score proc. An environment variable named `REPORTDIR_RAW` defines a directory (i.e. a filesystem path, relative to the project directory of Testilo) where Testilo will look for the raw (i.e. not-yet-scored) reports. If you want Testilo to score all of the reports in that directory, you can omit the `reportNameStart` argument. If, instead, you want Testilo to score only the reports in that directory whose names begin with a certain string, replace `reportNameStart` with that string. So, for example, suppose the raw reports are in the `reports/raw` directory of a project, `testing`, that sits alongside of Testilo in your filesystem. Then you would assign the value `'../testing/reports/raw'` to the environment variable `REPORTDIR_RAW`. Now, to score all of the reports in that directory with score proc `sp11a`, execute `node score sp11a`. Or, to score only the reports in that directory whose filenames begin with `4rper`, execute  node score sp11a `4rper`.
+A scored report file is identical to the file it was created from, except that the scored report has new properties named `score` and `scoreProcID`. The `score` property contains the scores.
 
-This procedure has two preconditions:
-- The score proc is compatible with the script (or _test proc_) that produced the report(s).
-- You have defined environment variables `REPORTDIR_RAW` and (for the scored reports that Testilo will write) `REPORTDIR_SCORED`.
+### `digest`
 
-The scored report file has the same name as the original. The scored report has the same content as the original, plus new properties named `score` and `scoreProcID`.
+Testaro reports, both originally and after they are scored, are JSON files. That format is basically designed for machine tractability.
 
-#### Procedures
+The `digest` utility converts scored reports into HTML documents with explanatory content. Thus, it converts machine-oriented reports into human-oriented reports, called _digests_. It depends on digest procs to define the digesting rules. Some digest procs are in the Testilo package (in the `procs/digest` directory), and you can create more digest procs to implement different rules.
 
-The score procs included with Testilo represent milestones in the refinement of a scoring methodology.
+You can digest multiple scored reports with a single invocation of `digest`.
 
-One development has been an expansion of the set of packages. The progression from score proc `sp09a` to `sp10a` included the addition of the Tenon package.
+To execute  `digest`, you need to have two environment variables defined to tell `digest` where files are located. You can define the environment variables in the `.env` file. Here is an example:
 
-The main development has been a change from package-based to issue-based scoring. With package-based scoring, each package yielded a score, and the scores were summed into a total score. With issue-based scoring, the individual tests in each package are classified into groups, such that the tests from various packages in any particular group all seek to discover approximately the same type of accessibility issue. An artifact gets a score on each group, and the group scores are summed into a total score. The change from package-based to issue-based scoring took place in the progression from score proc `sp10a` to `sp10b`.
+```
+REPORTDIR_SCORED=../testing/reports/scored
+REPORTDIR_DIGESTED=../testing/reports/digested
+```
 
-The problem of combining partly similar tests from different packages and producing an appropriate accessibility score has no perfect solution, and each successive score proc embodies efforts to make the result more appropriate.
+The named directories must already exist.
 
-#### Prevention
+The syntax of the `digest` statement is documented in `digest.js`.
 
-Testaro reports an error when it is unable to perform a test on a host. A score proc can take such errors into account. The score procs included with Testilo do that by estimating scores when a package cannot be run.
+The digests created by `digest` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/digested/style.css` file in Testilo is an appropriate stylesheet to be copied into `process.env.REPORTDIR_DIGESTED`.
 
-### Digesting
+### `compare`
 
-To make scored Testaro reports more useful for humans, Testilo can create digests of scored reports. A digest is an HTML document (a web page) summarizing and explaining the findings, with the scored report appended to it.
+You can summarize the results of a multi-host job by producing a document comparing the scores received by the hosts. The `compare` utility does this.
 
-To make Testilo digest reports, execute the statement `node digest procID reportNameStart`. The rules for this statement are the same as for the `score` statement, except that the directory where Testilo finds the reports in the one referenced by the `REPORTDIR_SCORED` environment variable, and the directory where Testilo will write the digests is the one referenced by `REPORTDIR_DIGESTED`. In order to make the digests appear correct in a browser, you must copy the `reports/digested/style.css` file into the `REPORTDIR_DIGESTED` directory.
+The `compare` utility gathers scores from a set of scored reports and produces an HTML document comparing the scores. It depends on compare procs to define the rules for making and showing the comparative scores. Some compare procs are in the Testilo package (in the `procs/compare` directory), and you can create more compare procs to implement different rules.
 
-### Comparing
+To execute  `compare`, you need to have two environment variables defined to tell `digest` where files are located. You can define the environment variables in the `.env` file. Here is an example:
 
-You can use Testilo to publish comparisons of accessibility scores. To do this, execute the statement `node compare abc xyz`, replacing `abc` with a filename base for the comparison and `xyz` with the name of a subdirectory of the `procs/compare` directory.
+```
+REPORTDIR_SCORED=../testing/reports/scored
+COMPARISONDIR=../testing/reports/compared
+```
 
-Testilo will examine all of the scored reports in the `REPORTDIR_SCORED` directory. The comparison proc in the `xyz` directory will construct a web page. Testilo will save the page in the `COMPARISONDIR` directory. The name of the file will be `abc.html`.
+The named directories must already exist.
 
-Comparison procs can design various pages on the basis of a set of scored reports. As an example, the `cp0` comparison proc creates a page that contains a table of scores, shown both numerically and with a bar graph. In the table, the first column contains descriptions of the pages (the `what` property of the hosts in the batch), such as “Wikipedia English”. Each such description is a link to the page on the web. The second column contains the scores of the pages. Each score is a link to the digest for its page. The link points to a digest located in a `digests` directory adjacent to the page itself. Thus, to use the `cp0` comparison proc, you would copy its output file to a web server, create a `digests` directory on the server as a sibling of that file, and copy the digest files into the `digests` directory.
+The syntax of the `compare` statement is documented in `compare.js`.
 
-This procedure has some preconditions:
-- The comparison proc is compatible with the score proc that scored the report.
-- Testilo can find the scored report files in the directory whose relative path (relative to the project directory of Testilo) is the value of the `REPORTDIR_SCORED` environment variable.
-- Testilo can read in the `REPORTDIR_SCORED` directory.
-- There is a `COMPARISONDIR` environment variable, whose value is the relative path of a directory that Testilo can write to.
-- The `procs/compare` directory contains a subdirectory named `xyz`, which in turn contains files named `index.html` and `index.js`.
-- You have copied the `reports/comparative/style.css` file into the `COMPARISONDIR` directory.
+The comparisons created by `compare` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into `process.env.COMPARISONDIR`.

package/compare.js

@@ -1,7 +1,12 @@
 /*
   compare.js
-  Testilo comparison script.
-  Usage example: node compare cp12a candidates
+  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).
 */
 
 // ########## IMPORTS

package/digest.js

@@ -1,7 +1,13 @@
 /*
   digest.js
-  Testilo digesting script.
-  Usage example: node digest 35k1r-railpass dp10a
+  Creates digests from scored reports.
+  Reads reports in process.env.REPORTDIR_SCORED and outputs into process.env.REPORTDIR_DIGESTED.
+  Arguments:
+    0. Base of name of digest proc located in procs/digest.
+    1?. starting substring of names of reports in process.env.REPORTDIR_SCORED.
+  Usage examples:
+    node digest dp18a 35k1r (to digest all scored reports with names starting with 35k1r)
+    node digest dp18a (to digest all scored reports)
 */
 
 // ########## IMPORTS
@@ -23,7 +29,7 @@ const reportIDStart = process.argv[3];
 // 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.
+// Creates digests.
 const digest = async () => {
   const reportDirScoredAbs = `${__dirname}/${reportDirScored}`;
   let reportFileNames = await fs.readdir(reportDirScoredAbs);

package/merge.js

@@ -0,0 +1,72 @@
+/*
+  merge.js
+  Merges a batch and a script to produce 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. name of subdirectory of process.env.JOBDIR into which to write host scripts.
+  Usage example:
+    node merge tp18 weborgs tp18-weborgs-1
+  Note: The subdirectory for host scripts will be created if it does not exist.
+*/
+
+// ########## IMPORTS
+
+// Module to keep secrets.
+require('dotenv').config();
+// Module to read and write files.
+const fs = require('fs/promises');
+
+// ########## CONSTANTS
+
+const scriptDir = process.env.SCRIPTDIR || 'scripts';
+const batchDir = process.env.BATCHDIR || 'batches';
+const jobDir = process.env.JOBDIR || 'jobs';
+const scriptName = process.argv[2];
+const batchName = process.argv[3];
+const jobSubdir = process.argv[4];
+
+// ########## FUNCTIONS
+
+// Merges a batch into a script and writes host scripts.
+const merge = async (script, batch, timeStamp, outDir) => {
+  await fs.mkdir(outDir, {recursive: true});
+  const {hosts} = batch;
+  // For each host in the batch:
+  const jobs = hosts.map(host => {
+    // Copy the script.
+    const newScript = JSON.parse(JSON.stringify(script));
+    // In the copy, make all url commands visit the host.
+    newScript.commands.forEach(command => {
+      if (command.type === 'url') {
+        command.which = host.which;
+        command.what = host.what;
+      }
+    });
+    // Create a host script.
+    return {
+      id: `${timeStamp}-${host.id}`,
+      host,
+      script: newScript
+    };
+  });
+  // Write the host scripts.
+  for (const job of jobs) {
+    await fs.writeFile(`${outDir}/${job.id}.json`, JSON.stringify(job, null, 2));
+  };
+  console.log(`Merger completed. Count of jobs created: ${hosts.length}`);
+};
+
+// ########## OPERATION
+
+fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8')
+.then(scriptFile => {
+  fs.readFile(`${batchDir}/${batchName}.json`, 'utf8')
+  .then(async batchFile => {
+    const script = JSON.parse(scriptFile);
+    const batch = JSON.parse(batchFile);
+    const timeStamp = Math.floor((Date.now() - Date.UTC(2022, 1)) / 2000).toString(36);
+    const outDir = `${jobDir}/${jobSubdir}`;
+    await merge(script, batch, timeStamp, outDir);
+  });
+});

package/package.json

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

package/procs/digest/dp16a/index.html

@@ -42,7 +42,7 @@
       </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>sp16a</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>dp16a</code> to produce this digest, briefly explaining how <code>sp15c</code> computed the scores.</p>
+      <p>Finally, Testilo used procedure <code>dp16a</code> to produce this digest, briefly explaining how <code>sp16a</code> computed the scores.</p>
       <h2>Score summary</h2>
       <table class="allBorder secondCellRight">
         <caption>Score components</caption>

package/procs/digest/dp18a/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>__tp__</code></p>
+          <p><strong>Scored by</strong>: Testilo, procedure <code>__sp__</code></p>
+          <p><strong>Digested by</strong>: Testilo, procedure <code>__dp__</code></p>
+        </div>
+      </header>
+      <h2>Introduction</h2>
+      <p>The <a href="https://www.npmjs.com/package/testaro">Testaro</a> application used its <code>__tp__</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 1230 tests. Of these, 24 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>__sp__</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>__dp__</code> to produce this digest, briefly explaining how <code>__sp__</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>__sp__</code>. You can modify and extend Testaro and Testilo to fit other theories and priorities.</p>
+      <p>Here, in brief, is how <code>__sp__</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>sp15c</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>__sp__</code> are found in the <a href="https://github.com/jrpool/testilo/blob/main/procs/score/__sp__.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/dp18a/index.js

@@ -0,0 +1,129 @@
+/*
+  index: digester for scoring procedure sp18a.
+  Creator of parameters for substitution into index.html.
+  Usage example for selected files in REPORTDIR_SCORED: node digest dp18a 35k1r
+  Usage example for all files in REPORTDIR_SCORED: node digest dp18a
+*/
+
+// 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 {script, host, score} = report;
+  const reportJSON = JSON.stringify(report, null, 2);
+  const reportJSONSafe = htmlEscape(reportJSON);
+  query.report = reportJSONSafe;
+  query.tp = 'tp18';
+  query.sp = 'sp18a';
+  query.dp = 'dp18a';
+  // Add the job data to the query.
+  query.dateISO = report.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 = script.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>'
+  }
+};

package/procs/score/sp16b.js

@@ -1,5 +1,5 @@
 /*
-  sp16a
+  sp16b
   Testilo score proc 16b
 
   Computes scores from Testaro script tp16 and adds them to a report.