testilo 13.3.2 → 13.4.0

package/README.md

@@ -469,15 +469,13 @@ A module can invoke `digest` in this way:
 
 ```javaScript
 const {digest} = require('testilo/digest');
-const digesterDir = `${process.env.FUNCTIONDIR}/digest/dp99a`;
-fs.readFile(`${digesterDir}/index.html`, 'utf8')
-.then(template => {
-  const {digester} = require(`${digesterDir}/index`);
-  const digestedReports = digest(template, digester, scoredReports);
-});
+const digesterDir = `${process.env.FUNCTIONDIR}/digest/tdp99a`;
+const {digester} = require(`${digesterDir}/index`);
+digest(digester, scoredReports)
+.then(digestedReports => {…});
 ```
 
-The first two arguments to `digest()` are a digest template and a digesting function. In this example, they have been obtained from files in the Testilo package, but they could be custom-made. The third argument to `digest()` is an array of scored report objects. The `digest()` function returns an array of digested reports. The invoking module can further dispose of the digested reports as needed.
+The first argument to `digest()` is a digesting function. In this example, it has been obtained from a files in the Testilo package, but it could be custom-made. The second argument to `digest()` is an array of scored report objects. The `digest()` function returns an array of digested reports. The invoking module can further dispose of the digested reports as needed.
 
 #### By a user
 
@@ -505,12 +503,11 @@ To test the `digest` module, in the project directory you can execute the statem
 
 If you use Testilo to perform a battery of tests on multiple targets, you may want a single report that compares the total scores received by the targets. Testilo can produce such a _comparative report_.
 
-The `compare` module compares the scores in a collection of scored reports. Its `compare()` function takes three arguments:
-- a comparison template
+The `compare` module compares the scores in a collection of scored reports. Its `compare()` function takes two arguments:
 - a comparison function
 - an array of scored reports
 
-The comparison template is an HTML document containing placeholders. A copy of the template, with its placeholders replaced by computed values, becomes the comparative report. The comparison function defines the rules for replacing the placeholders with values. The Testilo package contains a `procs/compare` directory, in which there are subdirectories containing pairs of templates and modules that export comparison functions. You can use one of those pairs, or you can create your own.
+The comparison function defines the rules for generating an HTML file comparing the scored reports. The Testilo package contains a `procs/compare` directory, in which there are subdirectories containing modules that export comparison functions. You can use one of those functions, or you can create your own.
 
 ### Invocation
 
@@ -521,31 +518,30 @@ There are two ways to use the `compare` module.
 A module can invoke `compare` in this way:
 
 ```javaScript
-const fs = require('fs/promises);
 const {compare} = require('testilo/compare');
 const comparerDir = `${process.env.FUNCTIONDIR}/compare/tcp99`;
-fs.readFile(`${comparerDir}/index.html`)
-.then(template => {
-  const {comparer} = require(`${comparerDir}/index`);
-  const comparativeReport = compare(template, comparer, scoredReports);
-});
+const {comparer} = require(`${comparerDir}/index`);
+compare(comparer, scoredReports)
+.then(comparison => {…});
 ```
 
-The first two arguments to `compare()` are a template and a comparison function. In this example, they have been obtained from files in the Testilo package, but they could be custom-made. The third argument to `compare()` is an array of report objects. The `compare()` function returns a comparative report. The invoking module can further dispose of the comparative report as needed.
+The first argument to `compare()` is a comparison function. In this example, it been obtained from a file in the Testilo package, but it could be custom-made. The second argument to `compare()` is an array of report objects. The `compare()` function returns a comparative report. The invoking module can further dispose of the comparative report as needed.
 
 #### By a user
 
 A user can invoke `compare` in this way:
 
 ```bash
-node call compare tcp99 legislators
+node call compare tcp99 legislators 23pl
 ```
 
 When a user invokes `compare` in this example, the `call` module:
-- gets the template and the comparison module from subdirectory `tcp99` of the subdirectory `compare` in the `process.env.FUNCTIONDIR` directory.
-- gets all the reports in the `scored` subdirectory of the `process.env.REPORTDIR` directory.
+- gets the comparison module from subdirectory `tcp99` of the subdirectory `compare` in the `process.env.FUNCTIONDIR` directory.
+- gets all the reports in the `scored` subdirectory of the `process.env.REPORTDIR` directory whose file names begin with `23pl`.
 - writes the comparative report as an HTML file named `legislators.html` to the `comparative` subdirectory of the `process.env.REPORTDIR` directory.
 
+The fourth argument to `call` (`23pl` in this example) is optional. If it is omitted, `call` will get and `comparer` will compare all the reports in the `scored` directory.
+
 The comparative report created by `compare` is an HTML file, and it expects a `style.css` file to exist in its directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into the directory where comparative reports are written.
 
 ### Validation

package/call.js

@@ -131,8 +131,8 @@ const callDigest = async (digesterID, selector = '') => {
   const reports = await getReports('scored', selector);
   // If any exist:
   if (reports.length) {
-    const digesterDir = `${functionDir}/digest/${digesterID}`;
     // Get the digester.
+    const digesterDir = `${functionDir}/digest/${digesterID}`;
     const {digester} = require(`${digesterDir}/index`);
     // Digest the reports.
     const digestedReports = await digest(digester, reports);
@@ -152,15 +152,20 @@ const callDigest = async (digesterID, selector = '') => {
 };
 // Fulfills a comparison request.
 // Get the scored reports to be scored.
-const callCompare = async (compareProcID, comparisonNameBase) => {
-  const reports = await getReports('scored');
-  const comparerDir = `${functionDir}/compare/${compareProcID}`;
-  const comparisonTemplate = await fs.readFile(`${comparerDir}/index.html`, 'utf8');
-  const comparer = require(`${comparerDir}/index`).getQuery;
-  const comparison = await compare(comparisonTemplate, comparer, reports);
-  const comparisonDir = `${reportDir}/comparative`;
-  await fs.writeFile(`${comparisonDir}/${comparisonNameBase}.html`, comparison);
-  console.log(`Comparison completed. Proc: ${compareProcID}. Directory: ${comparisonDir}.`);
+const callCompare = async (compareProcID, comparisonNameBase, selector = '') => {
+  const reports = await getReports('scored', selector);
+  // If any exist:
+  if (reports.length) {
+    // Get the comparer.
+    const comparerDir = `${functionDir}/compare/${compareProcID}`;
+    const {comparer} = require(`${comparerDir}/index`);
+    // Compare the reports.
+    const comparison = await compare(comparer, reports);
+    // Save the comparison.
+    const comparisonDir = `${reportDir}/comparative`;
+    await fs.writeFile(`${comparisonDir}/${comparisonNameBase}.html`, comparison);
+    console.log(`Comparison completed and saved in ${comparisonDir}`);
+  }
 };
 
 // ########## OPERATION
@@ -214,7 +219,7 @@ else if (fn === 'multiDigest' && fnArgs.length === 1) {
     console.log('Execution completed');
   });
 }
-else if (fn === 'compare' && fnArgs.length === 2) {
+else if (fn === 'compare' && fnArgs.length > 1 && fnArgs.length < 4) {
   callCompare(... fnArgs)
   .then(() => {
     console.log('Execution completed');

package/compare.js

@@ -1,22 +1,16 @@
 /*
   compare.js
-  Creates a comparative report from scored reports.
+  Creates a comparison from scored reports.
+  Arguments:
+    0. Comparing function.
+    1. Array of scored reports.
 */
 
 // ########## FUNCTIONS
 
-// Replaces the placeholders in a template with eponymous query parameters.
-const replaceHolders = (template, query) => template
-.replace(/__([a-zA-Z]+)__/g, (ph, qp) => query[qp]);
 // Compares the scored reports and returns a comparison.
-exports.compare = async (comparisonTemplate, comparer, reports) => {
-  // Create a query.
-  const query = {};
-  // Populate the query.
-  await comparer(reports, query);
-  // Use it to create a comparison.
-  const comparison = replaceHolders(comparisonTemplate, query);
+exports.compare = async (comparer, scoredReports) => {
   // Return the comparison.
-  console.log(`Comparison complete. Report count: ${reports.length}`);
-  return comparison;
+  console.log(`Comparison complete. Report count: ${scoredReports.length}`);
+  return comparer(scoredReports);
 };

package/digest.js

@@ -1,6 +1,6 @@
 /*
   digest.js
-  Creates digests from a scored reports.
+  Creates digests from scored reports.
   Arguments:
     0. Digesting function.
     1. Array of scored reports.

package/package.json

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

package/procs/compare/tcp27/index.html

@@ -0,0 +1,47 @@
+<!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 procedure <code>__scriptID__</code></li>
+        <li>Scored by <a href="https://www.npmjs.com/package/testilo">Testilo</a> with procedure <code>__scorer__</code></li>
+        <li>Digested by Testilo with procedure <code>__digester__</code></li>
+        <li>Compared by Testilo with procedure <code>__comparer__</code></li>
+      </ol>
+      <p>Testaro used ten tools (Alfa, Axe, Continuum, Equal Access, HTML CodeSniffer, Nu Html Checker, Tenon, Testaro, and WAVE) to perform about 1350 automated accessibility tests. Testilo used its scoring procedure to 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 (from best to worst)</tr>
+        </thead>
+        <tbody class="linkSmaller secondCellRight">
+          __tableBody__
+        </tbody>
+      </table>
+      <h2>Disclaimer</h2>
+      <p>Other tests and scoring formulae would produce different results. The algorithms underlying these results can be inspected in the Testaro and Testilo packages and can be revised 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>

package/procs/compare/tcp27/index.js

@@ -0,0 +1,83 @@
+// index: comparer for scoring procedure tsp27
+
+// ########## IMPORTS
+
+// Module to access files.
+const fs = require('fs/promises');
+
+// CONSTANTS
+
+// Digester ID.
+const id = 'tcp27';
+// Newlines with indentations.
+const joiner = '\n      ';
+const innerJoiner = '\n        ';
+const innestJoiner = '\n          ';
+
+// ########## FUNCTIONS
+
+// Returns data on the targets.
+const getData = async scoredReports => {
+  const bodyData = [];
+  for (const report of scoredReports) {
+    const {id, sources, score} = report;
+    bodyData.push({
+      id,
+      org: sources.target.what,
+      url: sources.target.which,
+      score: score.summary.total
+    });
+  };
+  return {
+    pageCount: scoredReports.length,
+    script: scoredReports[0].sources.script,
+    bodyData
+  }
+};
+// Returns the maximum score.
+const getMaxScore = tableData => tableData.reduce((max, item) => Math.max(max, item.score), 0);
+// Converts report data to a table body.
+const getTableBody = async bodyData => {
+  const maxScore = getMaxScore(bodyData);
+  const rows = bodyData
+  .sort((a, b) => a.score - b.score)
+  .map(item => {
+    const {id, org, url, score} = item;
+    const pageCell = `<th scope="row"><a href="${url}">${org}</a></th>`;
+    const numCell = `<td><a href="digests/${id}.html">${score}</a></td>`;
+    // Make the bar width proportional.
+    const barWidth = 100 * score / maxScore;
+    const bar = `<rect height="100%" width="${barWidth}%" fill="red"></rect>`;
+    const barCell = `<td aria-hidden="true"><svg width="100%" height="0.7em">${bar}</svg></td>`;
+    const row = `<tr>${pageCell}${numCell}${barCell}</tr>`;
+    return row;
+  });
+  return rows.join(innestJoiner);
+};
+// Populates a query for a comparative table.
+const populateQuery = async (scoredReports, query) => {
+  const data = await getData(scoredReports);
+  query.pageCount = data.pageCount;
+  query.scriptID = scoredReports[0].sources.script;
+  query.scorer = 'tsp27';
+  query.digester = 'tdp27';
+  query.comparer = 'tcp27';
+  query.tableBody = await getTableBody(data.bodyData);
+  const date = new Date();
+  query.dateISO = date.toISOString().slice(0, 10);
+  query.dateSlash = query.dateISO.replace(/-/g, '/');
+};
+// Returns a digested report.
+exports.comparer = async scoredReports => {
+  // Create a query to replace placeholders.
+  const query = {};
+  populateQuery(scoredReports, query);
+  // Get the template.
+  let template = await fs.readFile(`${__dirname}/index.html`, 'utf8');
+  // Replace its placeholders.
+  Object.keys(query).forEach(param => {
+    template = template.replace(new RegExp(`__${param}__`, 'g'), query[param]);
+  });
+  // Return the digest.
+  return template;
+};

package/procs/digest/tdp27/index.html

@@ -29,24 +29,27 @@
         </table>
       </header>
       <h2>Introduction</h2>
-      <p>This is a digest of results from a battery of accessibility tests.</p>
-      <p>The battery includes about 1350 tests drawn from ten different packages: Alfa, Axe, Continuum, Equal Access, HTML CodeSniffer, Nu Html Checker, QualWeb, Tenon, Testaro, and WAVE.</p>
-      <p>These tests were run on the web page named above and gave the page a score of __total__, where 0 would be <q>perfect</q>.</p>
-      <h2>Scores</h2>
+      <p>This is a digest of results from a battery of <a href="https://www.w3.org/WAI/">web accessibility</a> tests.</p>
+      <p>Ten different <dfn>tools</dfn> (Alfa, Axe, Continuum, Equal Access, HTML CodeSniffer, Nu Html Checker, QualWeb, Tenon, Testaro, and WAVE) tested the web page of __org__ at __url__ to check its compliance with various <dfn>rules</dfn>. There were a total of about 1350 rules, classified into about 250 accessibility <dfn>issues</dfn>.</p>
+      <p>The results were interpreted to yield an aggregate score of __total__, where 0 would be <q>perfect</q>.</p>
+      <h2>Total score</h2>
+      <p>The total score is the sum of five components.</p>
       <table class="allBorder secondCellRight">
         <caption>Score summary</caption>
         <thead>
-          <tr><th>Component</th><th>Score</th></tr>
+          <tr><th>Component</th><th>Score</th><th>Description</th></tr>
         </thead>
         <tbody class="headersLeft">
-          <tr><th>total</th><td>__total__</td></tr>
-          <tr><th>issue</th><td>__issue__</td></tr>
-          <tr><th>tool</th><td>__tool__</td></tr>
-          <tr><th>prevention</th><td>__prevention__</td></tr>
-          <tr><th>log</th><td>__log__</td></tr>
-          <tr><th>latency</th><td>__latency__</td></tr>
+          <tr><th>total</th><td>__total__</td><td>Sum of the component scores</td></tr>
+          <tr><th>issue</th><td>__issue__</td><td>Severity and number of reported defects</td></tr>
+          <tr><th>tool</th><td>__tool__</td><td>Tool-by-tool defect ratings</td></tr>
+          <tr><th>prevention</th><td>__prevention__</td><td>Failed attempts by tools to test the page</td></tr>
+          <tr><th>log</th><td>__log__</td><td>Browser warnings about the page</td></tr>
+          <tr><th>latency</th><td>__latency__</td><td>Abnormal delay in page responses</td></tr>
         </tbody>
       </table>
+      <h2>Issue scores</h2>
+      <p>The score of an issue depends on the <dfn>severity</dfn> (user impact and certainty) of the issue and on how many instances were reported (by one or more tools).</p>
       <table class="allBorder secondCellRight">
         <caption>Issue scores</caption>
         <thead>
@@ -56,8 +59,10 @@
           __issueRows__
         </tbody>
       </table>
-      <h2>Issues</h2>
+      <h2>Itemized issues</h2>
+      <p>The reported rule violations are itemized below, issue by issue. Additional details can be inspected in the complete report at the end of this page.</p>
       __issueDetailRows__
+      <h2>Complete report</h2>
       <pre>__report__</pre>
       <footer>
         <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>

package/procs/digest/tdp27/index.js

@@ -62,7 +62,7 @@ const populateQuery = (report, query) => {
   // Add paragraph groups about the issue details to the query.
   const issueDetailRows = [];
   issueIDs.forEach(issueID => {
-    issueDetailRows.push(`<h3>Issue <code>${issueID}</code></h3>`);
+    issueDetailRows.push(`<h3 class="bars">Issue <code>${issueID}</code></h3>`);
     issueDetailRows.push(`<p>WCAG: ${issueClasses[issueID].wcag || 'N/A'}</p>`);
     const issueData = details.issue[issueID];
     issueDetailRows.push(`<p>Score: ${issueData.score}</p>`);

package/reports/digested/style.css

@@ -47,6 +47,9 @@ fieldset {
 form {
   margin-top: 1rem;
 }
+h1, h2, h3, h4, h5, h6 {
+  margin-bottom: 0;
+}
 h2 {
   font-size: 1.8rem;
   margin: 1rem auto 0.5rem auto;
@@ -55,6 +58,10 @@ h2 {
 h3 {
   font-size: 1.6rem;
 }
+h3.bars {
+  border-top: solid black 0.1rem;
+  padding-top: 0.3rem;
+}
 h4 {
   font-size: 1.4rem;
 }