testilo 41.0.5 → 41.2.0

package/README.md

@@ -669,10 +669,9 @@ To test the `rescore` module, in the project directory you can execute the state
 
 Reports from Testaro are JavaScript objects. When represented as JSON, they are human-readable, but not human-friendly. They are basically designed for machine tractability. This is equally true for reports that have been scored by Testilo. But Testilo can _digest_ a scored report, converting it to a human-oriented HTML document, or _digest_.
 
-The `digest` module digests a scored report. Its `digest()` function takes three arguments:
+The `digest` module digests a scored report. Its `digest()` function takes two arguments:
 - a digester (a digesting function)
 - a scored report object
-- the URL of a directory containing the scored reports
 
 The digester populates an HTML digest template. A copy of the template, with its placeholders replaced by computed values, becomes the digest. The digester defines the rules for replacing the placeholders with values. The Testilo package contains a `procs/digest` directory, in which there are subdirectories, each containing a template and a module that exports a digester. You can use one of those modules, or you can create your own.
 
@@ -717,9 +716,9 @@ When a user invokes `digest()` in this example, the `call` module:
 - writes the digested reports to the `digested` subdirectory of the `REPORTDIR` directory.
 - includes in each digest a link to the scored report, with the link destination being based on `SCORED_REPORT_URL`.
 
-The included digesters create digests that have links. The server that serves such a digest must also respond correctly when a user activates one of the links. One link is to the scored report. Other links are to collections of standard instances of violations of particular rules from the scored report.
+The included digesters create digests that have links. The server that serves such a digest must also respond correctly when a user activates one of the links. One link is to the scored report. Other links are to World Wide Web Consortium documents on WCAG principles, guidelines, and success criteria.
 
-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 the directory where digested reports are written.
+The digests created by `digest()` are HTML files, and they expect a `style.css` file to exist in their directory. If you use an included digester, the `reports/digested/style.css` file in Testilo is an appropriate stylesheet to be copied into the directory where digested reports are written.
 
 ### Difgesting
 

package/package.json

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

package/procs/digest/{tdp44 → tdp46}/index.html

@@ -11,6 +11,43 @@
     <title>Accessibility digest</title>
     <link rel="icon" href="favicon.ico">
     <link rel="stylesheet" href="style.css">
+    <script id="script" type="module">
+      const sortButton = document.getElementById('sortButton');
+      const sortChangeSpan = document.getElementById('sortChange');
+      const sumBody = document.getElementById('sumBody');
+      const rows = Array.from(sumBody.children);
+      const sortRowsBy = basis => {
+        if (basis === 'wcag') {
+          rows.sort((a, b) => {
+            const sorters = [a, b].map(row => {
+              const wcagParts = row.children[1].textContent.split('.');
+              const wcagNums = wcagParts.map(part => Number.parseInt(part, 10));
+              return 100 * (wcagNums[0] || 0) + 20 * (wcagNums[1] || 0) + (wcagNums[2] || 0);
+            });
+            return sorters[0] - sorters[1];
+          });
+        }
+        else if (basis === 'score') {
+          rows.sort((a, b) => {
+            const sorters = [a, b].map(row => Number.parseInt(row.children[2].textContent));
+            return sorters[1] - sorters[0];
+          });
+        }
+        sumBody.textContent = '';
+        rows.forEach(row => {
+          sumBody.appendChild(row);
+        });
+      };
+      sortButton.addEventListener('click', event => {
+        // Add the new sorting basis to the page.
+        sortChangeSpan.textContent = sortChangeSpan.textContent === 'score to WCAG'
+        ? 'WCAG to score'
+        : 'score to WCAG';
+        const newBasis = sortChangeSpan.textContent === 'score to WCAG' ? 'score' : 'wcag';
+        // Re-sort the table.
+        sortRowsBy(newBasis);
+      });
+    </script>
   </head>
   <body>
     <main>
@@ -53,14 +90,23 @@
       <p>This digest can help answer that question. Ten different tools (Alfa, ASLint, Axe, Editoria11y, Equal Access, HTML CodeSniffer, Nu Html Checker, QualWeb, Testaro, and WAVE) tested the page to check its compliance with their accessibility rules. In all, the tools define about 990 rules, which are classified here into about 310 accessibility issues.</p>
       <p>The results were interpreted to yield a score, with 0 being ideal. The score for this page was __total__, the sum of __issueCount__ for the count of issues, __issue__ for specific issues, __solo__ for unclassified rule violations, __tool__ for tool-by-tool ratings, __element__ for the count of violating elements, __prevention__ for the page preventing tools from running, __log__ for browser warnings, and __latency__ for delayed page responses.</p>
       <h2 id="summary">Issue summary</h2>
-      <p>This table shows the numbers of rule violations (<q>instances</q>) reported by one or more tools, classified by issue. When an instance count is 0, that means the tool has a rule belonging to the issue but reported no violations of that rule.</p>
-      <p>Tools do not always agree on instance counts. Disagreements may be due to non-equivalent rules or invalid tests. You can inspect the <a href="__reportURL__">full report</a> to diagnose differences.</p>
+      <h3>Details about this summary</h3>
+      <ul>
+        <li>This table shows the numbers of rule violations (<q>instances</q>) reported by one or more tools, classified by issue.</li>
+        <li>Tools often disagree on instance counts, because of non-equivalent rules or invalid tests. You can inspect the <a href="__reportURL__">full report</a> to diagnose differences.</li>
+        <li>The <q>WCAG</q> value is the principle, guideline, or success criterion of the <a href="https://www.w3.org/TR/WCAG22/">Web Content Accessibility Guidelines</a> most relevant to the issue.</li>
+        <li>The <q>Score</q> value is the contribution of the issue to the page score.</li>
+        <li>An instance count of 0 means the tool has a rule belonging to the issue but reported no violations of that rule, although at least one tool reported at least one violation.</li>
+        <li>You can sort this table by WCAG or score.</li>
+      </ul>
+      <h3>The summary</h3>
+      <p><button id="sortButton" type="button">Change sorting from <span id="sortChange">score to WCAG</span></button></p>
       <table class="allBorder thirdCellRight">
         <caption>How many violations each tool reported, by issue</caption>
         <thead>
           <tr><th>Issue</th><th>WCAG</th><th>Score</th><th>Instance counts</th></tr>
         </thead>
-        <tbody class="headersLeft">
+        <tbody id="sumBody" class="headersLeft">
           __issueRows__
         </tbody>
       </table>

package/procs/digest/{tdp43e → tdp46}/index.js

@@ -36,27 +36,75 @@ const {getNowDate, getNowDateSlash} = require('../../util');
 // CONSTANTS
 
 // Digester ID.
-const digesterID = 'tdp43e';
+const digesterID = 'tdp45';
 // Newline with indentations.
 const innerJoiner = '\n        ';
 const outerJoiner = '\n      ';
+// Directory of WCAG links.
+const wcagPhrases = {};
 
 // FUNCTIONS
 
 // Gets a row of the score-summary table.
 const getScoreRow = (componentName, score) => `<tr><th>${componentName}</th><td>${score}</td></tr>`;
+// Gets a WCAG link or, if not obtainable, a numeric identifier.
+const getWCAGTerm = wcag => {
+  const wcagPhrase = wcagPhrases[wcag];
+  const wcagTerm = wcagPhrase
+  ? `<a href="https://www.w3.org/WAI/WCAG22/Understanding/${wcagPhrase}.html">${wcag}</a>`
+  : wcag;
+  return wcagTerm;
+};
 // Gets a row of the issue-score-summary table.
 const getIssueScoreRow = (issueConstants, issueDetails) => {
   const {summary, wcag} = issueConstants;
+  const wcagTerm = getWCAGTerm(wcag);
   const {instanceCounts, score} = issueDetails;
   const toolList = Object
   .keys(instanceCounts)
   .map(tool => `<code>${tool}</code>:${instanceCounts[tool]}`)
   .join(', ');
-  return `<tr><th>${summary}</th><td class="center">${wcag}<td class="right num">${score}</td><td>${toolList}</td></tr>`;
+  return `<tr><th>${summary}</th><td class="center">${wcagTerm}<td class="right num">${score}</td><td>${toolList}</td></tr>`;
+};
+// Populates the directory of WCAG understanding verbal IDs.
+const getWCAGPhrases = async () => {
+  // Get the copy of file https://raw.githubusercontent.com/w3c/wcag/main/guidelines/wcag.json.
+  const wcagJSON = await fs.readFile(`${__dirname}/../../../wcag.json`, 'utf8');
+  const wcag = JSON.parse(wcagJSON);
+  const {principles} = wcag;
+  // For each principle in it:
+  principles.forEach(principle => {
+    // If it is usable:
+    if (principle.num && principle.id && principle.id.startsWith('WCAG2:')) {
+      // Add it to the directory.
+      wcagPhrases[principle.num] = principle.id.slice(6);
+      const {guidelines} = principle;
+      // For each guideline in the principle:
+      guidelines.forEach(guideline => {
+        // If it is usable:
+        if (guideline.num && guideline.id && guideline.id.startsWith('WCAG2:')) {
+          // Add it to the directory.
+          wcagPhrases[guideline.num] = guideline.id.slice(6);
+          const {successcriteria} = guideline;
+          // For each success criterion in the guideline:
+          successcriteria.forEach(successCriterion => {
+            // If it is usable:
+            if (
+              successCriterion.num
+              && successCriterion.id
+              && successCriterion.id.startsWith('WCAG2:')
+            ) {
+              // Add it to the directory.
+              wcagPhrases[successCriterion.num] = successCriterion.id.slice(6);
+            }
+          });
+        }
+      });
+    }
+  });
 };
 // Adds parameters to a query for a digest.
-const populateQuery = (report, query) => {
+const populateQuery = async (report, query) => {
   const {
     browserID, device, id, isolate, lowMotion, score, sources, standard, strict, target
   } = report;
@@ -80,6 +128,8 @@ const populateQuery = (report, query) => {
   query.browser = browserID;
   query.agent = agent ? ` on agent ${agent}` : '';
   query.reportURL = process.env.SCORED_REPORT_URL.replace('__id__', id);
+  // Populate the WCAG phrase directory.
+  await getWCAGPhrases();
   // Add values for the score-summary table to the query.
   const rows = {
     summaryRows: [],
@@ -112,7 +162,9 @@ const populateQuery = (report, query) => {
     const issueSummary = issues[issueID].summary;
     issueDetailRows.push(`<h3 class="bars">Issue: ${issueSummary}</h3>`);
     issueDetailRows.push(`<p>Impact: ${issues[issueID].why || 'N/A'}</p>`);
-    issueDetailRows.push(`<p>WCAG: ${issues[issueID].wcag || 'N/A'}</p>`);
+    const wcag = issues[issueID].wcag;
+    const wcagTerm = wcag ? getWCAGTerm(wcag) : 'N/A';
+    issueDetailRows.push(`<p>WCAG: ${wcagTerm}</p>`);
     const issueData = details.issue[issueID];
     issueDetailRows.push(`<p>Score: ${issueData.score}</p>`);
     issueDetailRows.push('<h4>Elements</h4>');
@@ -176,7 +228,7 @@ const populateQuery = (report, query) => {
 exports.digester = async report => {
   // Create a query to replace placeholders.
   const query = {};
-  populateQuery(report, query);
+  await populateQuery(report, query);
   // Get the template.
   let template = await fs.readFile(`${__dirname}/index.html`, 'utf8');
   // Replace its placeholders.

package/procs/digest/{tdp43e → tdp47}/index.html

@@ -11,11 +11,55 @@
     <title>Accessibility digest</title>
     <link rel="icon" href="favicon.ico">
     <link rel="stylesheet" href="style.css">
+    <script id="script" type="module">
+      const sortButton = document.getElementById('sortButton');
+      const sortChangeSpan = document.getElementById('sortChange');
+      const sumBody = document.getElementById('sumBody');
+      const rows = Array.from(sumBody.children);
+      const sortRowsBy = basis => {
+        if (basis === 'wcag') {
+          rows.sort((a, b) => {
+            const sorters = [a, b].map(row => {
+              const wcagParts = row.children[1].textContent.split('.');
+              const wcagNums = wcagParts.map(part => Number.parseInt(part, 10));
+              return 100 * (wcagNums[0] || 0) + 20 * (wcagNums[1] || 0) + (wcagNums[2] || 0);
+            });
+            return sorters[0] - sorters[1];
+          });
+        }
+        else if (basis === 'score') {
+          rows.sort((a, b) => {
+            const sorters = [a, b].map(row => Number.parseInt(row.children[2].textContent));
+            return sorters[1] - sorters[0];
+          });
+        }
+        sumBody.textContent = '';
+        rows.forEach(row => {
+          sumBody.appendChild(row);
+        });
+      };
+      sortButton.addEventListener('click', event => {
+        // Add the new sorting basis to the page.
+        sortChangeSpan.textContent = sortChangeSpan.textContent === 'score to WCAG'
+        ? 'WCAG to score'
+        : 'score to WCAG';
+        const newBasis = sortChangeSpan.textContent === 'score to WCAG' ? 'score' : 'wcag';
+        // Re-sort the table.
+        sortRowsBy(newBasis);
+      });
+    </script>
   </head>
   <body>
     <main>
       <header>
         <h1>Accessibility digest</h1>
+        <h2>Contents</h2>
+        <ul>
+          <li><a href="#intro">Introduction</a></li>
+          <li><a href="#summary">Issue summary</a></li>
+          <li><a href="#itemization">Itemized issues</a></li>
+          <li><a href="#elements">Elements with issues</a></li>
+        </ul>
         <table class="allBorder">
           <caption>Synopsis</caption>
           <tr><th>Page</th><td>__org__</td></tr>
@@ -41,28 +85,37 @@
           </tr>
         </table>
       </header>
-      <h2>Introduction</h2>
+      <h2 id="intro">Introduction</h2>
       <p>How <a href="https://www.w3.org/WAI/">accessible</a> is the __org__ web page at <a href="__url__"><code>__url__</code></a>?</p>
       <p>This digest can help answer that question. Ten different tools (Alfa, ASLint, Axe, Editoria11y, Equal Access, HTML CodeSniffer, Nu Html Checker, QualWeb, Testaro, and WAVE) tested the page to check its compliance with their accessibility rules. In all, the tools define about 990 rules, which are classified here into about 310 accessibility issues.</p>
       <p>The results were interpreted to yield a score, with 0 being ideal. The score for this page was __total__, the sum of __issueCount__ for the count of issues, __issue__ for specific issues, __solo__ for unclassified rule violations, __tool__ for tool-by-tool ratings, __element__ for the count of violating elements, __prevention__ for the page preventing tools from running, __log__ for browser warnings, and __latency__ for delayed page responses.</p>
-      <h2>Issue summary</h2>
-      <p>This table shows the issues discovered by one or more tools. When an instance count is 0, that means the tool has a test for the issue but the page passed that test.</p>
-      <p>Why do instance counts differ among tools? Possibly because the tests are not really equivalent, or a test is unreliable. You can inspect the <a href="__reportURL__">full report</a> to diagnose differences.</p>
+      <h2 id="summary">Issue summary</h2>
+      <h3>Details about this summary</h3>
+      <ul>
+        <li>This table shows the numbers of rule violations (<q>instances</q>) reported by one or more tools, classified by issue.</li>
+        <li>Tools often disagree on instance counts, because of non-equivalent rules or invalid tests. You can inspect the <a href="__reportURL__">full report</a> to diagnose differences.</li>
+        <li>The <q>WCAG</q> value is the principle, guideline, or success criterion of the <a href="https://www.w3.org/TR/WCAG22/">Web Content Accessibility Guidelines</a> most relevant to the issue.</li>
+        <li>The <q>Score</q> value is the contribution of the issue to the page score.</li>
+        <li>An instance count of 0 means the tool has a rule belonging to the issue but reported no violations of that rule, although at least one tool reported at least one violation.</li>
+        <li>You can sort this table by WCAG or score.</li>
+      </ul>
+      <h3>The summary</h3>
+      <p><button id="sortButton" type="button">Change sorting from <span id="sortChange">score to WCAG</span></button></p>
       <table class="allBorder thirdCellRight">
-        <caption>Summary of issues</caption>
+        <caption>How many violations each tool reported, by issue</caption>
         <thead>
           <tr><th>Issue</th><th>WCAG</th><th>Score</th><th>Instance counts</th></tr>
         </thead>
-        <tbody class="headersLeft">
+        <tbody id="sumBody" class="headersLeft">
           __issueRows__
         </tbody>
       </table>
-      <h2>Itemized issues</h2>
+      <h2 id="itemization">Itemized issues</h2>
       <p>The reported rule violations are itemized below, issue by issue. Additional details can be inspected in the <a href="__reportURL__">full report</a>.</p>
       __issueDetailRows__
-      <h2>Multi-issue elements</h2>
-      <p>Elements exhibiting more than 1 issue:</p>
-      __multiIssueElementRows__
+      <h2 id="elements">Elements with issues</h2>
+      <p>Elements exhibiting issues:</p>
+      __elementRows__
       <footer>
         <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
       </footer>

package/procs/digest/{tdp44 → tdp47}/index.js

@@ -36,27 +36,75 @@ const {getNowDate, getNowDateSlash} = require('../../util');
 // CONSTANTS
 
 // Digester ID.
-const digesterID = 'tdp44';
+const digesterID = 'tdp45';
 // Newline with indentations.
 const innerJoiner = '\n        ';
 const outerJoiner = '\n      ';
+// Directory of WCAG links.
+const wcagPhrases = {};
 
 // FUNCTIONS
 
 // Gets a row of the score-summary table.
 const getScoreRow = (componentName, score) => `<tr><th>${componentName}</th><td>${score}</td></tr>`;
+// Gets a WCAG link or, if not obtainable, a numeric identifier.
+const getWCAGTerm = wcag => {
+  const wcagPhrase = wcagPhrases[wcag];
+  const wcagTerm = wcagPhrase
+  ? `<a href="https://www.w3.org/WAI/WCAG22/Understanding/${wcagPhrase}.html">${wcag}</a>`
+  : wcag;
+  return wcagTerm;
+};
 // Gets a row of the issue-score-summary table.
 const getIssueScoreRow = (issueConstants, issueDetails) => {
   const {summary, wcag} = issueConstants;
+  const wcagTerm = getWCAGTerm(wcag);
   const {instanceCounts, score} = issueDetails;
   const toolList = Object
   .keys(instanceCounts)
   .map(tool => `<code>${tool}</code>:${instanceCounts[tool]}`)
   .join(', ');
-  return `<tr><th>${summary}</th><td class="center">${wcag}<td class="right num">${score}</td><td>${toolList}</td></tr>`;
+  return `<tr><th>${summary}</th><td class="center">${wcagTerm}<td class="right num">${score}</td><td>${toolList}</td></tr>`;
+};
+// Populates the directory of WCAG understanding verbal IDs.
+const getWCAGPhrases = async () => {
+  // Get the copy of file https://raw.githubusercontent.com/w3c/wcag/main/guidelines/wcag.json.
+  const wcagJSON = await fs.readFile(`${__dirname}/../../../wcag.json`, 'utf8');
+  const wcag = JSON.parse(wcagJSON);
+  const {principles} = wcag;
+  // For each principle in it:
+  principles.forEach(principle => {
+    // If it is usable:
+    if (principle.num && principle.id && principle.id.startsWith('WCAG2:')) {
+      // Add it to the directory.
+      wcagPhrases[principle.num] = principle.id.slice(6);
+      const {guidelines} = principle;
+      // For each guideline in the principle:
+      guidelines.forEach(guideline => {
+        // If it is usable:
+        if (guideline.num && guideline.id && guideline.id.startsWith('WCAG2:')) {
+          // Add it to the directory.
+          wcagPhrases[guideline.num] = guideline.id.slice(6);
+          const {successcriteria} = guideline;
+          // For each success criterion in the guideline:
+          successcriteria.forEach(successCriterion => {
+            // If it is usable:
+            if (
+              successCriterion.num
+              && successCriterion.id
+              && successCriterion.id.startsWith('WCAG2:')
+            ) {
+              // Add it to the directory.
+              wcagPhrases[successCriterion.num] = successCriterion.id.slice(6);
+            }
+          });
+        }
+      });
+    }
+  });
 };
 // Adds parameters to a query for a digest.
-const populateQuery = (report, query) => {
+const populateQuery = async (report, query) => {
   const {
     browserID, device, id, isolate, lowMotion, score, sources, standard, strict, target
   } = report;
@@ -80,6 +128,8 @@ const populateQuery = (report, query) => {
   query.browser = browserID;
   query.agent = agent ? ` on agent ${agent}` : '';
   query.reportURL = process.env.SCORED_REPORT_URL.replace('__id__', id);
+  // Populate the WCAG phrase directory.
+  await getWCAGPhrases();
   // Add values for the score-summary table to the query.
   const rows = {
     summaryRows: [],
@@ -112,7 +162,9 @@ const populateQuery = (report, query) => {
     const issueSummary = issues[issueID].summary;
     issueDetailRows.push(`<h3 class="bars">Issue: ${issueSummary}</h3>`);
     issueDetailRows.push(`<p>Impact: ${issues[issueID].why || 'N/A'}</p>`);
-    issueDetailRows.push(`<p>WCAG: ${issues[issueID].wcag || 'N/A'}</p>`);
+    const wcag = issues[issueID].wcag;
+    const wcagTerm = wcag ? getWCAGTerm(wcag) : 'N/A';
+    issueDetailRows.push(`<p>WCAG: ${wcagTerm}</p>`);
     const issueData = details.issue[issueID];
     issueDetailRows.push(`<p>Score: ${issueData.score}</p>`);
     issueDetailRows.push('<h4>Elements</h4>');
@@ -148,8 +200,8 @@ const populateQuery = (report, query) => {
     });
   });
   query.issueDetailRows = issueDetailRows.join(outerJoiner);
-  // Add paragraphs about the multi-issue elements to the query.
-  const multiIssueElementRows = [];
+  // Add paragraphs about the elements to the query.
+  const elementRows = [];
   const issueElements = {};
   Object.keys(details.element).forEach(issueID => {
     const pathIDs = details.element[issueID];
@@ -161,8 +213,8 @@ const populateQuery = (report, query) => {
   const sortedPathIDs = Object.keys(issueElements).sort();
   sortedPathIDs.forEach(pathID => {
     const elementIssues = issueElements[pathID];
-    if (elementIssues && elementIssues.length > 1) {
-      multiIssueElementRows.push(
+    if (elementIssues) {
+      elementRows.push(
         `<h5>Element <code>${pathID}</code></h5>`,
         '<ul>',
         ... elementIssues.map(issueID => `  <li>${issues[issueID].summary}</li>`).sort(),
@@ -170,13 +222,13 @@ const populateQuery = (report, query) => {
       );
     }
   });
-  query.multiIssueElementRows = multiIssueElementRows.join(outerJoiner);
+  query.elementRows = elementRows.join(outerJoiner);
 };
 // Returns a digested report.
 exports.digester = async report => {
   // Create a query to replace placeholders.
   const query = {};
-  populateQuery(report, query);
+  await populateQuery(report, query);
   // Get the template.
   let template = await fs.readFile(`${__dirname}/index.html`, 'utf8');
   // Replace its placeholders.