testaro 5.7.6 → 5.9.1

package/commands.js

@@ -150,6 +150,15 @@ exports.commands = {
         rules: [true, 'array', 'areStrings', 'rule names, or empty if all']
       }
     ],
+    elements: [
+      'Perform an elements test',
+      {
+        detailLevel: [true, 'number', '', '0 = counts, 1 = selves, 2 = also sibling nodes'],
+        tagName: [false, 'string', '', 'tag name of elements'],
+        onlyVisible: [false, 'boolean', '', 'whether to exclude invisible elements'],
+        attribute: [false, 'string', 'hasLength', 'required attribute or attribute=value']
+      }
+    ],
     embAc: [
       'Perform an embAc test',
       {

package/package.json

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

package/run.js

@@ -34,6 +34,7 @@ const tests = {
   bulk: 'count of visible elements',
   continuum: 'Level Access Continuum, community edition',
   docType: 'document without a doctype property',
+  elements: 'data on specified elements',
   embAc: 'active elements embedded in links or buttons',
   focAll: 'focusable and Tab-focused elements',
   focInd: 'focus indicators',
@@ -55,6 +56,7 @@ const tests = {
   styleDiff: 'style inconsistencies',
   tabNav: 'keyboard navigation between tab elements',
   tenon: 'Tenon',
+  title: 'page title',
   titledEl: 'title attributes on inappropriate elements',
   wave: 'WAVE',
   zIndex: 'z indexes'
@@ -81,6 +83,7 @@ const errorWords = [
   'content security policy',
   'deprecated',
   'error',
+  'expected',
   'failed',
   'invalid',
   'missing',
@@ -442,7 +445,7 @@ const textOf = async (page, element) => {
     return null;
   }
 };
-// Returns an element of a type case-insensitively matching a text.
+// Returns an element of a type case-insensitively including a text.
 const matchElement = async (page, selector, matchText, index = 0) => {
   if (matchText) {
     // If the page still exists:
@@ -454,14 +457,18 @@ const matchElement = async (page, selector, matchText, index = 0) => {
       if (selections.length) {
         // If there are enough to make a match possible:
         if (index < selections.length) {
-          // Return the specified one, if any.
+          // For each element of the specified type:
           let matchCount = 0;
           const selectionTexts = [];
           for (const selection of selections) {
+            // Add its text to the list of texts of such elements.
             const selectionText = await textOf(page, selection);
             selectionTexts.push(selectionText);
+            // If its text includes the specified text:
             if (selectionText.includes(slimText)) {
+              // If the count of such elements with such texts found so far is the specified count:
               if (matchCount++ === index) {
+                // Return it as the matching element.
                 return {
                   success: true,
                   matchingElement: selection
@@ -661,7 +668,8 @@ const isTrue = (object, specs) => {
 // Adds a wait error result to an act.
 const waitError = (page, act, error, what) => {
   console.log(`ERROR waiting for ${what} (${error.message})`);
-  act.result = {url: page.url()};
+  act.result.found = false;
+  act.result.url = page.url();
   act.result.error = `ERROR waiting for ${what}`;
   return false;
 };
@@ -754,49 +762,57 @@ const doActs = async (report, actIndex, page) => {
         // Otherwise, if the act is a wait for text:
         else if (act.type === 'wait') {
           const {what, which} = act;
-          console.log(`>> for ${what} to include “${which}”`);
-          // Wait 5 or 10 seconds for the specified text, and quit if it does not appear.
-          if (act.what === 'url') {
-            await page.waitForURL(act.which, {timeout: 15000})
-            .catch(error => {
+          console.log(`>> ${what}`);
+          const result = act.result = {};
+          // Wait for the specified text, and quit if it does not appear.
+          if (what === 'url') {
+            try {
+              await page.waitForURL(which, {timeout: 15000});
+              result.found = true;
+              result.url = page.url();
+            }
+            catch(error) {
               actIndex = -2;
               waitError(page, act, error, 'URL');
-            });
+            }
           }
-          else if (act.what === 'title') {
-            await page.waitForFunction(
-              text => document && document.title && document.title.includes(text),
-              act.which,
-              {
-                polling: 1000,
-                timeout: 5000
-              }
-            )
-            .catch(error => {
+          else if (what === 'title') {
+            try {
+              await page.waitForFunction(
+                text => document
+                && document.title
+                && document.title.toLowerCase().includes(text.toLowerCase()),
+                which,
+                {
+                  polling: 1000,
+                  timeout: 5000
+                }
+              );
+              result.found = true;
+              result.title = await page.title(); 
+            }
+            catch(error) {
               actIndex = -2;
               waitError(page, act, error, 'title');
-            });
+            }
           }
-          else if (act.what === 'body') {
-            await page.waitForFunction(
-              text => document && document.body && document.body.innerText.includes(text),
-              act.which,
-              {
-                polling: 2000,
-                timeout: 10000
-              }
-            )
-            .catch(async error => {
+          else if (what === 'body') {
+            try {
+              await page.waitForFunction(
+                text => document
+                && document.body
+                && document.body.innerText.toLowerCase().includes(text.toLowerCase()),
+                which,
+                {
+                  polling: 2000,
+                  timeout: 10000
+                }
+              );
+              result.found = true;
+            }
+            catch(error) {
               actIndex = -2;
               waitError(page, act, error, 'body');
-            });
-          }
-          // If the text was found:
-          if (actIndex > -2) {
-            // Add this to the report.
-            act.result = {url: page.url()};
-            if (act.what === 'title') {
-              act.result.title = await page.title();
             }
           }
         }
@@ -1054,24 +1070,36 @@ const doActs = async (report, actIndex, page) => {
                   await matchingElement.focus({timeout: 2000});
                   act.result = 'focused';
                 }
-                // Otherwise, if it is clicking a link, perform it.
+                // Otherwise, if it is clicking a link:
                 else if (act.type === 'link') {
+                  // Try to click it.
                   const href = await matchingElement.getAttribute('href');
                   const target = await matchingElement.getAttribute('target');
-                  await matchingElement.click({timeout: 2000})
-                  .catch(async () => {
-                    console.log('ERROR: First attempt to click link timed out');
+                  await matchingElement.click({timeout: 3000})
+                  // If it cannot be clicked within 3 seconds:
+                  .catch(async error => {
+                    // Try to force-click it without actionability checks.
+                    const errorSummary = error.message.replace(/\n.+/, '');
+                    console.log(`ERROR: Link to ${href} not clickable (${errorSummary})`);
                     await matchingElement.click({
-                      force: true,
-                      timeout: 10000
+                      force: true
                     })
-                    .catch(() => {
+                    // If it cannot be force-clicked:
+                    .catch(error => {
+                      // Quit and report the failure.
                       actIndex = -2;
-                      console.log('ERROR: Second (forced) attempt to click link timed out');
-                      act.result = 'ERROR: Normal and forced click attempts timed out';
+                      const errorSummary = error.message.replace(/\n.+/, '');
+                      console.log(`ERROR: Link to ${href} not force-clickable (${errorSummary})`);
+                      act.result = {
+                        href: href || 'NONE',
+                        target: target || 'NONE',
+                        error: 'ERROR: Normal and forced attempts to click link timed out'
+                      };
                     });
                   });
+                  // If it was clicked:
                   if (actIndex > -2) {
+                    // Report the success.
                     act.result = {
                       href: href || 'NONE',
                       target: target || 'NONE',
@@ -1089,7 +1117,9 @@ const doActs = async (report, actIndex, page) => {
                       const optionText = await option.textContent();
                       optionTexts.push(optionText);
                     }
-                    const matchTexts = optionTexts.map((text, index) => text.includes(act.what) ? index : -1);
+                    const matchTexts = optionTexts.map(
+                      (text, index) => text.includes(act.what) ? index : -1
+                    );
                     const index = matchTexts.filter(text => text > -1)[act.index || 0];
                     if (index !== undefined) {
                       await matchingElement.selectOption({index});
@@ -1185,7 +1215,7 @@ const doActs = async (report, actIndex, page) => {
                     }
                     // If there is a current element:
                     if (currentElement) {
-                      // If it was already reached within this command performance:
+                      // If it was already reached within this act:
                       if (currentElement.dataset.pressesReached === actCount.toString(10)) {
                         // Report the error.
                         console.log(`ERROR: ${currentElement.tagName} element reached again`);
@@ -1319,6 +1349,8 @@ const doActs = async (report, actIndex, page) => {
       const errorMsg = `ERROR: Invalid command of type ${act.type}`;
       act.result = errorMsg;
       console.log(errorMsg);
+      // Quit.
+      actIndex = -2;
     }
     // Perform the remaining acts.
     await doActs(report, actIndex + 1, page);

package/tests/elements.js

@@ -0,0 +1,130 @@
+/*
+  elements
+  This test reports data about specified elements.
+*/
+exports.reporter = async (page, detailLevel, tagName, onlyVisible, attribute) => {
+  // Determine a selector of the specified elements.
+  let selector = tagName || '*';
+  if (attribute) {
+    selector += `[${attribute}]`;
+  }
+  if (onlyVisible) {
+    selector += ':visible';
+  }
+  // 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)
+        };
+        // 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 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 sibling itemization is required:
+        if (detailLevel === 2) {
+          // 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);
+  // Return the result.
+  return {result: data};
+};

package/tests/title.js

@@ -0,0 +1,8 @@
+/*
+  title
+  This test reports the page title.
+*/
+exports.reporter = async page => {
+  const title = await page.title();
+  return {result: title};
+};