testaro 5.9.1 → 5.10.0

package/README.md

@@ -6,7 +6,7 @@ Federated accessibility test automation
 
 Testaro is a collection of collections of web accessibility tests.
 
-The purpose of Testaro is to provide programmatic access to 1228 accessibility tests defined in several test packages and in Testaro itself.
+The purpose of Testaro is to provide programmatic access to 1230 accessibility tests defined in several test packages and in Testaro itself.
 
 ## System requirements
 
@@ -40,8 +40,8 @@ As of this version, the counts of tests in the packages referenced above were:
 - WAVE: 110
 - Nu Html Checker: 147
 - subtotal: 612
-- Testaro tests: 22
-- grand total: 1228
+- Testaro tests: 24
+- grand total: 1230
 
 ## Code organization
 
@@ -234,6 +234,14 @@ This command causes Testaro to alter the `display` and `visibility` style proper
 
 The possible commands of type `test` are enumerated in the `tests` object defined in the `index.js` file.
 
+A test performs operations and reports results. The results may or may not directly indicate that a page passes or fails requirements. Typically, accessibility tests report successes and failures. But a test in Testaro is defined less restrictively, so it can report any results. As one example, the Testaro `elements` test reports facts about certain elements on a page, without asserting that those facts are successes or failures.
+
+The term “test” has two meanings for Testaro:
+- A command is a test (test command) if its `type` property has the value `test`.
+- A package, such as Continuum, performs multiple tests (packaged tests).
+
+Thus, if a command of type `test` runs Continuum, Continuum performs multiple tests and reports their results.
+
 ###### Examples
 
 An example of a **packaged test** is:
@@ -266,7 +274,7 @@ In this case, Testaro runs the `motion` test with the specified parameters.
 
 ###### Tenon
 
-The `tenon` test requires two commands:
+Most packaged tests require only one command, but the `tenon` test requires two commands:
 - A command of type `tenonRequest`.
 - A command of type `test` with `tenon` as the value of `which`.
 
@@ -342,7 +350,7 @@ The changes in `htmlcs/HTMLCS.js` are:
 
 ###### BBC Accessibility Standards Checker
 
-The BBC Accessibility Standards Checker has obsolete dependencies with security vulnerabilities. Therefore, it is not used as a dependency of Testaro. Instead, 6 of its tests are reimplemented, in some case with revisions, as Testaro tests. They are drawn from the 18 automated tests of the Checker. The other 12 tests were found too duplicative of other tests to justify reimplementation.
+The BBC Accessibility Standards Checker has obsolete dependencies with security vulnerabilities. Therefore, it is not used as a dependency of Testaro. Instead, 6 of its tests are reimplemented, in some cases with revisions, as Testaro tests. They are drawn from the 18 automated tests of the Checker. The other 12 tests were found too duplicative of other tests to justify reimplementation.
 
 ##### Branching
 

package/commands.js

@@ -32,7 +32,7 @@ exports.commands = {
       }
     ],
     link: [
-      'Click a link',
+      'Click a link and wait for the page to be idle or loaded',
       {
         which: [true, 'string', 'hasLength', 'substring of link text'],
         index: [false, 'number', '', 'index among matches if not 0'],
@@ -153,7 +153,7 @@ exports.commands = {
     elements: [
       'Perform an elements test',
       {
-        detailLevel: [true, 'number', '', '0 = counts, 1 = selves, 2 = also sibling nodes'],
+        detailLevel: [true, 'number', '', '0 to 3, to specify the level of detail'],
         tagName: [false, 'string', '', 'tag name of elements'],
         onlyVisible: [false, 'boolean', '', 'whether to exclude invisible elements'],
         attribute: [false, 'string', 'hasLength', 'required attribute or attribute=value']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testaro",
-  "version": "5.9.1",
+  "version": "5.10.0",
   "description": "Automation of accessibility testing",
   "main": "index.js",
   "scripts": {

package/run.js

@@ -1097,13 +1097,29 @@ const doActs = async (report, actIndex, page) => {
                       };
                     });
                   });
+                  let loadState = 'idle';
+                  // Wait up to 3 seconds for the resulting page to be idle.
+                  await page.waitForLoadState('networkidle', {timeout: 3000})
+                  // If the wait times out:
+                  .catch(async () => {
+                    loadState = 'loaded';
+                    // Wait up to 2 seconds for the page to be loaded.
+                    await page.waitForLoadState('domcontentloaded', {timeout: 2000})
+                    // If the wait times out:
+                    .catch(() => {
+                      loadState = 'incomplete';
+                      // Proceed but report the timeout.
+                      console.log('ERROR waiting for page to load after link activation');
+                    });
+                  });
                   // If it was clicked:
                   if (actIndex > -2) {
                     // Report the success.
                     act.result = {
                       href: href || 'NONE',
                       target: target || 'NONE',
-                      move: 'clicked'
+                      move: 'clicked',
+                      loadState
                     };
                   }
                 }

package/tests/elements.js

@@ -1,6 +1,11 @@
 /*
   elements
   This test reports data about specified elements.
+  Meanings of detailLevel values:
+    0. Only total element count; no detail.
+    1. Also data on each specified element.
+    2. Data on each specified element also include the text content of the parent element.
+    3. Data on each specified element also include data on its sibling nodes.
 */
 exports.reporter = async (page, detailLevel, tagName, onlyVisible, attribute) => {
   // Determine a selector of the specified elements.
@@ -11,120 +16,135 @@ exports.reporter = async (page, detailLevel, tagName, onlyVisible, attribute) =>
   if (onlyVisible) {
     selector += ':visible';
   }
+  let data = {};
   // Get the data on the elements.
-  const data = await page.$$eval(selector, (elements, detailLevel) => {
-    // FUNCTION DEFINITIONS START
-    // Compacts a string.
-    const compact = string => string.replace(/\s+/g, ' ').trim();
-    // Gets data on the sibling nodes of an element.
-    const getSibInfo = (node, nodeType, text) => {
-      const sibInfo = {
-        type: nodeType
-      };
-      if (nodeType === 1) {
-        sibInfo.tagName = node.tagName;
-      }
-      else if (nodeType === 3) {
-        sibInfo.text = compact(text);
-      }
-      return sibInfo;
-    };
-    // FUNCTION DEFINITIONS END
-    // Initialize the data with the count of the specified elements.
-    const data = {
-      total: elements.length
-    };
-    // If no itemization is required:
-    if (detailLevel === 0) {
-      // Return the element count.
-      return data;
-    }
-    // Otherwise, i.e. if itemization is required:
-    else {
-      // Initialize the item data.
-      data.items = [];
-      // For each specified element:
-      elements.forEach(element => {
-        // Initialize data on it.
-        const parent = element.parentElement;
-        const datum = {
-          tagName: element.tagName,
-          parentTagName: parent ? parent.tagName : '',
-          code: compact(element.outerHTML),
-          attributes: [],
-          textContent: compact(element.textContent)
+  try {
+    data = await page.$$eval(selector, (elements, detailLevel) => {
+      // FUNCTION DEFINITIONS START
+      // Compacts a string.
+      const compact = string => string.replace(/\s+/g, ' ').trim();
+      // Gets data on the sibling nodes of an element.
+      const getSibInfo = (node, nodeType, text) => {
+        const sibInfo = {
+          type: nodeType
         };
-        // For each of its attributes:
-        for (const attribute of element.attributes) {
-          // Add data on the attribute to the element data.
-          const {name, value} = attribute;
-          datum.attributes.push({
-            name,
-            value
-          });
-          // If the element has reference labels:
-          if (name === 'aria-labelledby') {
-            // Add their texts to the element data.
-            const labelerIDs = value.split(/\s+/);
-            const labelers = [];
-            labelerIDs.forEach(id => {
-              const labeler = document.getElementById(id);
-              if (labeler) {
-                labelers.push(compact(labeler.textContent));
-              }
-            });
-            if (labelers.length) {
-              datum.labelers = labelers;
-            }
-          }
+        if (nodeType === 1) {
+          sibInfo.tagName = node.tagName;
         }
-        // If the element has text content:
-        const {labels, textContent} = element;
-        const compactContent = compact(textContent);
-        if (compactContent) {
-          // Add it to the element data.
-          datum.textContent = compactContent;
+        else if (nodeType === 3) {
+          sibInfo.text = compact(text);
         }
-        // If the element has labels:
-        if (labels && labels.length) {
-          // Add their texts to the element data.
-          datum.labels = Array.from(labels).map(label => compact(label.textContent));
-        }
-        // If sibling itemization is required:
-        if (detailLevel === 2) {
-          // Add the sibling data to the element data.
-          datum.siblings = {
-            before: [],
-            after: []
+        return sibInfo;
+      };
+      // FUNCTION DEFINITIONS END
+      // Initialize the data with the count of the specified elements.
+      const data = {
+        total: elements.length
+      };
+      // If no itemization is required:
+      if (detailLevel === 0) {
+        // Return the element count.
+        return data;
+      }
+      // Otherwise, i.e. if itemization is required:
+      else {
+        // Initialize the item data.
+        data.items = [];
+        // For each specified element:
+        elements.forEach(element => {
+          // Initialize data on it.
+          const parent = element.parentElement;
+          const datum = {
+            tagName: element.tagName,
+            parentTagName: parent ? parent.tagName : '',
+            code: compact(element.outerHTML),
+            attributes: [],
+            textContent: compact(element.textContent)
           };
-          let more = element;
-          while (more) {
-            more = more.previousSibling;
-            if (more) {
-              const {nodeType, nodeValue} = more;
-              if (! (nodeType === 3 && nodeValue === '')) {
-                const sibInfo = getSibInfo(more, nodeType, nodeValue);
-                datum.siblings.before.unshift(sibInfo);
+          // For each of its attributes:
+          for (const attribute of element.attributes) {
+            // Add data on the attribute to the element data.
+            const {name, value} = attribute;
+            datum.attributes.push({
+              name,
+              value
+            });
+            // If the element has reference labels:
+            if (name === 'aria-labelledby') {
+              // Add their texts to the element data.
+              const labelerIDs = value.split(/\s+/);
+              const labelers = [];
+              labelerIDs.forEach(id => {
+                const labeler = document.getElementById(id);
+                if (labeler) {
+                  labelers.push(compact(labeler.textContent));
+                }
+              });
+              if (labelers.length) {
+                datum.labelers = labelers;
               }
             }
           }
-          more = element;
-          while (more) {
-            more = more.nextSibling;
-            if (more) {
-              const {nodeType, textContent} = more;
-              if (! (nodeType === 3 && textContent === '')) {
-                const sibInfo = getSibInfo(more, nodeType, compact(textContent));
-                datum.siblings.after.push(sibInfo);
+          // If the element has text content:
+          const {labels, textContent} = element;
+          const compactContent = compact(textContent);
+          if (compactContent) {
+            // Add it to the element data.
+            datum.textContent = compactContent;
+          }
+          // If the element has labels:
+          if (labels && labels.length) {
+            // Add their texts to the element data.
+            datum.labels = Array.from(labels).map(label => compact(label.textContent));
+          }
+          // If the parental text content is required:
+          if (detailLevel > 1) {
+            // Add it to the element data.
+            datum.parentTextContent = parent ? parent.textContent : '';
+          }
+          // If sibling itemization is required:
+          if (detailLevel === 3) {
+            // Add the sibling data to the element data.
+            datum.siblings = {
+              before: [],
+              after: []
+            };
+            let more = element;
+            while (more) {
+              more = more.previousSibling;
+              if (more) {
+                const {nodeType, nodeValue} = more;
+                if (! (nodeType === 3 && nodeValue === '')) {
+                  const sibInfo = getSibInfo(more, nodeType, nodeValue);
+                  datum.siblings.before.unshift(sibInfo);
+                }
+              }
+            }
+            more = element;
+            while (more) {
+              more = more.nextSibling;
+              if (more) {
+                const {nodeType, textContent} = more;
+                if (! (nodeType === 3 && textContent === '')) {
+                  const sibInfo = getSibInfo(more, nodeType, compact(textContent));
+                  datum.siblings.after.push(sibInfo);
+                }
               }
             }
           }
-        }
-        data.items.push(datum);
-      });
-      return data;
-    }
-  }, detailLevel);
+          data.items.push(datum);
+        });
+        return data;
+      }
+    }, detailLevel);
+  }
+  catch(error) {
+    console.log(`ERROR performing test (${error.message})`);
+    data = {
+      prevented: true,
+      error: 'ERROR performing test'
+    };
+  }
   // Return the result.
   return {result: data};
 };