testaro 5.9.2 → 5.11.0

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'],
@@ -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.2",
+  "version": "5.11.0",
   "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;
   }
@@ -715,8 +625,8 @@ const doActs = async (report, actIndex, page) => {
         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 +636,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 +674,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 +687,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 +702,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 +733,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 +776,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 +933,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 +1150,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 +1169,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 +1204,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 +1338,7 @@ const doActs = async (report, actIndex, page) => {
               }
               // Add the result to the act.
               act.result = {
+                success: true,
                 status,
                 totals: {
                   presses,
@@ -1322,32 +1358,44 @@ 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');
       }
     }
     // 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;

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};
 };