testaro 8.4.7 → 9.0.0

package/run.js

@@ -7,8 +7,10 @@
 
 // Module to keep secrets.
 require('dotenv').config();
-// Requirements for commands.
-const {commands} = require('./commands');
+// Requirements for acts.
+const {actSpecs} = require('./actSpecs');
+// Playwright package.
+const playwright = require('playwright');
 
 // ########## CONSTANTS
 
@@ -16,7 +18,6 @@ const {commands} = require('./commands');
 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;
-const urlInject = process.env.URL_INJECT || 'yes';
 // CSS selectors for targets of moves.
 const moves = {
   button: 'button, [role=button], input[type=submit]',
@@ -66,20 +67,6 @@ const tests = {
   wave: 'WAVE',
   zIndex: 'z indexes'
 };
-// Tests that may change the DOM.
-const domChangers = new Set([
-  'axe',
-  'continuum',
-  'focAll',
-  'focInd',
-  'focOp',
-  'hover',
-  'htmlcs',
-  'ibm',
-  'menuNav',
-  'textNodes',
-  'wave'
-]);
 // Browser types available in PlayWright.
 const browserTypeNames = {
   'chromium': 'Chrome',
@@ -187,24 +174,24 @@ const hasSubtype = (variable, subtype) => {
     return true;
   }
 };
-// Validates a command.
-const isValidCommand = command => {
-  // Identify the type of the command.
-  const type = command.type;
+// Validates an act.
+const isValidAct = act => {
+  // Identify the type of the act.
+  const type = act.type;
   // If the type exists and is known:
-  if (type && commands.etc[type]) {
+  if (type && actSpecs.etc[type]) {
     // Copy the validator of the type for possible expansion.
-    const validator = Object.assign({}, commands.etc[type][1]);
+    const validator = Object.assign({}, actSpecs.etc[type][1]);
     // If the type is test:
     if (type === 'test') {
       // Identify the test.
-      const testName = command.which;
+      const testName = act.which;
       // If one was specified and is known:
       if (testName && tests[testName]) {
         // If it has special properties:
-        if (commands.tests[testName]) {
+        if (actSpecs.tests[testName]) {
           // Expand the validator by adding them.
-          Object.assign(validator, commands.tests[testName][1]);
+          Object.assign(validator, actSpecs.tests[testName][1]);
         }
       }
       // Otherwise, i.e. if no or an unknown test was specified:
@@ -213,22 +200,22 @@ const isValidCommand = command => {
         return false;
       }
     }
-    // Return whether the command is valid.
+    // Return whether the act is valid.
     return Object.keys(validator).every(property => {
       if (property === 'name') {
         return true;
       }
       else {
         const vP = validator[property];
-        const cP = command[property];
-        // If it is optional and omitted or present and valid:
-        const optAndNone = ! vP[0] && ! cP;
-        const isValidCommand = cP !== undefined && hasType(cP, vP[1]) && hasSubtype(cP, vP[2]);
-        return optAndNone || isValidCommand;
+        const aP = act[property];
+        // If it is optional and omitted or is present and valid:
+        const optAndNone = ! vP[0] && ! aP;
+        const isValidAct = aP !== undefined && hasType(aP, vP[1]) && hasSubtype(aP, vP[2]);
+        return optAndNone || isValidAct;
       }
     });
   }
-  // Otherwise, i.e. if the command has an unknown or no type:
+  // Otherwise, i.e. if the act has an unknown or no type:
   else {
     // Return invalidity.
     return false;
@@ -238,42 +225,60 @@ const isValidCommand = command => {
 const isValidReport = report => {
   if (report) {
     // Return whether the report is valid.
-    const {job, acts, jobData} = report;
-    const {id, what, strict, commands, sources, jobCreationTime, timeStamp} = job;
-    const criteria = [
-      [job, 'report has job property'],
-      [acts, 'report has acts property'],
-      [jobData, 'report has jobData property'],
-      [id, 'job has id property'],
-      [what, 'job has what property'],
-      [typeof strict === 'boolean', 'job has true or false strict property'],
-      [commands, 'job has commands property'],
-      [sources, 'job has sources property'],
-      [jobCreationTime, 'job has jobCreationTime property'],
-      [timeStamp, 'job has timeStamp property'],
-      [Array.isArray(acts), 'acts has array value'],
-      [typeof id === 'string', 'id has string value'],
-      [typeof what === 'string', 'what has string value'],
-      [Array.isArray(commands), 'commands has array value'],
-      [commands[0].type, 'first command has type property'],
-      [commands[0].type === 'launch', 'first command has launch type'],
-      [commands.length > 1, 'command count greater than 1'],
-      [commands[1].type, 'second command has type property'],
-      [commands[1].type === 'url', 'second command has url type'],
-      [commands[1].which, 'second command has which property'],
-      [isURL(commands[1].which), 'second command which property has URL value'],
-      [commands.every(command => isValidCommand(command)), 'every command is valid'],
-      [sources && typeof sources.script === 'string', 'sources has script property with string value'],
-      [sources && sources.host, 'sources has host property']
-    ];
-    const invalidityIndex = criteria.findIndex(criterion => ! criterion[0]);
-    if (invalidityIndex > -1) {
-      console.log(`ERROR: report fails “${criteria[invalidityIndex][1]}” requirement`);
+    const {id, what, strict, timeLimit, acts, sources, creationTime, timeStamp} = report;
+    if (! id || typeof id !== 'string') {
+      return 'Bad report ID';
     }
-    return invalidityIndex === -1;
+    if (! what || typeof what !== 'string') {
+      return 'Bad report what';
+    }
+    if (! strict || typeof strict !== 'boolean') {
+      return 'Bad report strict';
+    }
+    if (! timeLimit || typeof timeLimit !== 'number' || timeLimit < 1) {
+      return 'Bad report time limit';
+    }
+    if (! acts || ! Array.isArray(acts) || acts.length < 2) {
+      return 'Bad report acts';
+    }
+    if (! acts.every(act => act.type && typeof act.type === 'string')) {
+      return 'Act with no type';
+    }
+    if (acts[0].type !== 'launch') {
+      return 'First act type not launch';
+    }
+    if (acts[1].type !== 'url') {
+      return 'Second act type not url';
+    }
+    if (! ['chromium', 'webkit', 'firefox'].includes(acts[0].which)) {
+      return 'Bad first act which';
+    }
+    if (! acts[1].which || typeof acts[1].which !== 'string' || ! isURL(acts[1].which)) {
+      return 'Second act which not a URL';
+    }
+    if (acts.some(act => ! isValidAct(act))) {
+      return 'Not all acts valid';
+    }
+    if (! sources || typeof sources !== 'object') {
+      return 'Bad report sources';
+    }
+    if (typeof sources.script !== 'string') {
+      return 'Bad sources script';
+    }
+    if (
+      ! creationTime
+      || typeof creationTime !== 'string'
+      || ! /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(creationTime)
+    ) {
+      return 'bad job creation time';
+    }
+    if (! timeStamp || typeof timeStamp !== 'string') {
+      return 'bad report timestamp';
+    }
+    return '';
   }
   else {
-    return false;
+    return 'no report';
   }
 };
 
@@ -295,7 +300,7 @@ const browserClose = async () => {
 const errorStart = error => error.message.replace(/\n.+/s, '');
 // Launches a browser.
 const launch = async (report, typeName, lowMotion = false) => {
-  const browserType = require('playwright')[typeName];
+  const browserType = playwright[typeName];
   // If the specified browser type exists:
   if (browserType) {
     // Close the current browser, if any.
@@ -604,6 +609,18 @@ const goTo = async (report, page, url, timeout, waitUntil, isStrict) => {
 };
 // Recursively performs the acts in a report.
 const doActs = async (report, actIndex, page) => {
+  // Quits and reports the performance being aborted.
+  const abortActs = async () => {
+    // Add data on the aborted act to the report.
+    report.jobData.abortTime = nowString();
+    report.jobData.abortedAct = actIndex;
+    // Prevent performance of additional acts.
+    actIndex = -2;
+    // Report this.
+    console.log('ERROR: Job aborted');
+    // Stop the action until the user resumes it.
+    await page.pause();
+  };
   process.on('message', message => {
     if (message === 'interrupt') {
       console.log('ERROR: Terminal interrupted doActs');
@@ -611,18 +628,18 @@ const doActs = async (report, actIndex, page) => {
     }
   });
   const {acts} = report;
-  // If any more commands are to be performed:
+  // If any more acts are to be performed:
   if (actIndex > -1 && actIndex < acts.length) {
-    // Identify the command to be performed.
+    // Identify the act to be performed.
     const act = acts[actIndex];
     // If it is valid:
-    if (isValidCommand(act)) {
+    if (isValidAct(act)) {
       const whichSuffix = act.which ? ` (${act.which})` : '';
       console.log(`>>>> ${act.type}${whichSuffix}`);
-      // Increment the count of commands performed.
+      // Increment the count of acts performed.
       actCount++;
       act.startTime = Date.now();
-      // If the command is an index changer:
+      // If the act is an index changer:
       if (act.type === 'next') {
         const condition = act.if;
         const logSuffix = condition.length === 3 ? ` ${condition[1]} ${condition[2]}` : '';
@@ -641,9 +658,9 @@ const doActs = async (report, actIndex, page) => {
         };
         // If the condition is true:
         if (truth[1]) {
-          // If the performance of commands is to stop:
+          // If the performance of acts is to stop:
           if (act.jump === 0) {
-            // Stop.
+            // Quit.
             actIndex = -2;
           }
           // Otherwise, if there is a numerical jump:
@@ -651,14 +668,14 @@ const doActs = async (report, actIndex, page) => {
             // Set the act index accordingly.
             actIndex += act.jump - 1;
           }
-          // Otherwise, if there is a named next command:
+          // Otherwise, if there is a named next act:
           else if (act.next) {
             // Set the new index accordingly, or stop if it does not exist.
             actIndex = acts.map(act => act.name).indexOf(act.next) - 1;
           }
         }
       }
-      // Otherwise, if the command is a launch:
+      // Otherwise, if the act is a launch:
       else if (act.type === 'launch') {
         // Launch the specified browser, creating a browser context and a page in it.
         await launch(report, act.which, act.lowMotion ? 'reduce' : 'no-preference');
@@ -667,13 +684,13 @@ const doActs = async (report, actIndex, page) => {
       }
       // Otherwise, if a current page exists:
       else if (page) {
-        // If the command is a url:
+        // If the act is a url:
         if (act.type === 'url') {
           // Identify the URL.
           const resolved = act.which.replace('__dirname', __dirname);
           requestedURL = resolved;
           // Visit it and wait until the network is idle.
-          const {strict} = report.job;
+          const {strict} = report;
           let response = await goTo(report, page, requestedURL, 15000, 'networkidle', strict);
           // If the visit fails:
           if (response.error) {
@@ -712,23 +729,17 @@ const doActs = async (report, actIndex, page) => {
           }
           // If none of the visits succeeded:
           if (response.error) {
-            // Report this.
-            report.jobData.aborted = true;
-            report.jobData.abortedAct = actIndex;
+            // Report this and quit.
             addError(act, 'failure', 'ERROR: Visits failed');
-            // Quit.
-            actIndex = -2;
+            await abortActs();
           }
           // Otherwise, i.e. if the last visit attempt succeeded:
           else {
             // If a prohibited redirection occurred:
             if (response.exception === 'badRedirection') {
-              // Report this.
-              report.jobData.aborted = true;
-              report.jobData.abortedAct = actIndex;
+              // Report this and quit.
               addError(act, 'badRedirection', 'ERROR: Navigation illicitly redirected');
-              // Quit.
-              actIndex = -2;
+              await abortActs();
             }
             // Add the resulting URL to the act.
             if (! act.result) {
@@ -744,20 +755,22 @@ const doActs = async (report, actIndex, page) => {
           const result = act.result = {};
           // If the text is to be the URL:
           if (what === 'url') {
-            // Wait for the URL to be the exact text and quit on failure.
+            // Wait for the URL to be the exact text.
             try {
               await page.waitForURL(which, {timeout: 15000});
               result.found = true;
               result.url = page.url();
             }
+            // If the wait times out:
             catch(error) {
-              actIndex = -2;
+              // Quit.
+              await abortActs();
               waitError(page, act, error, 'text in the URL');
             }
           }
           // Otherwise, if the text is to be a substring of the page title:
           else if (what === 'title') {
-            // Wait for the page title to include the text, case-insensitively, and quit on failure.
+            // Wait for the page title to include the text, case-insensitively.
             try {
               await page.waitForFunction(
                 text => document
@@ -772,14 +785,16 @@ const doActs = async (report, actIndex, page) => {
               result.found = true;
               result.title = await page.title();
             }
+            // If the wait times out:
             catch(error) {
-              actIndex = -2;
+              // Quit.
+              await abortActs();
               waitError(page, act, error, 'text in the title');
             }
           }
           // Otherwise, if the text is to be a substring of the text of the page body:
           else if (what === 'body') {
-            // Wait for the body to include the text, case-insensitively, and quit on failure.
+            // Wait for the body to include the text, case-insensitively.
             try {
               await page.waitForFunction(
                 text => document
@@ -793,25 +808,31 @@ const doActs = async (report, actIndex, page) => {
               );
               result.found = true;
             }
+            // If the wait times out:
             catch(error) {
-              actIndex = -2;
+              // Quit.
+              await abortActs();
               waitError(page, act, error, 'text in the body');
             }
           }
         }
         // Otherwise, if the act is a wait for a state:
         else if (act.type === 'state') {
-          // Wait for it and quit on failure.
+          // Wait for it.
           const stateIndex = ['loaded', 'idle'].indexOf(act.which);
           await page.waitForLoadState(
             ['domcontentloaded', 'networkidle'][stateIndex], {timeout: [10000, 15000][stateIndex]}
           )
-          .catch(error => {
+          // If the wait times out:
+          .catch(async error => {
+            // Quit.
             console.log(`ERROR waiting for page to be ${act.which} (${error.message})`);
             addError(act, 'timeout', `ERROR waiting for page to be ${act.which}`);
-            actIndex = -2;
+            await abortActs();
           });
+          // If the wait succeeded:
           if (actIndex > -2) {
+            // Add state data to the report.
             act.result = {
               success: true,
               state: act.which
@@ -833,8 +854,10 @@ const doActs = async (report, actIndex, page) => {
         // Otherwise, if the page has a URL:
         else if (page.url() && page.url() !== 'about:blank') {
           const url = page.url();
-          // If redirection is permitted or did not occur:
-          if (! report.strict || deSlash(url) === deSlash(requestedURL)) {
+          // If redirection is inapplicable, is permitted, or did not occur:
+          if (
+            url.startsWith('file:') || ! report.strict || deSlash(url) === deSlash(requestedURL)
+          ) {
             // Add the URL to the act.
             act.url = url;
             // If the act is a revelation:
@@ -965,7 +988,7 @@ const doActs = async (report, actIndex, page) => {
               // Initialize the arguments.
               const args = [act.which === 'tenon' ? tenonData : page];
               // Identify the additional validator of the test.
-              const testValidator = commands.tests[act.which];
+              const testValidator = actSpecs.tests[act.which];
               // If it exists:
               if (testValidator) {
                 // Identify its argument properties.
@@ -1085,8 +1108,9 @@ const doActs = async (report, actIndex, page) => {
               // If a match was found:
               if (act.result.found) {
                 // FUNCTION DEFINITION START
-                // Perform a click or Enter keypress and wait for the network to be idle.
+                // Performs a click or Enter keypress and waits for the network to be idle.
                 const doAndWait = async isClick => {
+                  // Perform and report the move.
                   const move = isClick ? 'click' : 'Enter keypress';
                   try {
                     await isClick
@@ -1095,12 +1119,14 @@ const doActs = async (report, actIndex, page) => {
                     act.result.success = true;
                     act.result.move = move;
                   }
+                  // If the move fails:
                   catch(error) {
+                    // Quit and add failure data to the report.
                     act.result.success = false;
                     act.result.error = 'moveFailure';
                     act.result.message = `ERROR: ${move} failed`;
                     console.log(`ERROR: ${move} failed (${errorStart(error)})`);
-                    actIndex = -2;
+                    await abortActs();
                   }
                   if (act.result.success) {
                     try {
@@ -1186,15 +1212,16 @@ const doActs = async (report, actIndex, page) => {
                     }
                     // If the click or load failed:
                     catch(error) {
-                      // Quit and report the failure.
+                      // Quit and add failure data to the report.
                       console.log(`ERROR clicking link (${errorStart(error)})`);
                       act.result.success = false;
                       act.result.error = 'unclickable';
                       act.result.message = 'ERROR: click or load timed out';
-                      actIndex = -2;
+                      await abortActs();
                     }
                     // If the link click succeeded:
                     if (! act.result.error) {
+                      // Add success data to the report.
                       act.result.success = true;
                       act.result.move = 'clicked';
                     }
@@ -1223,7 +1250,7 @@ const doActs = async (report, actIndex, page) => {
                   act.result.move = 'selected';
                   act.result.option = optionText;
                 }
-                // Otherwise, if it is entering text on a text- or search-input element:
+                // Otherwise, if it is entering text in an input element:
                 else if (['text', 'search'].includes(act.type)) {
                   act.result.attributes = {};
                   const {attributes} = act.result;
@@ -1263,12 +1290,12 @@ const doActs = async (report, actIndex, page) => {
               }
               // Otherwise, i.e. if no match was found:
               else {
-                // Stop.
+                // Quit and add failure data to the report.
                 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;
+                await abortActs();
               }
             }
             // Otherwise, if the act is a keypress:
@@ -1436,7 +1463,7 @@ const doActs = async (report, actIndex, page) => {
             // Otherwise, i.e. if the act type is unknown:
             else {
               // Add the error result to the act.
-              addError(act, 'badType', 'ERROR: Invalid command type');
+              addError(act, 'badType', 'ERROR: Invalid act type');
             }
           }
           // Otherwise, i.e. if redirection is prohibited but occurred:
@@ -1458,85 +1485,37 @@ const doActs = async (report, actIndex, page) => {
       }
       act.endTime = Date.now();
     }
-    // Otherwise, i.e. if the command is invalid:
+    // Otherwise, i.e. if the act is invalid:
     else {
-      // Add an error result to the act.
-      const errorMsg = `ERROR: Invalid command of type ${act.type}`;
+      // Quit and add error data to the report.
+      const errorMsg = `ERROR: Invalid act of type ${act.type}`;
       console.log(errorMsg);
-      addError(act, 'badCommand', errorMsg);
-      // Quit.
-      actIndex = -2;
+      addError(act, 'badAct', errorMsg);
+      await abortActs();
     }
-    // Perform the remaining acts unless the performance of acts has been aborted.
+    // Perform any remaining acts if not aborted.
     await doActs(report, actIndex + 1, page);
   }
-  else {
-    console.log('No more acts to perform; closing the browser');
+  // Otherwise, if all acts have been performed and the job succeeded:
+  else if (! report.jobData.abortTime) {
+    console.log('Acts completed');
     await browserClose();
     console.log('Browser closed');
   }
 };
-// Injects launch and url acts into a report where necessary to undo DOM changes.
-const injectLaunches = acts => {
-  let injectMore = true;
-  while (injectMore) {
-    const injectIndex = acts.findIndex((act, index) =>
-      index < acts.length - 1
-      && act.type === 'test'
-      && acts[index + 1].type === 'test'
-      && domChangers.has(act.which)
-    );
-    if (injectIndex === -1) {
-      injectMore = false;
-    }
-    else {
-      const lastBrowserType = acts.reduce((browserType, act, index) => {
-        if (act.type === 'launch' && index < injectIndex) {
-          return act.which;
-        }
-        else {
-          return browserType;
-        }
-      }, '');
-      const lastURL = acts.reduce((url, act, index) => {
-        if (act.type === 'url' && index < injectIndex) {
-          return act.which;
-        }
-        else {
-          return url;
-        }
-      }, '');
-      acts.splice(
-        injectIndex + 1,
-        0,
-        {
-          type: 'launch',
-          which: lastBrowserType,
-          what: `${lastBrowserType} browser`
-        },
-        {
-          type: 'url',
-          which: lastURL,
-          what: 'URL'
-        }
-      );
-    }
-  }
-};
-// Runs a job and adds the results to the report of the job.
+/*
+  Returns whether an initialized job report is valid and, if so, runs the job and adds the results
+  to the report.
+*/
 exports.doJob = async report => {
   // If the report is valid:
-  if(isValidReport(report)) {
-    // Add the job commands to the report as its initial acts.
-    report.acts = JSON.parse(JSON.stringify(report.job.commands));
-    /*
-      Inject launch and url acts where necessary to undo DOM changes, if specified.
-      Injection of url acts alone does not guarantee test independence.
-    */
-    if (urlInject === 'yes') {
-      injectLaunches(report.acts);
-    }
+  const reportInvalidity = isValidReport(report);
+  if (reportInvalidity) {
+    console.log(reportInvalidity);
+  }
+  else {
     // Add initialized job data to the report.
+    report.jobData = {};
     const startTime = new Date();
     report.jobData.startTime = nowString();
     report.jobData.endTime = '';
@@ -1554,16 +1533,11 @@ exports.doJob = async report => {
     report.jobData.presses = 0;
     report.jobData.amountRead = 0;
     report.jobData.testTimes = [];
-    // Recursively perform the specified acts.
+    // Recursively perform the acts and get any page if debugging is on and a job was aborted.
     await doActs(report, 0, null);
     // Add the end time and duration to the report.
     const endTime = new Date();
     report.jobData.endTime = nowString();
     report.jobData.elapsedSeconds =  Math.floor((endTime - startTime) / 1000);
-    return true;
-  }
-  else {
-    console.log('ERROR: Initialized job report invalid');
-    return false;
   }
 };

package/samples/00000-ts18-example.json

@@ -11,7 +11,7 @@
     },
     {
       "type": "url",
-      "which": "https://example.com",
+      "which": "https://example.edu",
       "what": "Example.com",
       "id": "example"
     },
@@ -36,7 +36,7 @@
     },
     {
       "type": "url",
-      "which": "https://example.com",
+      "which": "https://example.edu",
       "what": "Example.com",
       "id": "example"
     },
@@ -221,7 +221,7 @@
     "batch": "",
     "host": {
       "id": "example",
-      "which": "https://example.com",
+      "which": "https://example.edu",
       "what": "Example.com"
     },
     "requester": "user@domain.tld"