testaro 77.2.0 → 78.0.0

package/README.md

@@ -142,6 +142,7 @@ Here is a sample job, showing properties that you can set:
   strict: true, // Whether to reject redirections from the target URL
   standard: 'only', // Report native (no), standard (only), or both (also) results
   imageColor: 0, // Color type (0, 2, 4, 6) of the page image, if one is to be created along with a catalog
+  imageScale: 2, // Optional: also capture the page image at this device pixel density (see the images section)
   device: { // Device to emulate
     id: 'iPhone 8',
     windowOptions: {
@@ -375,7 +376,9 @@ In some cases no catalog entry can be found. The reasons may include:
 
 #### `images`
 
-Testaro inserts an `images` array property if necessary to store page images in the report. If the job has an `imageColor` property with `0`, `2`, `4`, or `6` as its value and Testaro will insert a `catalog` property, then Testaro also creates a page image with that color type and makes its base64-encoded PNG the first item in the `images` array.
+Testaro inserts an `images` array property if necessary to store page images in the report. If the job has an `imageColor` property with `0`, `2`, `4`, or `6` as its value and Testaro will insert a `catalog` property, then Testaro also creates a page image with that color type and makes its base64-encoded PNG the first item in the `images` array. The first item is always captured at CSS-pixel scale (one image pixel per CSS pixel), so the `motion` test of the `testaro` tool can compare it with its own CSS-pixel screenshot.
+
+If the job also has an `imageScale` property with a number greater than 1 as its value, then the catalog page is rendered at that device scale factor, and Testaro captures a second page image at device-pixel scale and makes it the second item in the `images` array. That image has `imageScale` times the pixels of the CSS layout in each dimension, for crisp display on high-resolution screens. The `boxID` properties of the catalog remain in CSS pixels; consumers can map them onto the second image by multiplying the coordinates by `imageScale`. Fractional values (such as a device's native `2.625`) are valid. A natural choice is the emulated device's own `deviceScaleFactor`, which also makes the catalog page select the same `srcset`/`image-set` resources as the test pages. If `imageScale` is omitted, `1`, or invalid, the behavior is identical to that before this property existed.
 
 There is a `shoot` act type that can be used to make additional page images during a job.
 

package/package.json

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

package/procs/catalog.js

@@ -33,6 +33,16 @@ const {shoot} = require('./shoot');
 exports.getCatalog = async report => {
   const {browserID} = report;
   const targetURL = report.target?.url;
+  // Image scale factor (report.imageScale). When greater than 1, the catalog context
+  // runs at that deviceScaleFactor and a supplemental page image is captured at device
+  // scale, i.e. with imageScale times the pixels of the CSS layout. Box IDs are
+  // CSS-pixel regardless, because getBoundingClientRect reports CSS pixels by
+  // definition; consumers map them onto the supplemental image by multiplying by
+  // imageScale. Omitted, 1, or invalid values keep the behavior identical to before
+  // this option existed.
+  const imageScale = Number.isFinite(report.imageScale) && report.imageScale > 1
+    ? report.imageScale
+    : 1;
   // If the report specifies a global browser ID and a global target URL:
   if (browserID && targetURL) {
     // Launch a browser and visit the target, or abort the job on failure.
@@ -40,7 +50,8 @@ exports.getCatalog = async report => {
       report,
       actIndex: null,
       tempBrowserID: browserID,
-      tempURL: targetURL
+      tempURL: targetURL,
+      contextOverrides: imageScale > 1 ? {deviceScaleFactor: imageScale} : {}
     });
     // If the launch and navigation succeeded:
     if (page) {
@@ -58,13 +69,27 @@ exports.getCatalog = async report => {
       });
       // If a page image is required:
       if ([0, 2, 4, 6].includes(report.imageColor)) {
-        // Create one and add it to the report.
+        // Create one at CSS-pixel scale and add it to the report as images[0]. This
+        // scale is invariant to imageScale and to the context's deviceScaleFactor, so
+        // the testaro motion rule, which compares its own CSS-scale screenshot with
+        // images[0], is unaffected by the imageScale option.
         console.log('Creating page image');
         await shoot(page, report, {
           exclusionSelector: '',
           colorType: report.imageColor,
           action: 'report'
         });
+        // If a supersampled page image is also required:
+        if (imageScale > 1) {
+          // Create one at device-pixel scale and add it to the report as images[1].
+          console.log(`Creating page image at ${imageScale}x device scale`);
+          await shoot(page, report, {
+            exclusionSelector: '',
+            colorType: report.imageColor,
+            action: 'report',
+            scale: 'device'
+          });
+        }
       }
       // Get a catalog of the elements in the page and a map of path IDs to catalog indexes.
       console.log('Creating catalog');
@@ -114,7 +139,14 @@ exports.getCatalog = async report => {
             texts[text] ??= [];
             texts[text].push(index);
           }
-          const domRect = element.getBoundingClientRect();
+          // Get its bounding box, but only if the element is painted. Chromium reports
+          // plausible nonzero boxes for laid-out but unpainted content (visibility: hidden
+          // and content-visibility: hidden subtrees), and such a box disagrees with the
+          // page image, overlapping unrelated visible elements.
+          const isVisible = typeof element.checkVisibility === 'function'
+          ? element.checkVisibility({checkVisibilityCSS: true, visibilityProperty: true})
+          : true;
+          const domRect = isVisible ? element.getBoundingClientRect() : null;
           // Get its box ID.
           const boxID = domRect
           ? ['x', 'y', 'width', 'height'].map(key => Math.round(domRect[key])).join(':')

package/procs/launch.js

@@ -281,7 +281,10 @@ const launchOnce = async opts => {
     tempURL = '',
     headEmulation = 'high',// low, high
     xPathNeed = 'script',// own, script, attribute, none
-    needsAccessibleName = false
+    needsAccessibleName = false,
+    // Extra Playwright context options (e.g. deviceScaleFactor for device-pixel page
+    // images), spread last so they win over the defaults.
+    contextOverrides = {}
   } = opts;
   const act = report.acts[actIndex] ?? {};
   const {device} = report;
@@ -373,7 +376,9 @@ const launchOnce = async opts => {
           'Accept-Encoding': 'gzip, deflate, br',
           'DNT': '1',
           'Upgrade-Insecure-Requests': '1'
-        }
+        },
+        // Caller-specified context options (see contextOverrides above).
+        ...contextOverrides
       };
       browserContext = await browser.newContext(contextOptions);
       // Prevent default timeouts.
@@ -599,7 +604,9 @@ exports.launch = async (opts = {}) => {
     headEmulation = 'high',
     xPathNeed = 'script',
     needsAccessibleName = false,
-    retries = 2
+    retries = 2,
+    // Extra Playwright context options, passed through to launchOnce.
+    contextOverrides = {}
   } = opts;
   // If the report is valid:
   const jobValidation = isValidJob(report);
@@ -615,7 +622,8 @@ exports.launch = async (opts = {}) => {
         tempURL,
         headEmulation,
         xPathNeed,
-        needsAccessibleName
+        needsAccessibleName,
+        contextOverrides
       }
     );
     // If the launch and navigation succeeded:
@@ -657,7 +665,8 @@ exports.launch = async (opts = {}) => {
             tempURL,
             headEmulation,
             xPathNeed,
-            needsAccessibleName
+            needsAccessibleName,
+            contextOverrides
           }
         );
         // If the launch and navigation succeeded:

package/procs/shoot.js

@@ -26,10 +26,13 @@ const randomFileName = (suffixLength = 3) => {
   return fileName;
 };
 // Creates and returns a screenshot.
-const screenShot = async (page, exclusionLocator = null) => {
+const screenShot = async (page, exclusionLocator = null, scale = 'css') => {
   const options = {
     fullPage: true,
-    scale: 'css',
+    // 'css' renders 1 image pixel per CSS pixel; 'device' renders at the context's
+    // deviceScaleFactor, i.e. an image whose pixel coordinates are the CSS
+    // coordinates multiplied by that factor.
+    scale,
     timeout: applyMultiplier(4000)
   };
   if (exclusionLocator) {
@@ -49,10 +52,12 @@ exports.shoot = async (page, report, {
   // Color fidelity: 0 (grayscale), 2 (RGB), 4 (grayscale alpha), 6 (RGBA).
   colorType = 0,
   // Disposition: return, report, file.
-  action = 'return'
+  action = 'return',
+  // Screenshot scale ('css' or 'device'); see screenShot above.
+  scale = 'css'
 } = {}) => {
   // Make and get a screenshot as a buffer.
-  let shot = await screenShot(page, exclusionSelector ? page.locator(exclusionSelector) : null);
+  let shot = await screenShot(page, exclusionSelector ? page.locator(exclusionSelector) : null, scale);
   // If it succeeded:
   if (shot.length) {
     // Get the screenshot as an object representation of a PNG image.