testilo 38.0.2 → 39.0.1

package/README.md

@@ -786,10 +786,14 @@ To test the `digest` module, in the project directory you can execute the statem
 
 ### Summarization
 
-The `summarize` module of Testilo can summarize a scored report. The summary is an object that contains these properties from the report: `id`, `endTime`, `sources`, and `score` (the value of the `score.total` property of the report).
+The `summarize` module of Testilo can summarize a scored report. The summary is an object that contains these properties from the report: `id`, `endTime`, `targetWhat` (description of the target), `url` (of the target), `sources`, and `score` (only the value of the `score.total` property of the report).
+
+Report summaries make some operations more efficient by allowing other modules to get needed data from summaries instead of from reports. The size of a summary tends to be about 0.01% of the size of a report.
 
 #### Invocation
 
+The `summarize` module summarizes one report when invoked by a module, but the `call` module invoked by a user can call `summarize` multiple times to summarize multiple reports and combine those summaries into a file.
+
 ##### By a module
 
 A module can invoke `summarize()` in this way:
@@ -819,10 +823,6 @@ When a user invokes `summarize` in this example, the `call` module:
 - creates a _summary report_, an object containing three properties: `id` (an ID), `what` (a description, such as `'divisions'`), and `summaries` (the array of summaries).
 - writes the summary report in JSON format to the `summarized` subdirectory of the `REPORTDIR` directory, using the ID as the base of the file name.
 
-#### Summary reports
-
-A summary report serves as a necessary input to the `compare` and `track` modules described below. When a user invokes the `compare` module, a summary report is produced. A module can create a summary report by invoking `compare` multiple times on different scored reports, assembling the resulting summaries into an array, and creating an object like the one the `call` module creates for a user.
-
 ### Comparison
 
 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 _comparison_.
@@ -833,7 +833,7 @@ The `compare` module compares the scores in a summary report. The `compare()` fu
 
 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.
 
-Summary reports suitable for comparisons are those that contain one result per target. If a summary report contains results from multiple times per target, tracking (described below) is appropriate, rather than comparison.
+The built-in comparison functions compare all of the scores in the summary report. Thus, if the summary report contains multiple scores for the same target, based on tests performed at various times, those scores will all appear in the comparison, labeled identically with the `what` description of the target. If you want only one score per target to appear, you can create a new summary report that includes only one summary per target in its `summaries` array.
 
 #### Invocation
 
@@ -864,7 +864,7 @@ node call compare 'state legislators' tcp99 240813
 
 When a user invokes `compare` in this example, the `call` module:
 - gets the comparison module from subdirectory `tcp99` of the subdirectory `compare` in the `FUNCTIONDIR` directory.
-- gets the first summary report whose file name begins with `'240813'` from the `summarized` subdirectory of the `REPORTDIR` directory.
+- gets the last summary report whose file name begins with `'240813'` from the `summarized` subdirectory of the `REPORTDIR` directory.
 - creates an ID for the comparison.
 - creates the comparison as an HTML document.
 - writes the comparison in the `comparative` subdirectory of the `REPORTDIR` directory, with `state legislators` as a description and the ID as the base of the file name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testilo",
-  "version": "38.0.2",
+  "version": "39.0.1",
   "description": "Prepares Testaro jobs and processes Testaro reports",
   "main": "call.js",
   "scripts": {

package/procs/compare/tcp43/index.html

@@ -0,0 +1,42 @@
+<!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: __what__</title>
+    <link rel="icon" href="favicon.ico">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility score comparison: __what__</h1>
+      </header>
+      <h2>Introduction</h2>
+      <p>This is comparison __id__.</p>
+      <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 tested by <a href="https://www.npmjs.com/package/testaro">Testaro</a>. Testaro used ten tools (Alfa, ASLint, Axe, Editoria11y, Equal Access, HTML CodeSniffer, Nu Html Checker, QualWeb, Testaro, and WAVE) to perform about 900 automated accessibility tests.</p>
+      <p><a href="https://www.npmjs.com/package/testilo">Testilo</a> classified the problems found by these tests into <dfn>issues</dfn> and assigned a <dfn>score</dfn> to each page. A perfect score would be 0. Higher scores indicate more issues, more instances of them, more serious issues, and more of the tools reporting instances of issues.</p>
+      <h2>Comparison</h2>
+      <table class="allBorder redBar">
+        <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 procedures would yield different scores and rank orders among these pages.</p>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/compare/tcp43/index.js

@@ -0,0 +1,84 @@
+/*
+  © 2024 CVS Health and/or one of its affiliates. All rights reserved.
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+*/
+
+/*
+  index
+  Compares scores in a summary report.
+*/
+
+// ########## IMPORTS
+
+// Module to access files.
+const fs = require('fs/promises');
+const {getBarCell, getNowDate, getNowDateSlash} = require('../../util');
+
+// CONSTANTS
+
+// Newlines with indentations.
+const innestJoiner = '\n          ';
+
+// ########## FUNCTIONS
+
+// Returns the maximum score.
+const getMaxScore = summaryReport => summaryReport.summaries.reduce(
+  (max, result) => Math.max(max, result.score), 0
+);
+// Converts summary report data to a table body.
+const getTableBody = async summaryReport => {
+  const maxScore = getMaxScore(summaryReport);
+  const rows = summaryReport.summaries
+  .sort((a, b) => a.score - b.score)
+  .map(result => {
+    const {id, score, targetWhat, url} = result;
+    const pageCell = `<th scope="row"><a href="${url}">${targetWhat}</a></th>`;
+    const scoreDestination = process.env.DIGEST_URL.replace('__id__', id);
+    const numCell = `<td class="num"><a href="${scoreDestination}">${score}</a></td>`;
+    // Make the bar width proportional.
+    const barCell = getBarCell(score, maxScore, 25, false);
+    const row = `<tr>${pageCell}${numCell}${barCell}</tr>`;
+    return row;
+  });
+  return rows.join(innestJoiner);
+};
+// Populates a query for a comparative table.
+const populateQuery = exports.populateQuery = async (id, what, summaryReport, query) => {
+  query.id = id;
+  query.what = what;
+  query.pageCount = summaryReport.summaries.length;
+  query.tableBody = await getTableBody(summaryReport);
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
+};
+// Returns a comparison.
+exports.comparer = async (id, what, summaryReport) => {
+  // Create a query to replace placeholders.
+  const query = {};
+  populateQuery(id, what, summaryReport, 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 comparison.
+  return template;
+};

package/procs/track/ttp40/index.js

@@ -53,12 +53,10 @@ const populateQuery = async (id, what, summaryReport, query) => {
   // JSON of summary report.
   const {summaries} = summaryReport;
   query.summaryReportJSON = JSON.stringify(summaryReport);
-  // Legend.
-
   // Get an array of target descriptions and assign to each an ID.
   const rows = [];
   const targets = Array
-  .from(new Set(summaries.map(result => result.target.what)))
+  .from(new Set(summaries.map(result => result.targetWhat)))
   .sort()
   .map((targetWhat, index) => [alphaNumOf(index), targetWhat]);
   const targetIDs = {};

package/procs/track/ttp43/index.html

@@ -0,0 +1,116 @@
+<!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 web pages">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility tracking report</title>
+    <link rel="icon" href="favicon.ico">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility tracking report</h1>
+      </header>
+      <h2>Introduction</h2>
+      <p>This is tracking report <code>__id__</code>, for __what__.</p>
+      <p>It tracks accessibility scores over time. A perfect score is 0. The tracking was performed by Testilo procedure <code>__tp__</code>.</p>
+      <p>The results are presented first as a graph, and then as a table.</p>
+      <h2>Results as a graph</h2>
+      <h3>Legend</h3>
+      <ul id="legendItems">
+        __legendItems__
+      </ul>
+      <h3>Line graph</h3>
+      <figure id="graph">
+        <figcaption>Accessibility scores</figcaption>
+      </figure>
+      <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
+      <script src="https://cdn.jsdelivr.net/npm/@observablehq/plot@0.6"></script>
+      <script type="module" defer>
+        const summaryReportJSON = '__summaryReportJSON__';
+        const summaryReport = JSON.parse(summaryReportJSON);
+        const graphData = [];
+        const targetIDs = {};
+        Array.from(document.getElementById('legendItems').children).forEach(li => {
+          const targetData = li.textContent.split(': ');
+          targetIDs[targetData[1]] = targetData[0];
+        });
+        summaryReport.summaries.forEach(result => {
+          const {what} = result.sources.target;
+          graphData.push({
+            targetID: targetIDs[what],
+            targetWhat: what,
+            time: new Date(`20${result.endTime}Z`),
+            score: result.score
+          });
+        });
+        const svg = Plot.plot({
+          style: 'overflow: visible;',
+          height: 600,
+          y: {grid: true},
+          marks: [
+            Plot.ruleY([0]),
+            Plot.lineY(graphData, {
+              x: 'time',
+              y: 'score',
+              stroke: 'targetID'
+            }),
+            Plot.dot(graphData, {
+              x: 'time',
+              y: 'score',
+              z: 'targetID',
+              r: 9
+            }),
+            Plot.text(graphData, {
+              x: 'time',
+              y: 'score',
+              z: 'targetID',
+              text: 'targetID',
+              textAnchor: 'middle'
+            }),
+            Plot.text(graphData, Plot.selectFirst({
+              x: 'time',
+              y: 'score',
+              z: 'targetID',
+              text: 'targetWhat',
+              textAnchor: 'start',
+              dx: 15
+            })),
+            Plot.text(graphData, Plot.selectLast({
+              x: 'time',
+              y: 'score',
+              z: 'targetID',
+              text: 'targetWhat',
+              textAnchor: 'start',
+              dx: 15
+            }))
+          ]
+        });
+        document.getElementById('graph').insertAdjacentElement('beforeend', svg);
+      </script>
+      <h2>Results as a table</h2>
+      <table class="allBorder secondCellRight">
+        <caption>Accessibility scores</caption>
+        <thead>
+          <tr>
+            <th>Date and time</th>
+            <th>Score</th>
+            <th>Target</th>
+          </tr>
+        </thead>
+        <tbody>
+          __scoreRows__
+        </tbody>
+      </table>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/track/ttp43/index.js

@@ -0,0 +1,100 @@
+/*
+  © 2024 CVS Health and/or one of its affiliates. All rights reserved.
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+*/
+
+// index: tracker for tracking procedure ttp43.
+
+// IMPORTS
+
+// Module to keep secrets.
+require('dotenv').config();
+// Module to process files.
+const fs = require('fs/promises');
+// Utility module.
+const {alphaNumOf, getNowDate, getNowDateSlash} = require('../../util');
+
+// CONSTANTS
+
+// Tracker ID.
+const trackerID = 'ttp43';
+// Newline with indentations.
+const innerJoiner = '\n          ';
+// Digest URL.
+const digestURL = process.env.DIGEST_URL;
+
+// FUNCTIONS
+
+// Adds parameters to a query for a tracking report.
+const populateQuery = async (id, what, summaryReport, query) => {
+  // General parameters.
+  query.id = id;
+  query.what = what;
+  query.tp = trackerID;
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
+  // JSON of summary report.
+  const {summaries} = summaryReport;
+  query.summaryReportJSON = JSON.stringify(summaryReport);
+  // Get an array of target descriptions and assign to each an ID.
+  const rows = [];
+  const targets = Array
+  .from(new Set(summaries.map(result => result.targetWhat)))
+  .sort()
+  .map((targetWhat, index) => [alphaNumOf(index), targetWhat]);
+  const targetIDs = {};
+  targets.forEach(target => {
+    targetIDs[target[1]] = target[0];
+  });
+  // Add legend items to the query.
+  const legendItems = targets.map(target => `<li>${target[0]}: ${target[1]}</li>`);
+  query.legendItems = legendItems.join('\n        ');
+  // For each result:
+  summaries.forEach(result => {
+    const {endTime, id, score, targetWhat, url} = result;
+    // Create a date-time cell.
+    const timeCell = `<td>${endTime}</td>`;
+    // Create a score cell.
+    const digestLinkDestination = digestURL.replace('__id__', id);
+    const scoreCell = `<td><a href=${digestLinkDestination}>${score}</a></td>`;
+    // Create a target cell.
+    const targetLink = `<a href="${url}">${targetWhat}</a>`;
+    const targetCell = `<td>${targetIDs[targetWhat]}: ${targetLink}</td>`;
+    const row = `<tr>${[timeCell, scoreCell, targetCell].join('')}</tr>`;
+    // Add the row to the array of rows.
+    rows.push(row);
+  });
+  // Add the rows to the query.
+  query.scoreRows = rows.join(innerJoiner);
+};
+// Returns a tracking report.
+exports.tracker = async (id, what, summaryReport) => {
+  // Create a query to replace placeholders.
+  const query = {};
+  await populateQuery(id, what, summaryReport, 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 tracking report.
+  return template;
+};

package/summarize.js

@@ -34,9 +34,12 @@ require('dotenv').config();
 
 // Returns a report summary.
 exports.summarize = report => {
-  const {id, jobData, score, sources} = report;
+  const {id, jobData, score, sources, target} = report;
+  const foundTarget = target || sources.target;
   const summary = {
     id: id || null,
+    url: foundTarget && (foundTarget.url || foundTarget.which) || null,
+    targetWhat: foundTarget.what || null,
     endTime: jobData && jobData.endTime || null,
     sources: sources || null,
     score: score && score.summary && score.summary.total || null