testaro 5.9.3 → 5.11.1

package/README.md

@@ -316,6 +316,8 @@ Tenon recommends giving it a public URL rather than giving it the content of a p
 
 The `continuum` test makes use of the files in the `continuum` directory. The test inserts the contents of all three files into the page as scripts and then uses them to perform the tests of the Continuum package.
 
+Level Access on 22 August 2022 granted authorization for the copying of the `AccessEngine.community.js` file insofar as necessary for allowing Continuum community edition tests to be included in Testaro.
+
 ###### HTML CodeSniffer
 
 The `htmlcs` test makes use of the`htmlcs/HTMLCS.js` file. That file was created, and can be recreated if necessary, as follows:

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'],

package/package.json

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

package/run.js

@@ -12,7 +12,7 @@ const {commands} = require('./commands');
 
 // ########## CONSTANTS
 
-// Set DEBUG environment variable to 'true' to add debugging features.
+// Set DEBUG environment variable to 'true,' to add debugging features.
 const debug = process.env.DEBUG === 'true';
 // Set WAITS environment variable to a positive number to insert delays (in ms).
 const waits = Number.parseInt(process.env.WAITS) || 0;
@@ -294,16 +294,11 @@ const launch = async typeName => {
     });
     // If the launch succeeded:
     if (healthy) {
-      // Create a new context (window) in it, taller if debugging is on.
-      const viewport = debug ? {
-        viewPort: {
-          width: 1280,
-          height: 1120
-        }
-      } : {};
-      browserContext = await browser.newContext(viewport);
-      // When a page is added to the browser context:
-      browserContext.on('page', page => {
+      browserContext = await browser.newContext();
+      // When a page (i.e. browser tab) is added to the browser context (i.e. browser window):
+      browserContext.on('page', async page => {
+        // Activate the page.
+        await page.bringToFront();
         // Make abbreviations of its console messages get reported in the Playwright console.
         page.on('console', msg => {
           const msgText = msg.text();
@@ -339,12 +334,6 @@ const launch = async typeName => {
       });
       // Open the first page of the context.
       const page = await browserContext.newPage();
-      if (debug) {
-        page.setViewportSize({
-          width: 1280,
-          height: 1120
-        });
-      }
       // Wait until it is stable.
       await page.waitForLoadState('domcontentloaded');
       // Update the name of the current browser type and store it in the page.
@@ -445,85 +434,6 @@ const textOf = async (page, element) => {
     return null;
   }
 };
-// 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:
-    if (page) {
-      const slimText = debloat(matchText);
-      // Identify the elements of the specified type.
-      const selections = await page.$$(selector);
-      // If there are any:
-      if (selections.length) {
-        // If there are enough to make a match possible:
-        if (index < selections.length) {
-          // 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
-                };
-              }
-            }
-          }
-          // None satisfied the specifications, so return a failure.
-          return {
-            success: false,
-            error: 'exhausted',
-            message: `Text found in only ${matchCount} (not ${index + 1}) of ${selections.length}`,
-            candidateTexts: selectionTexts
-          };
-        }
-        // Otherwise, i.e. if there are too few such elements to make a match possible:
-        else {
-          // Return a failure.
-          return {
-            success: false,
-            error: 'fewer',
-            message: `Count of '${selector}' elements only ${selections.length}`
-          };
-        }
-      }
-      // Otherwise, i.e. if there are no elements of the specified type:
-      else {
-        // Return a failure.
-        return {
-          success: false,
-          error: 'none',
-          message: `No '${selector}' elements found`
-        };
-      }
-    }
-    // Otherwise, i.e. if the page no longer exists:
-    else {
-      // Return a failure.
-      return {
-        success: false,
-        error: 'gone',
-        message: 'Page gone'
-      };
-    }
-  }
-  // Otherwise, i.e. if no text was specified:
-  else {
-    // Return a failure.
-    return {
-      success: false,
-      error: 'text',
-      message: 'No text specified'
-    };
-  }
-};
 // Returns a string with any final slash removed.
 const deSlash = string => string.endsWith('/') ? string.slice(0, -1) : string;
 // Tries to visit a URL.
@@ -682,10 +592,10 @@ const wait = ms => {
   });
 };
 // Adds an error result to an act.
-const addError = (act, error) => {
-  act.result = {
-    error
-  };
+const addError = (act, error, message) => {
+  act.result.success = false;
+  act.result.error = error;
+  act.result.message = message;
   if (act.type === 'test') {
     act.result.prevented = true;
   }
@@ -709,14 +619,15 @@ const doActs = async (report, actIndex, page) => {
       console.log(`>>>> ${act.type}${whichSuffix}`);
       // Increment the count of commands performed.
       actCount++;
+      act.startTime = Date.now();
       // If the command is an index changer:
       if (act.type === 'next') {
         const condition = act.if;
         const logSuffix = condition.length === 3 ? ` ${condition[1]} ${condition[2]}` : '';
         console.log(`>> ${condition[0]}${logSuffix}`);
         // Identify the act to be checked.
-        const ifActIndex = report.acts.map(act => act.type !== 'next').lastIndexOf(true);
-        // Determine whether its jump condition is true.
+        const ifActIndex = report.acts.map(act => act.type !== 'next').lastIndexOf(true,);
+        // Determine whether its jump condition is true,.
         const truth = isTrue(report.acts[ifActIndex].result, condition);
         // Add the result to the act.
         act.result = {
@@ -726,7 +637,7 @@ const doActs = async (report, actIndex, page) => {
           value: truth[0],
           jumpRequired: truth[1]
         };
-        // If the condition is true:
+        // If the condition is true,:
         if (truth[1]) {
           // If the performance of commands is to stop:
           if (act.jump === 0) {
@@ -764,8 +675,9 @@ const doActs = async (report, actIndex, page) => {
           const {what, which} = act;
           console.log(`>> ${what}`);
           const result = act.result = {};
-          // Wait for the specified text, and quit if it does not appear.
+          // If the text is to be the URL:
           if (what === 'url') {
+            // Wait for it up to 15 seconds and quit on failure.
             try {
               await page.waitForURL(which, {timeout: 15000});
               result.found = true;
@@ -776,7 +688,9 @@ const doActs = async (report, actIndex, page) => {
               waitError(page, act, error, 'URL');
             }
           }
+          // Otherwise, if the text is to be a substring of the page title:
           else if (what === 'title') {
+            // Wait for it up to 5 seconds and quit on failure.
             try {
               await page.waitForFunction(
                 text => document
@@ -789,14 +703,16 @@ const doActs = async (report, actIndex, page) => {
                 }
               );
               result.found = true;
-              result.title = await page.title(); 
+              result.title = await page.title();
             }
             catch(error) {
               actIndex = -2;
               waitError(page, act, error, 'title');
             }
           }
+          // Otherwise, if the text is to be a substring of the text of the page body:
           else if (what === 'body') {
+            // Wait for it up to 10 seconds and quit on failure.
             try {
               await page.waitForFunction(
                 text => document
@@ -818,27 +734,33 @@ const doActs = async (report, actIndex, page) => {
         }
         // Otherwise, if the act is a wait for a state:
         else if (act.type === 'state') {
-          // Wait for it, and quit if it does not appear.
+          // Wait for it up to 5 or 10 seconrds, and quit on failure.
           const stateIndex = ['loaded', 'idle'].indexOf(act.which);
           await page.waitForLoadState(
             ['domcontentloaded', 'networkidle'][stateIndex], {timeout: [10000, 5000][stateIndex]}
           )
           .catch(error => {
             console.log(`ERROR waiting for page to be ${act.which} (${error.message})`);
-            addError(act, `ERROR waiting for page to be ${act.which}`);
+            act.result = {
+              success: false,
+              error: `ERROR waiting for page to be ${act.which}`
+            };
             actIndex = -2;
           });
           if (actIndex > -2) {
-            addError(`Page became ${act.which}`);
+            act.result = {
+              success: true,
+              state: act.which
+            };
           }
         }
         // Otherwise, if the act is a page switch:
         else if (act.type === 'page') {
           // Wait for a page to be created and identify it as current.
           page = await browserContext.waitForEvent('page');
-          // Wait until it is stable and thus ready for the next act.
+          // Wait up to 20 seconds until it is idle.
           await page.waitForLoadState('networkidle', {timeout: 20000});
-          // Add the resulting URL and any description of it to the act.
+          // Add the resulting URL to the act.
           const result = {
             url: page.url()
           };
@@ -855,7 +777,9 @@ const doActs = async (report, actIndex, page) => {
             if (act.type === 'reveal') {
               // Make all elements in the page visible.
               await require('./procs/allVis').allVis(page);
-              act.result = 'All elements visible.';
+              act.result = {
+                success: true,
+              };
             }
             // Otherwise, if the act is a tenon request:
             else if (act.type === 'tenonRequest') {
@@ -1010,106 +934,211 @@ const doActs = async (report, actIndex, page) => {
                 });
                 testReport.result.failureCount = failureCount;
               }
+              testReport.result.success = true;
               report.testTimes.push([act.which, Math.round((Date.now() - startTime) / 1000)]);
               report.testTimes.sort((a, b) => b[1] - a[1]);
               // Add the result object (possibly an array) to the act.
               const resultCount = Object.keys(testReport.result).length;
-              act.result = resultCount ? testReport.result : 'NONE';
+              act.result = resultCount ? testReport.result : {success: false};
             }
             // Otherwise, if the act is a move:
             else if (moves[act.type]) {
               const selector = typeof moves[act.type] === 'string' ? moves[act.type] : act.what;
-              // Try up to 5 times, every 2 seconds, to identify the element to perform the move on.
-              let matchResult = {success: false};
+              // Try for up to 10 seconds to identify the element to perform the move on.
+              act.result = {found: false};
+              let selection = {};
               let tries = 0;
-              while (tries++ < 5 && ! matchResult.success) {
-                matchResult = await matchElement(page, selector, act.which || '', act.index);
-                if (! matchResult.success) {
+              const slimText = debloat(act.which);
+              while (tries++ < 5 && ! act.result.found) {
+                if (act.which) {
+                  // If the page still exists:
+                  if (page) {
+                    // Identify the elements of the specified type.
+                    const selections = await page.$$(selector);
+                    // If there are any:
+                    if (selections.length) {
+                      // If there are enough to make a match possible:
+                      if ((act.index || 0) < selections.length) {
+                        // For each element of the specified type:
+                        let matchCount = 0;
+                        const selectionTexts = [];
+                        for (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 element has the specified index among such elements:
+                            if (matchCount++ === (act.index || 0)) {
+                              // Report it as the matching element and stop checking.
+                              act.result.found = true;
+                              act.result.text = slimText;
+                              break;
+                            }
+                          }
+                        }
+                        // If no element satisfied the specifications:
+                        if (! act.result.found) {
+                          act.result.success = false;
+                          act.result.error = 'exhausted';
+                          act.result.typeElementCount = selections.length;
+                          act.result.textElementCount = --matchCount;
+                          act.result.message = 'Not enough elements have the specified text';
+                          act.result.candidateTexts = selectionTexts;
+                        }
+                      }
+                      // Otherwise, i.e. if there are too few such elements to make a match possible:
+                      else {
+                        // Return a failure.
+                        act.result.success = false;
+                        act.result.error = 'fewer';
+                        act.result.typeElementCount = selections.length;
+                        act.result.message = 'Elements of specified type too few';
+                      }
+                    }
+                    // Otherwise, i.e. if there are no elements of the specified type:
+                    else {
+                      // Return a failure.
+                      act.result.success = false;
+                      act.result.error = 'none';
+                      act.result.typeElementCount = 0;
+                      act.result.message = 'No elements specified type found';
+                    }
+                  }
+                  // Otherwise, i.e. if the page no longer exists:
+                  else {
+                    // Return a failure.
+                    act.result.success = false;
+                    act.result.error = 'gone';
+                    act.result.message = 'Page gone';
+                  }
+                }
+                // Otherwise, i.e. if no text was specified:
+                else {
+                  // Return a failure.
+                  act.result.success = false;
+                  act.result.error = 'text';
+                  act.result.message = 'No text specified';
+                }
+                if (! act.result.found) {
                   await wait(2000);
                 }
               }
               // If a match was found:
-              if (matchResult.success) {
-                const {matchingElement} = matchResult;
+              if (act.result.found) {
                 // If the move is a button click, perform it.
                 if (act.type === 'button') {
-                  await matchingElement.click({timeout: 3000});
-                  act.result = 'clicked';
+                  await selection.click({timeout: 3000});
+                  act.result.success = true;
+                  act.result.move = 'clicked';
                 }
                 // Otherwise, if it is checking a radio button or checkbox, perform it.
                 else if (['checkbox', 'radio'].includes(act.type)) {
-                  await matchingElement.waitForElementState('stable', {timeout: 2000})
+                  await selection.waitForElementState('stable', {timeout: 2000})
                   .catch(error => {
                     console.log(`ERROR waiting for stable ${act.type} (${error.message})`);
-                    addError(act, `ERROR waiting for stable ${act.type}`);
+                    act.result.success = false;
+                    act.result.error = `ERROR waiting for stable ${act.type}`;
                   });
-                  if (! act.result) {
-                    const isEnabled = await matchingElement.isEnabled();
+                  if (! act.result.error) {
+                    const isEnabled = await selection.isEnabled();
                     if (isEnabled) {
-                      await matchingElement.check({
+                      await selection.check({
                         force: true,
                         timeout: 2000
                       })
                       .catch(error => {
                         console.log(`ERROR checking ${act.type} (${error.message})`);
-                        addError(act, `ERROR checking ${act.type}`);
+                        act.result.success = false;
+                        act.result.error = `ERROR checking ${act.type}`;
                       });
-                      if (! act.result) {
-                        act.result = 'checked';
+                      if (! act.result.error) {
+                        act.result.success = true;
+                        act.result.move = 'checked';
                       }
                     }
                     else {
                       const report = `ERROR: could not check ${act.type} because disabled`;
                       console.log(report);
-                      act.result = report;
+                      act.result.success = false;
+                      act.result.error = report;
                     }
                   }
                 }
                 // Otherwise, if it is focusing the element, perform it.
                 else if (act.type === 'focus') {
-                  await matchingElement.focus({timeout: 2000});
-                  act.result = 'focused';
+                  await selection.focus({timeout: 2000});
+                  act.result.success = true;
+                  act.result.move = 'focused';
                 }
                 // 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: 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
-                    })
-                    // If it cannot be force-clicked:
-                    .catch(error => {
+                  const href = await selection.getAttribute('href');
+                  const target = await selection.getAttribute('target');
+                  act.result.href = href || 'NONE';
+                  act.result.target = target || 'DEFAULT';
+                  // If the destination is a new page:
+                  if (target && target !== '_self') {
+                    // Click the link and wait for the resulting page event.
+                    try {
+                      const [newPage] = await Promise.all([
+                        page.context().waitForEvent('page', {timeout: 6000}),
+                        selection.click({timeout: 5000})
+                      ]);
+                      // Wait for the new page to load.
+                      await newPage.waitForLoadState('domcontentloaded', {timeout: 6000});
+                      // Make the new page the current page.
+                      page = newPage;
+                      act.result.success = true;
+                      act.result.move = 'clicked';
+                      act.result.newURL = page.url();
+                    }
+                    // If the click, event, or load failed:
+                    catch(error) {
                       // Quit and report the failure.
+                      console.log(
+                        `ERROR clicking new-page link (${error.message.replace(/\n.+/s, '')})`
+                      );
+                      act.result.success = false;
+                      act.result.error = 'unclickable';
+                      act.result.message = 'ERROR: click and new-page navigation timed out';
                       actIndex = -2;
-                      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'
-                      };
+                    }
+                  }
+                  // Otherwise, i.e. if the destination is in the current page:
+                  else {
+                    // Click the link and wait for the resulting navigation.
+                    await selection.click({timeout: 5000})
+                    // If the click and navigation time out:
+                    .catch(async error => {
+                      // Try to force-click it and wait for the navigation.
+                      const errorSummary = error.message.replace(/\n.+/s, '');
+                      console.log(`ERROR: Link to ${href} not clickable (${errorSummary})`);
+                      await selection.click({
+                        force: true,
+                        timeout: 3000
+                      })
+                      // If it cannot be force-clicked:
+                      .catch(error => {
+                        // Quit and report the failure.
+                        actIndex = -2;
+                        const errorSummary = error.message.replace(/\n.+/s, '');
+                        console.log(`ERROR: Link to ${href} not force-clickable (${errorSummary})`);
+                        act.result.success = false;
+                        act.result.error = 'unclickable';
+                        act.result.message = 'ERROR: Normal and forced click attempts timed out';
+                      });
                     });
-                  });
-                  // If it was clicked:
-                  if (actIndex > -2) {
-                    // Report the success.
-                    act.result = {
-                      href: href || 'NONE',
-                      target: target || 'NONE',
-                      move: 'clicked'
-                    };
+                    // If the link click succeeded:
+                    if (! act.result.error) {
+                      act.result.success = true;
+                      act.result.move = 'clicked';
+                    }
                   }
                 }
                 // Otherwise, if it is selecting an option in a select list, perform it.
                 else if (act.type === 'select') {
-                  const options = await matchingElement.$$('option');
+                  const options = await selection.$$('option');
                   let optionText = '';
                   if (options && Array.isArray(options) && options.length) {
                     const optionTexts = [];
@@ -1122,13 +1151,13 @@ const doActs = async (report, actIndex, page) => {
                     );
                     const index = matchTexts.filter(text => text > -1)[act.index || 0];
                     if (index !== undefined) {
-                      await matchingElement.selectOption({index});
+                      await selection.selectOption({index});
                       optionText = optionTexts[index];
                     }
                   }
-                  act.result = optionText
-                    ? `“${optionText}” selected`
-                    : 'ERROR: option not found';
+                  act.result.success = true;
+                  act.result.move = 'selected';
+                  act.result.option = optionText;
                 }
                 // Otherwise, if it is entering text on the element:
                 else if (act.type === 'text') {
@@ -1141,22 +1170,26 @@ const doActs = async (report, actIndex, page) => {
                     what = what.replace(/__[A-Z]+__/, envValue);
                   }
                   // Enter the text.
-                  await matchingElement.type(act.what);
+                  await selection.type(act.what);
                   report.presses += act.what.length;
-                  act.result = 'entered';
+                  act.result.success = true;
+                  act.result.move = 'entered';
                 }
                 // Otherwise, i.e. if the move is unknown, add the failure to the act.
                 else {
                   // Report the error.
                   const report = 'ERROR: move unknown';
-                  act.result = report;
+                  act.result.success = false;
+                  act.result.error = report;
                   console.log(report);
                 }
               }
               // Otherwise, i.e. if no match was found:
               else {
                 // Stop.
-                act.result = matchResult;
+                act.result.success = false;
+                act.result.error = 'absent';
+                act.result.message = 'ERROR: specified element not found';
                 console.log('ERROR: Specified element not found');
                 actIndex = -2;
               }
@@ -1172,7 +1205,10 @@ const doActs = async (report, actIndex, page) => {
                 await page.keyboard.press(key);
               }
               const qualifier = act.again ? `${1 + act.again} times` : 'once';
-              act.result = `pressed ${qualifier}`;
+              act.result = {
+                success: true,
+                message: `pressed ${qualifier}`
+              };
             }
             // Otherwise, if it is a repetitive keyboard navigation:
             else if (act.type === 'presses') {
@@ -1303,6 +1339,7 @@ const doActs = async (report, actIndex, page) => {
               }
               // Add the result to the act.
               act.result = {
+                success: true,
                 status,
                 totals: {
                   presses,
@@ -1322,32 +1359,45 @@ const doActs = async (report, actIndex, page) => {
             // Otherwise, i.e. if the act type is unknown:
             else {
               // Add the error result to the act.
-              act.result = 'ERROR: invalid command type';
+              act.result = {
+                success: false,
+                error: 'badType',
+                message: 'ERROR: invalid command type'
+              };
             }
           }
           // Otherwise, i.e. if redirection is prohibited but occurred:
           else {
-            // Add the error result to the act.
-            addError(act, `ERROR: Page URL wrong (${url})`);
+            // Add an error result to the act.
+            act.result = {
+              success: false,
+              error: 'redirection',
+              message: `ERROR: Page redirected to (${url})`
+            };
           }
         }
         // Otherwise, i.e. if the required page URL does not exist:
         else {
           // Add an error result to the act.
-          addError(act, 'ERROR: Page has no URL');
+          addError(act, 'noURL', 'ERROR: Page has no URL');
         }
       }
       // Otherwise, i.e. if no page exists:
       else {
         // Add an error result to the act.
-        addError(act, 'ERROR: No page identified');
+        addError(act, 'noPage', 'ERROR: No page identified');
       }
+      act.endTime = Date.now();
     }
     // Otherwise, i.e. if the command is invalid:
     else {
       // Add an error result to the act.
       const errorMsg = `ERROR: Invalid command of type ${act.type}`;
-      act.result = errorMsg;
+      act.result = {
+        success: false,
+        error: 'badCommand',
+        message: errorMsg
+      };
       console.log(errorMsg);
       // Quit.
       actIndex = -2;