testilo 26.0.0 → 28.0.0

package/README.md

@@ -768,7 +768,43 @@ node call summarize divisions 2411
 
 When a user invokes `summarize` in this example, the `call` module:
 - gets all the reports in the `scored` subdirectory of the `REPORTDIR` directory, or (if the third argument is present) all those whose file names begin with `2411`.
-- writes the summary as a JSON file named `divisions.json` to the `summarized` subdirectory of the `REPORTDIR` directory.
+- writes the summary, with `divisions` as its description, in JSON format to the `summarized` subdirectory of the `REPORTDIR` directory.
+
+### Track
+
+The `track` module of Testilo selects, organizes, and presents data from summaries to show changes over time in total scores. The module produces a web page, showing changes in a table and (in the future) also in a line graph.
+
+#### Invocation
+
+##### By a module
+
+A module can invoke `track()` in this way:
+
+```javaScript
+const {track} = require('testilo/track');
+const trackerDir = `${process.env.FUNCTIONDIR}/track/ttp99a`;
+const {tracker} = require(`${trackerDir}/index`);
+const summary = …;
+const [reportID, trackReport] = track(tracker, summary);
+```
+
+The `track()` function returns an ID and an HTML tracking report that shows data for all of the results in the summary. The invoking module can further dispose of the report as needed.
+
+##### By a user
+
+A user can invoke `track()` in this way:
+
+```javaScript
+node call track ttp99a 241016T2045-Uf-0 4 'ABC Foundation'
+```
+
+When a user invokes `track()` in this example, the `call` module:
+- gets the summary from the `241016T2045-Uf-0.json` file in the `summarized` subdirectory of the `REPORTDIR` directory.
+- selects the summarized data for all audits with the `order` value of `'4'` and the `target.what` value of `'ABC Foundation'`. If the third or fourth argument to `call()` is `null` (or omitted), then `call()` does not select audits by `order` or by `target.what`, respectively.
+- uses tracker `ttp99a` to create a tracking report.
+- writes the tracking report to the `tracking` subdirectory of the `REPORTDIR` directory.
+
+The tracking reports created by `track()` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/tracking/style.css` file in Testilo is an appropriate stylesheet to be copied into the directory where tracking reports are written.
 
 ## Origin
 

package/call.js

@@ -36,6 +36,8 @@ const {difgest} = require('./difgest');
 const {compare} = require('./compare');
 // Function to summarize reports.
 const {summarize} = require('./summarize');
+// Function to track audits.
+const {track} = require('./track');
 
 // ########## CONSTANTS
 
@@ -153,8 +155,7 @@ const callDigest = async (digesterID, selector = '') => {
   // If any exist:
   if (reports.length) {
     // Get the digester.
-    const digesterDir = `${functionDir}/digest/${digesterID}`;
-    const {digester} = require(`${digesterDir}/index`);
+    const {digester} = require(`${functionDir}/digest/${digesterID}/index`);
     // Digest the reports.
     const digestedReports = await digest(digester, reports);
     const digestedReportDir = `${reportDir}/digested`;
@@ -172,7 +173,7 @@ const callDigest = async (digesterID, selector = '') => {
     console.log('ERROR: No scored reports to be digested');
   }
 };
-// Fulfills a digesting request.
+// Fulfills a difgesting request.
 const callDifgest = async (difgesterID, reportAID, reportBID) => {
   // Get the scored reports to be difgested.
   const reportAArray = await getReports('scored', reportAID);
@@ -240,7 +241,7 @@ const callCredit = async (tallyID, selector = '') => {
     console.log('ERROR: No scored reports to be tallied');
   }
 };
-// Fulfills a summarize request.
+// Fulfills a summarization request.
 const callSummarize = async (what, selector = '') => {
   // Get the scored reports to be summarized.
   const reports = await getReports('scored', selector);
@@ -255,7 +256,7 @@ const callSummarize = async (what, selector = '') => {
     // Save the summary.
     const summaryDir = `${reportDir}/summarized`;
     await fs.mkdir(summaryDir, {recursive: true}); 
-    const filePath = `${summaryDir}/${summary.timeStamp}-${getRandomString(2)}-0.json`;
+    const filePath = `${summaryDir}/${summary.id}.json`;
     await fs.writeFile(filePath, `${JSON.stringify(summary, null, 2)}\n`);
     console.log(`Reports summarized and summary saved as ${filePath}`);
   }
@@ -265,6 +266,43 @@ const callSummarize = async (what, selector = '') => {
     console.log('ERROR: No scored reports to be summarized');
   }
 };
+// Fulfills a tracking request.
+const callTrack = async (trackerID, summaryID, orderID, targetWhat) => {
+  // Get the summary.
+  try {
+    const summaryJSON = await fs.readFile(`${reportDir}/summarized/${summaryID}.json`, 'utf8');
+    const summary = JSON.parse(summaryJSON);
+    // Remove unwanted audits from it.
+    summary.data = summary.data.filter(audit => {
+      if (orderID && audit.order !== orderID) {
+        return false;
+      }
+      if (targetWhat && audit.target && audit.target.what !== targetWhat) {
+        return false;
+      }
+      return true;
+    });
+    // If any audits remain:
+    if (summary.data.length) {
+      // Get the tracker.
+      const {tracker} = require(`${functionDir}/track/${trackerID}/index`);
+      // Track the audits.
+      const [reportID, trackingReport] = await track(tracker, summary);
+      // Save the tracking report.
+      await fs.mkdir(`${reportDir}/tracking`, {recursive: true});
+      const reportPath = `${reportDir}/tracking/${reportID}.html`;
+      await fs.writeFile(reportPath, trackingReport);
+      console.log(`Tracking report saved in ${reportPath}`);
+    }
+    // Otherwise, i.e. if no audits remain:
+    else {
+      console.log('ERROR: No audits match the request');
+    }
+  }
+  catch(error) {
+    console.log(`ERROR: Tracking request invalid (${error.message})`);
+  }
+};
 
 // ########## OPERATION
 
@@ -329,6 +367,12 @@ else if (fn === 'summarize' && fnArgs.length > 0 && fnArgs.length < 3) {
     console.log('Execution completed');
   });
 }
+else if (fn === 'track' && fnArgs.length > 1 && fnArgs.length < 5) {
+  callTrack(... fnArgs)
+  .then(() => {
+    console.log('Execution completed');
+  });
+}
 else {
   console.log('ERROR: Invalid statement');
 }

package/package.json

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

package/procs/compare/tcp40/index.js

@@ -7,7 +7,7 @@
 
 // Module to access files.
 const fs = require('fs/promises');
-const {getBarCell} = require('../../util');
+const {getBarCell, getNowDate, getNowDateSlash} = require('../../util');
 
 // CONSTANTS
 
@@ -63,9 +63,8 @@ const populateQuery = async (scoredReports, query) => {
   const data = await getData(scoredReports);
   query.pageCount = data.pageCount;
   query.tableBody = await getTableBody(data.bodyData);
-  const date = new Date();
-  query.dateISO = date.toISOString().slice(0, 10);
-  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
 };
 // Returns a comparative report.
 exports.comparer = async scoredReports => {

package/procs/difgest/tfp40/index.js

@@ -9,7 +9,7 @@ const {issues} = require('../../score/tic40');
 // Module to process files.
 const fs = require('fs/promises');
 // Utility module.
-const {getBarCell} = require('../../util');
+const {getBarCell, getNowDate, getNowDateSlash} = require('../../util');
 
 // CONSTANTS
 
@@ -46,8 +46,8 @@ const getIssueScoreRow = (summary, wcag, scoreA, scoreB, aSuperiorityMax, bSuper
 const populateQuery = (reportA, reportB, query) => {
   // General parameters.
   query.fp = id;
-  query.dateISO = new Date().toISOString().slice(0, 10);
-  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
   // For each report:
   const issueIDs = new Set();
   [reportA, reportB].forEach((report, index) => {

package/procs/digest/tdp40/index.js

@@ -8,6 +8,8 @@ require('dotenv').config();
 const {issues} = require('../../score/tic40');
 // Module to process files.
 const fs = require('fs/promises');
+// Utility module.
+const {getNowDate, getNowDateSlash} = require('../../util');
 
 // CONSTANTS
 
@@ -34,8 +36,8 @@ const populateQuery = (report, query) => {
   query.sp = scoreProcID;
   query.dp = digesterID;
   // Add the job data to the query.
-  query.dateISO = jobData.endTime.slice(0, 8);
-  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
   query.org = target.what;
   query.url = target.which;
   query.requester = requester;

package/procs/track/ttp40/index.html

@@ -0,0 +1,83 @@
+<!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>.</p>
+      <p>It tracks accessibility scores over time. A perfect score is 0. The tracking was performed by Testilo procedure __tp__.</p>
+      <p>The results are presented first as a graph, and then as a table.</p>
+      <h2>Results as a graph</h2>
+      <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">
+        const summaryJSON = '__summaryJSON__';
+        const summary = JSON.parse(summaryJSON);
+        const graphData = [];
+        summary.data.forEach(result => {
+          graphData.push({
+            target: result.target.what,
+            time: new Date(`20${result.endTime}Z`),
+            score: result.score
+          });
+        });
+        const svg = Plot.plot({
+          style: 'overflow: visible;',
+          y: {grid: true},
+          marks: [
+            Plot.ruleY([0]),
+            Plot.lineY(graphData, {
+              x: 'time',
+              y: 'score',
+              stroke: 'target'
+            }),
+            Plot.text(graphData, Plot.selectLast({
+              x: 'time',
+              y: 'score',
+              z: 'target',
+              text: 'target',
+              textAnchor: 'start',
+              dx: 3
+            }))
+          ]
+        });
+        document.getElementById('graph').insertAdjacentElement('beforeend', svg);
+      </script>
+      <h2>Results as a table</h2>
+      <table class="allBorder secondCellRight thirdCellRight">
+        <caption>Accessibility scores</caption>
+        <thead>
+          <tr>
+            <th>Date and time</th>
+            <th>Score</th>
+            <th>Order</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/ttp40/index.js

@@ -0,0 +1,70 @@
+// index: tracker for tracking procedure ttp40.
+
+// 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 = 'ttp40';
+// 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, summary, query) => {
+  // General parameters.
+  query.id = id;
+  query.tp = trackerID;
+  query.dateISO = getNowDate();
+  query.dateSlash = getNowDateSlash();
+  // JSON of pruned summary.
+  summary.data.forEach(result => {
+    delete result.id;
+    delete result.target.id;
+    delete result.target.which;
+  });
+  query.summaryJSON = JSON.stringify(summary);
+  // For each score:
+  const rows = [];
+  const results = summary.data;
+  const targetWhats = Array.from(new Set(results.map(result => result.target.what))).sort();
+  summary.data.forEach(result => {
+    // Create an HTML table row for it.
+    const timeCell = `<td>${result.endTime}</td>`;
+    const digestLinkDestination = digestURL.replace('__id__', result.id);
+    const scoreCell = `<td><a href=${digestLinkDestination}>${result.score}</a></td>`;
+    const orderCell = `<td class="center">${result.order}</td>`;
+    const targetID = alphaNumOf(targetWhats.indexOf(result.target.what));
+    const targetLink = `<a href="${result.target.which}">${result.target.what}</a>`;
+    const targetCell = `<td>${targetID}: ${targetLink}</td>`;
+    const row = `<tr>${[timeCell, scoreCell, orderCell, 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, summary) => {
+  // Create a query to replace placeholders.
+  const query = {};
+  await populateQuery(id, summary, 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/procs/util.js

@@ -18,7 +18,11 @@ const alphaNumChars = (() => {
 // Returns a string representing a date and time.
 const getTimeString = date => date.toISOString().slice(0, 19);
 // Returns a string representing the date and time.
-exports.getNowString = () => getTimeString(new Date());
+const getNowString = exports.getNowString = () => getTimeString(new Date());
+// Returns a string representing an ISO date.
+const getNowDate = exports.getNowDate = () => getNowString().slice(0, 10);
+// Returns a string representing a date with slashes.
+exports.getNowDateSlash = () => getNowDate().replace(/-/g, '/');
 // Returns a time stamp representing a date and time.
 const getTimeStamp
 = exports.getTimeStamp

package/reports/tracking/style.css

@@ -0,0 +1,115 @@
+*:focus {
+  outline: solid 0.2rem #00f;
+  outline-offset: 0.2rem;
+}
+body {
+  margin: 2rem;
+  font-size: large;
+}
+.bold, .componentID {
+  font-weight: 700;
+}
+button {
+  min-height: 44px;
+  min-width: 44px;
+  padding: 0.5rem;
+  border: solid 0.2rem #03a;
+  border-radius: 1rem;
+  font-size: inherit;
+  font-weight: 700;
+  color: #fff;
+  background-color: #03a;
+}
+button:hover {
+  color: #000;
+  background-color: #9df;
+}
+caption {
+  margin: 1rem 0;
+  font-weight: 700;
+  font-style: italic;
+}
+code {
+  font-family: sans-serif;
+  color: #832703;
+}
+.error {
+  font-weight: 700;
+  color: #c00;
+}
+fieldset {
+  width: max-content;
+  margin-top: 1rem;
+}
+.firstCellRight td:nth-child(1) {
+  text-align: right;
+}
+form {
+  margin-top: 1rem;
+}
+h1, h2, h3, h4, h5, h6 {
+  margin-bottom: 0;
+}
+h2 {
+  font-size: 1.8rem;
+  margin: 1rem auto 0.5rem auto;
+  color: #006666;
+}
+h3 {
+  font-size: 1.6rem;
+}
+h3.bars {
+  border-top: solid black 0.1rem;
+  padding-top: 0.3rem;
+}
+h4 {
+  font-size: 1.4rem;
+}
+h5 {
+  font-size: 1.2rem;
+}
+h6 {
+  font-size: 1rem;
+}
+input {
+  margin: 0.5rem 0;
+  font-size: inherit;
+}
+legend {
+  font-weight: 700;
+}
+pre {
+  white-space: break-spaces;
+}
+.secondCellRight td:nth-child(2) {
+  text-align: right;
+}
+section:not(.wide) {
+  max-width: 36rem;
+}
+#synopsis > p {
+  margin: 0;
+  padding: 0;
+}
+table {
+  border-collapse: collapse;
+}
+table.allBorder th {
+  padding-bottom: 0;
+}
+table.allBorder th, table.allBorder td, tbody td {
+  border: 1px gray solid;
+}
+tbody th {
+  padding-right: 1rem;
+  text-align: right;
+}
+td, th {
+  padding: 0 0.5rem;
+}
+thead th {
+  padding-bottom: 1rem;
+}
+.thirdCellRight td:nth-child(3) {
+  text-align: right;
+}

package/summarize.js

@@ -8,7 +8,7 @@
 // Module to keep secrets.
 require('dotenv').config();
 // Module to perform common operations.
-const {getNowStamp} = require('./procs/util');
+const {getFileID} = require('./procs/util');
 
 // ########## FUNCTIONS
 
@@ -27,8 +27,8 @@ exports.summarize = (what, reports) => {
     };
   });
   const summary = {
+    id: getFileID(2),
     what,
-    timeStamp: getNowStamp(),
     data
   };
   return summary;

package/track.js

@@ -0,0 +1,23 @@
+/*
+  track.js
+  Creates tracking reports from report summaries.
+  Arguments:
+    0. Tracking function.
+    1. Summary.
+*/
+
+// ########## IMPORTS
+
+// Module to perform common operations.
+const {getFileID} = require('./procs/util');
+
+// ########## FUNCTIONS
+
+// Creates and returns a tracking report from a summary.
+exports.track = async (tracker, summary) => {
+  // Use the tracker to create a tracking report.
+  const id = getFileID(2);
+  const trackingReport = await tracker(id, summary);
+  console.log(`Tracking report ${id} created`);
+  return [id, trackingReport];
+};