testaro 42.0.1 → 43.0.2

package/README.md

@@ -132,11 +132,26 @@ Here is an example of a job:
 ```javaScript
 {
   id: '250110T1200-7f-4',
+  what: 'monthly health check',
   strict: true,
   isolate: true,
   standard: 'also',
   observe: false,
-  deviceID: 'Kindle Fire HDX',
+  device: {
+    id: 'iPhone 8',
+    windowOptions: {
+      reducedMotion: 'no-preference',
+      userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/17.4 Mobile/15A372 Safari/604.1',
+      viewport: {
+        width: 375,
+        height: 667
+      },
+      deviceScaleFactor: 2,
+      isMobile: true,
+      hasTouch: true,
+      defaultBrowserType: 'webkit'
+    }
+  },
   browserID: 'webkit',
   lowMotion: false,
   timeLimit: 80,
@@ -176,7 +191,7 @@ Here is an example of a job:
 ```
 
 This job contains three _acts_, telling Testaro to:
-1. Launch a Webkit browser without a reduced-motion setting, open a tab with the properties of a Kindle Fire HDX device, and navigate to `https://abccorp.com/mgmt/realproperty.html`.
+1. Launch a Webkit browser without a reduced-motion setting, open a window with the properties of an iPhone 8 device, create a page (tab), and navigate to `https://abccorp.com/mgmt/realproperty.html`.
 1. Perform the test for the `landmark-complementary-is-top-level` rule of the `axe` tool and report the test result with Axe detail level 2.
 1. Perform the tests for rules `QW-BP25` and `QW-BP26` of the `qualWeb` tool on the existing page.
 
@@ -186,9 +201,8 @@ Job properties:
 - `strict`: `true` or `false`, indicating whether _substantive redirections_ should be treated as failures. These are redirections that do more than add or subtract a final slash.
 - `standard`: `'also'`, `'only'`, or `'no'`, indicating whether rule-violation instances are to be reported in tool-native formats and also in the Testaro standard format, only in the standard format, or only in the tool-native formats.
 - `observe`: `true` or `false`, indicating whether tool and Testaro-rule invocations are to be reported to the server as they occur, so that the server can update a waiting client.
-- `deviceID`: the ID of the device that some browser properties will resemble, unless overridden by a `launch` act. It must be `'default'` or the ID of one of about 125 devices recognized by Playwright, published at `https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json`.
+- `device`: the ID of a device and the properties of each new browser context (window) that will be set for conformity to that device, unless overridden by a `launch` act. It must be `'default'` or the ID of one of [about 125 devices recognized by Playwright](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json).
 - `browserID`: the ID of the browser to be used, unless overridden by a `launch` act. It must be `'chromium'`, `'firefox'`, or `'webkit`'.
-- `lowMotion`: whether the browser is to create tabs with the `reduce-motion` option set to `reduce` instead of `no-preference`.
 - `timeLimit`: the number of seconds allowed for the execution of the job.
 - `creationTimeStamp`: a string in `yymmddThhMM` format, describing when the job was created.
 - `executionTimeStamp`: a string in `yymmddThhMM` format, specifying a date and time before which the job is not to be performed.
@@ -237,7 +251,7 @@ When the texts of multiple elements of the same type will contain the same `whic
 
 #### Navigations
 
-An example of a **navigation** is the act of type `launch` above. The launch configuration is inherited from the `deviceID`, `browserID`, `lowMotion`, and `target` properties of the job, except that the act may override any of those properties.
+An example of a **navigation** is the act of type `launch` in the job example above. That `launch` act has only a `type` property. If you want a particular `launch` act to use a different browser type or to navigate to a different target from the job defaults, the `launch` act can have a `browserID` and/or a `target` property.
 
 If any act alters the page, you can restore the page to its original state for the next act by inserting a new `launch` act (and, if necessary, additional page-specific acts) between them.
 

package/actSpecs.js

@@ -54,10 +54,8 @@ exports.actSpecs = {
     launch: [
       'Launch a Playwright browser',
       {
-        url: [false, 'string', 'isURL', 'initial URL to navigate to'],
-        deviceID: [false, 'string', 'isDeviceID', 'Playwright device ID if not default, e.g. iPhone 6 landscape'],
-        browserID: [false, 'string', 'isBrowserID', 'chromium, firefox, or webkit if not job default'],
-        lowMotion: [false, 'boolean', '', 'set reduced-motion option if true'],
+        target: [false, 'object', '', 'target different from sources.target of the job'],
+        browserID: [false, 'string', 'isBrowserID', 'browser type different from browserID of the job'],
         what: [false, 'string', 'hasLength', 'comment']
       }
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testaro",
-  "version": "42.0.1",
+  "version": "43.0.2",
   "description": "Run 1000 web accessibility tests from 10 tools and get a standardized report",
   "main": "index.js",
   "scripts": {

package/procs/job.js

@@ -29,8 +29,8 @@
 
 // Requirements for acts.
 const {actSpecs} = require('../actSpecs');
-// Module to validate device IDs.
-const {isDeviceID} = require('./device');
+// Data on devices.
+const {devices} = require('playwright');
 // Module to get dates from time stamps.
 const {dateOf} = require('./dateOf');
 
@@ -82,9 +82,6 @@ const hasSubtype = (variable, subtype) => {
     else if (subtype === 'isURL') {
       return isURL(variable);
     }
-    else if (subtype === 'isDeviceID') {
-      return isDeviceID(variable);
-    }
     else if (subtype === 'isBrowserID') {
       return isBrowserID(variable);
     }
@@ -119,7 +116,7 @@ const hasSubtype = (variable, subtype) => {
   }
 };
 // Validates a browser type.
-const isBrowserID = type => ['chromium', 'firefox', 'webkit'].includes(type);
+const isBrowserID = exports.isBrowserID = type => ['chromium', 'firefox', 'webkit'].includes(type);
 // Validates a load state.
 const isState = string => ['loaded', 'idle'].includes(string);
 // Validates a URL.
@@ -179,6 +176,8 @@ const isValidAct = exports.isValidAct = act => {
     return false;
   }
 };
+// Returns whether a device ID is valid.
+const isDeviceID = deviceID => deviceID === 'default' || !! devices[deviceID];
 // Returns blank if a job is valid, or an error message.
 exports.isValidJob = job => {
   // If any job was provided:
@@ -190,9 +189,8 @@ exports.isValidJob = job => {
       isolate,
       standard,
       observe,
-      deviceID,
+      device,
       browserID,
-      lowMotion,
       timeLimit,
       creationTimeStamp,
       executionTimeStamp,
@@ -217,15 +215,12 @@ exports.isValidJob = job => {
     if (typeof observe !== 'boolean') {
       return 'Bad job observe';
     }
-    if (! isDeviceID(deviceID)) {
+    if (device.id !== 'default' && ! devices[device.id]) {
       return 'Bad job deviceID';
     }
-    if (! ['chromium', 'firefox', 'webkit'].includes(browserID)) {
+    if (! isBrowserID(browserID)) {
       return 'Bad job browserID';
     }
-    if (typeof lowMotion !== 'boolean') {
-      return 'Bad job lowMotion';
-    }
     if (typeof timeLimit !== 'number' || timeLimit < 1) {
       return 'Bad job timeLimit';
     }

package/run.js

@@ -30,15 +30,13 @@
 // Module to keep secrets.
 require('dotenv').config();
 // Module to validate jobs.
-const {isValidJob, tools} = require('./procs/job');
+const {isBrowserID, isValidJob, tools} = require('./procs/job');
 // Module to standardize report formats.
 const {standardize} = require('./procs/standardize');
 // Module to identify element bounding boxes.
 const {identify} = require('./procs/identify');
 // Module to send a notice to an observer.
 const {tellServer} = require('./procs/tellServer');
-// Module to get device options.
-const {getDeviceOptions, isDeviceID} = require('./procs/device');
 
 // CONSTANTS
 
@@ -186,16 +184,15 @@ const browserClose = async () => {
   }
 };
 // Launches a browser, navigates to a URL, and returns browser data.
-const launch = async (report, url, debug, waits, deviceID, browserID, lowMotion) => {
-  // Get the default arguments.
-  url ??= report.url;
-  deviceID ??= report.deviceID;
-  browserID ??= report.browserID;
-  lowMotion ??= report.lowMotion;
+const launch = async (report, debug, waits, tempBrowserID, tempTarget) => {
+  const {browserID, device, target} = report;
+  // Get the default arguments if not overridden.
+  browserID ??= browserID;
+  const {url} = (tempTarget || target);
   // If the specified browser type exists:
-  if (! browserID || ['chromium', 'firefox', 'webkit'].includes(browserID)) {
+  if (isBrowserID(browserID)) {
     // Create a browser of the specified or default type.
-    const browserType = require('playwright')[browserID || report.browserID];
+    const browserType = require('playwright')[tempBrowserID || browserID];
     // Close the current browser, if any.
     await browserClose();
     // Define browser options.
@@ -218,122 +215,106 @@ const launch = async (report, url, debug, waits, deviceID, browserID, lowMotion)
         error: 'Browser launch failed'
       };
     });
-    // Get the device options for a new context.
-    const deviceOptions = getDeviceOptions(
-      deviceID || 'default', lowMotion ? 'reduce-motion' : 'no-preference'
-    );
-    // If the device is valid:
-    if (deviceOptions) {
-      // Open a context (i.e. browser tab), with reduced motion if specified.
-      const browserContext = await browser.newContext(deviceOptions);
-      // Prevent default timeouts.
-      browserContext.setDefaultTimeout(0);
-      // When a page (i.e. browser tab) is added to the browser context (i.e. browser window):
-      browserContext.on('page', async page => {
-        // Ensure the report has a jobData property.
-        report.jobData ??= {};
-        report.jobData.logCount ??= 0;
-        report.jobData.logSize ??= 0;
-        report.jobData.errorLogCount ??= 0;
-        report.jobData.browserTabOptions ??= deviceOptions;
-        // Add any error events to the count of logging errors.
-        page.on('crash', () => {
-          report.jobData.errorLogCount++;
-          console.log('Page crashed');
-        });
-        page.on('pageerror', () => {
-          report.jobData.errorLogCount++;
-        });
-        page.on('requestfailed', () => {
-          report.jobData.errorLogCount++;
-        });
-        // If the page emits a message:
-        page.on('console', msg => {
-          const msgText = msg.text();
-          let indentedMsg = '';
-          // If debugging is on:
-          if (debug) {
-            // Log a summary of the message on the console.
-            const parts = [msgText.slice(0, 75)];
-            if (msgText.length > 75) {
-              parts.push(msgText.slice(75, 150));
-              if (msgText.length > 150) {
-                const tail = msgText.slice(150).slice(-150);
-                if (msgText.length > 300) {
-                  parts.push('...');
-                }
-                parts.push(tail.slice(0, 75));
-                if (tail.length > 75) {
-                  parts.push(tail.slice(75));
-                }
+    // Open a context (i.e. browser tab).
+    const browserContext = await browser.newContext(device.windowOptions);
+    // Prevent default timeouts.
+    browserContext.setDefaultTimeout(0);
+    // When a page (i.e. browser tab) is added to the browser context (i.e. browser window):
+    browserContext.on('page', async page => {
+      // Ensure the report has a jobData property.
+      report.jobData ??= {};
+      const {jobData} = report;
+      jobData.logCount ??= 0;
+      jobData.logSize ??= 0;
+      jobData.errorLogCount ??= 0;
+      // Add any error events to the count of logging errors.
+      page.on('crash', () => {
+        jobData.errorLogCount++;
+        console.log('Page crashed');
+      });
+      page.on('pageerror', () => {
+        jobData.errorLogCount++;
+      });
+      page.on('requestfailed', () => {
+        jobData.errorLogCount++;
+      });
+      // If the page emits a message:
+      page.on('console', msg => {
+        const msgText = msg.text();
+        let indentedMsg = '';
+        // If debugging is on:
+        if (debug) {
+          // Log a summary of the message on the console.
+          const parts = [msgText.slice(0, 75)];
+          if (msgText.length > 75) {
+            parts.push(msgText.slice(75, 150));
+            if (msgText.length > 150) {
+              const tail = msgText.slice(150).slice(-150);
+              if (msgText.length > 300) {
+                parts.push('...');
+              }
+              parts.push(tail.slice(0, 75));
+              if (tail.length > 75) {
+                parts.push(tail.slice(75));
               }
             }
-            indentedMsg = parts.map(part => `    | ${part}`).join('\n');
-            console.log(`\n${indentedMsg}`);
-          }
-          // Add statistics on the message to the report.
-          const msgTextLC = msgText.toLowerCase();
-          const msgLength = msgText.length;
-          report.jobData.logCount++;
-          report.jobData.logSize += msgLength;
-          if (errorWords.some(word => msgTextLC.includes(word))) {
-            report.jobData.errorLogCount++;
-            report.jobData.errorLogSize += msgLength;
           }
-          const msgLC = msgText.toLowerCase();
-          if (
-            msgText.includes('403') && (msgLC.includes('status')
-            || msgLC.includes('prohibited'))
-          ) {
-            report.jobData.prohibitedCount++;
-          }
-        });
-      });
-      // Open the first page of the context.
-      const page = await browserContext.newPage();
-      try {
-        // Wait until it is stable.
-        await page.waitForLoadState('domcontentloaded', {timeout: 5000});
-        // Navigate to the specified URL.
-        const navResult = await goTo(report, page, url, 15000, 'domcontentloaded');
-        // If the navigation succeeded:
-        if (navResult.success) {
-          // Update the name of the current browser type and store it in the page.
-          page.browserTypeName = browserID;
-          // Return the response of the target server, the browser context, and the page.
-          return {
-            success: true,
-            response: navResult.response,
-            browserContext,
-            page
-          };
+          indentedMsg = parts.map(part => `    | ${part}`).join('\n');
+          console.log(`\n${indentedMsg}`);
         }
-        // Otherwise, if the navigation failed:
-        else {
-          // Return the error.
-          return {
-            success: false,
-            error: navResult.error
-          };
+        // Add statistics on the message to the report.
+        const msgTextLC = msgText.toLowerCase();
+        const msgLength = msgText.length;
+        jobData.logCount++;
+        jobData.logSize += msgLength;
+        if (errorWords.some(word => msgTextLC.includes(word))) {
+          jobData.errorLogCount++;
+          jobData.errorLogSize += msgLength;
+        }
+        const msgLC = msgText.toLowerCase();
+        if (
+          msgText.includes('403') && (msgLC.includes('status')
+          || msgLC.includes('prohibited'))
+        ) {
+          jobData.prohibitedCount++;
         }
+      });
+    });
+    // Open the first page (tab) of the context (window).
+    const page = await browserContext.newPage();
+    try {
+      // Wait until it is stable.
+      await page.waitForLoadState('domcontentloaded', {timeout: 5000});
+      // Navigate to the specified URL.
+      const navResult = await goTo(report, page, url, 15000, 'domcontentloaded');
+      // If the navigation succeeded:
+      if (navResult.success) {
+        // Update the name of the current browser type and store it in the page.
+        page.browserID = browserID;
+        // Return the response of the target server, the browser context, and the page.
+        return {
+          success: true,
+          response: navResult.response,
+          browserContext,
+          page
+        };
       }
-      // If it fails to become stable after load:
-      catch(error) {
-        // Return this.
-        console.log(`ERROR: Blank page load in new tab timed out (${error.message})`);
+      // Otherwise, if the navigation failed:
+      else {
+        // Return the error.
         return {
           success: false,
-          error: 'Blank page load in new tab timed out'
+          error: navResult.error
         };
       }
     }
-    // Otherwise, i.e. if the device is invalid:
-    else {
+    // If it fails to become stable after load:
+    catch(error) {
       // Return this.
-      console.log(`ERROR: Device ${deviceID} invalid`);
+      console.log(`ERROR: Blank page load in new tab timed out (${error.message})`);
       return {
         success: false,
-        error: `${deviceID} device invalid`
+        error: 'Blank page load in new tab timed out'
       };
     }
   }
@@ -622,12 +603,10 @@ const doActs = async (report, actIndex, page) => {
       // Launch the specified browser on the specified device and navigate to the specified URL.
       const launchResult = await launch(
         report,
-        act.url || report.target.url,
         debug,
         waits,
-        act.deviceID || report.deviceID,
         act.browserID || report.browserID,
-        act.lowMotion || report.lowMotion
+        act.target || report.target
       );
       // If the launch and navigation succeeded:
       if (launchResult && launchResult.success) {

package/testaro/focAll.js

@@ -50,7 +50,7 @@ exports.reporter = async page => {
   */
   let tabFocused = 0;
   let refocused = 0;
-  const keyName = page.browserTypeName === 'webkit' ? 'Alt+Tab' : 'Tab';
+  const keyName = page.browserID === 'webkit' ? 'Alt+Tab' : 'Tab';
   while (refocused < 100 && tabFocused < 2000) {
     await page.keyboard.press(keyName);
     const isNewFocus = await page.evaluate(() => {

package/procs/device.js

@@ -1,59 +0,0 @@
-/*
-  © 2024 CVS Health and/or one of its affiliates. All rights reserved.
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in all
-  copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-  SOFTWARE.
-*/
-
-// device
-
-// IMPORTS
-
-const {devices} = require('playwright');
-
-// FUNCTIONS
-
-// Returns whether a device ID is valid.
-exports.isDeviceID = deviceID => deviceID === 'default' || !! devices[deviceID];
-
-// Returns options for the browser.newContext() function.
-exports.getDeviceOptions = (deviceID, motion) => {
-  const options = {
-    reduceMotion: motion
-  };
-  // If a non-default device was specified:
-  if (deviceID && deviceID !== 'default') {
-    // Get its properties if it exists.
-    const deviceProperties = devices[deviceID];
-    // Return options or report the device as invalid.
-    if (deviceProperties) {
-      return {
-        ... options,
-        ... deviceProperties
-      };
-    }
-    else {
-      return {};
-    }
-  }
-  // Otherwise, i.e. if no non-default device was specified:
-  else {
-    // Return options.
-    return options;
-  }
-};