@a11y-oracle/cypress-plugin 1.1.4 → 1.3.0

package/README.md

@@ -412,6 +412,30 @@ Node-side function (not a Cypress command). Call inside `setupNodeEvents()` to r
 import { setupOracleReporting } from '@a11y-oracle/cypress-plugin';
 ```
 
+### CDP Adapter
+
+#### `createCypressCDPAdapter()`
+
+Create a ready-to-use `CDPSessionLike` adapter for custom integrations. This is useful when you need to call `@a11y-oracle/axe-bridge`'s `resolveAllIncomplete()` directly instead of using the built-in Cypress commands.
+
+The function encapsulates all the CDP plumbing:
+- Enables `DOM.enable` and `Page.enable` CDP domains
+- Discovers the AUT frame ID from `Page.getFrameTree`
+- Creates an isolated world execution context in the AUT frame
+- Detects iframe position and CSS transform scale
+- Returns a `CDPSessionLike` adapter with scale-aware `Page.captureScreenshot` coordinate translation
+
+```typescript
+import { createCypressCDPAdapter } from '@a11y-oracle/cypress-plugin';
+import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+
+// In your custom Cypress command:
+cy.wrap(null).then(async () => {
+  const cdp = await createCypressCDPAdapter();
+  const resolved = await resolveAllIncomplete(cdp, axeResults, options);
+});
+```
+
 ### Lifecycle
 
 #### `cy.disposeA11yOracle()`
@@ -425,6 +449,7 @@ Types are re-exported from `@a11y-oracle/core-engine` and `@a11y-oracle/audit-fo
 ```typescript
 import type {
   // Core engine types
+  CDPSessionLike,
   SpeechResult,
   A11yState,
   A11yFocusedElement,
@@ -459,7 +484,9 @@ Cypress runs the app under test (AUT) inside an iframe within its runner page. T
 
 3. **Isolated execution context** — For `Runtime.evaluate` calls (focus indicator analysis, tab order, trap detection), the plugin creates an isolated world in the AUT frame via `Page.createIsolatedWorld`. This isolated world shares the same DOM (including `document.activeElement`, computed styles, etc.) but has its own JavaScript scope, ensuring evaluations target the AUT content.
 
-4. **Focus management** — Before each keyboard event, the plugin uses `DOM.focus()` on the AUT iframe element so that `Input.dispatchKeyEvent` reaches the correct frame.
+4. **Screenshot coordinate translation** — `getBoundingClientRect()` inside the AUT iframe returns iframe-relative coordinates, but `Page.captureScreenshot` clips from the top-level browser viewport. The plugin queries the AUT iframe's position in the viewport and offsets all screenshot clip coordinates accordingly. It also detects the CSS transform scale that Cypress applies to the AUT iframe wrapper (typically ~0.66x in headless Electron), and applies it to coordinates, dimensions, and the clip's `scale` property. This ensures pixel-level analysis (color contrast, focus indicator diffing) captures the correct region even when the AUT is rendered at a scaled size.
+
+5. **Focus management** — Before each keyboard event, the plugin uses `DOM.focus()` on the AUT iframe element so that `Input.dispatchKeyEvent` reaches the correct frame.
 
 ### CDP Flow
 

package/dist/index.d.ts

@@ -39,7 +39,8 @@
  * - Cypress >= 12.0.0
  */
 import './lib/commands.js';
-export type { SpeechResult, SpeechEngineOptions, A11yState, A11yFocusedElement, A11yFocusIndicator, A11yOrchestratorOptions, ModifierKeys, TabOrderReport, TabOrderEntry, TraversalResult, FocusIndicator, } from '@a11y-oracle/core-engine';
+export type { CDPSessionLike, SpeechResult, SpeechEngineOptions, A11yState, A11yFocusedElement, A11yFocusIndicator, A11yOrchestratorOptions, ModifierKeys, TabOrderReport, TabOrderEntry, TraversalResult, FocusIndicator, } from '@a11y-oracle/core-engine';
 export type { OracleIssue, OracleNode, OracleCheck, OracleImpact, OracleResultType, AuditContext, } from '@a11y-oracle/audit-formatter';
 export { setupOracleReporting } from './lib/reporting.js';
+export { createCypressCDPAdapter } from './lib/commands.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,mBAAmB,CAAC;AAG3B,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,mBAAmB,CAAC;AAG3B,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -42,3 +42,5 @@
 import './lib/commands.js';
 // Node-side reporting setup
 export { setupOracleReporting } from './lib/reporting.js';
+// Reusable CDP adapter for custom integrations (e.g. axe-bridge resolveAllIncomplete)
+export { createCypressCDPAdapter } from './lib/commands.js';

package/dist/lib/commands.d.ts

@@ -29,7 +29,7 @@
  * cy.disposeA11yOracle();
  * ```
  */
-import type { SpeechResult, A11yState, A11yOrchestratorOptions, TabOrderReport, TraversalResult, ModifierKeys } from '@a11y-oracle/core-engine';
+import type { CDPSessionLike, SpeechResult, A11yState, A11yOrchestratorOptions, TabOrderReport, TraversalResult, ModifierKeys } from '@a11y-oracle/core-engine';
 import type { AuditContext } from '@a11y-oracle/audit-formatter';
 declare global {
     namespace Cypress {
@@ -98,4 +98,28 @@ declare global {
         }
     }
 }
+/**
+ * Create a ready-to-use CDP adapter for the Cypress AUT iframe.
+ *
+ * Encapsulates all the CDP plumbing needed to use
+ * `@a11y-oracle/axe-bridge`'s `resolveAllIncomplete()` in a custom
+ * Cypress command:
+ *
+ * 1. Enables required CDP domains (`DOM.enable`, `Page.enable`)
+ * 2. Discovers the AUT frame ID from `Page.getFrameTree`
+ * 3. Creates an isolated world execution context in the AUT frame
+ * 4. Detects iframe position and CSS transform scale
+ * 5. Returns a `CDPSessionLike` adapter with scale-aware coordinate
+ *    translation for `Page.captureScreenshot`
+ *
+ * @example
+ * ```typescript
+ * import { createCypressCDPAdapter } from '@a11y-oracle/cypress-plugin';
+ * import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+ *
+ * const cdp = await createCypressCDPAdapter();
+ * const resolved = await resolveAllIncomplete(cdp, axeResults, options);
+ * ```
+ */
+export declare function createCypressCDPAdapter(): Promise<CDPSessionLike>;
 //# sourceMappingURL=commands.d.ts.map

package/dist/lib/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/lib/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAEV,YAAY,EACZ,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAIjE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;eAGG;YACH,cAAc,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnE;;;;;eAKG;YACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAE1C,+DAA+D;YAC/D,aAAa,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;YAEnC,2EAA2E;YAC3E,mBAAmB,IAAI,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;YAEtD,0EAA0E;YAC1E,qBAAqB,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;YAEnD;;;;;eAKG;YACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAE1E,0EAA0E;YAC1E,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;YAElC,sDAAsD;YACtD,oBAAoB,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC;YAElD;;;;;eAKG;YACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,eAAe,CAAC,CAAC;YAE9B;;;;;;;;;eASG;YACH,uBAAuB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAE1E;;;;;;;eAOG;YACH,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC9B,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnB;;;eAGG;YACH,iBAAiB,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;SACtC;KACF;CACF"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/lib/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAIjE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;eAGG;YACH,cAAc,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnE;;;;;eAKG;YACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAE1C,+DAA+D;YAC/D,aAAa,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;YAEnC,2EAA2E;YAC3E,mBAAmB,IAAI,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;YAEtD,0EAA0E;YAC1E,qBAAqB,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;YAEnD;;;;;eAKG;YACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAE1E,0EAA0E;YAC1E,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;YAElC,sDAAsD;YACtD,oBAAoB,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC;YAElD;;;;;eAKG;YACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,eAAe,CAAC,CAAC;YAE9B;;;;;;;;;eASG;YACH,uBAAuB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAE1E;;;;;;;eAOG;YACH,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC9B,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnB;;;eAGG;YACH,iBAAiB,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;SACtC;KACF;CACF;AAsQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,cAAc,CAAC,CAwCvE"}

package/dist/lib/commands.js

@@ -74,15 +74,20 @@ function createFrameAwareCDPAdapter() {
             // Runtime.evaluate runs inside the AUT iframe (via contextId), so
             // getBoundingClientRect() returns iframe-relative coords. But
             // Page.captureScreenshot clips relative to the top-level viewport.
+            // Cypress scales the AUT iframe via a CSS transform on a wrapper
+            // element, so we must also apply the display scale factor.
             if (method === 'Page.captureScreenshot' &&
                 p['clip'] &&
                 autIframeBounds &&
-                (autIframeBounds.x !== 0 || autIframeBounds.y !== 0)) {
+                (autIframeBounds.x !== 0 || autIframeBounds.y !== 0 || autIframeBounds.scale !== 1)) {
                 const clip = p['clip'];
+                const s = autIframeBounds.scale;
                 p['clip'] = {
-                    ...clip,
-                    x: clip.x + autIframeBounds.x,
-                    y: clip.y + autIframeBounds.y,
+                    x: autIframeBounds.x + clip.x * s,
+                    y: autIframeBounds.y + clip.y * s,
+                    width: clip.width * s,
+                    height: clip.height * s,
+                    scale: (clip.scale || 1) / s,
                 };
             }
             return sendCDP(method, p);
@@ -139,12 +144,18 @@ async function findAUTContextId(frameId) {
     }
 }
 /**
- * Get the AUT iframe's position in the top-level viewport.
+ * Get the AUT iframe's position and display scale in the top-level viewport.
  *
  * Runs `Runtime.evaluate` in the top-level context (without `contextId`)
  * to find the AUT iframe and return its bounding rect origin. Adds
  * `clientLeft`/`clientTop` to account for any iframe border.
  *
+ * Also computes the display scale by comparing the iframe's rendered width
+ * (`getBoundingClientRect().width`) to its CSS content width (`clientWidth`).
+ * Cypress scales the AUT iframe via a CSS transform on an ancestor wrapper
+ * element (not the iframe itself), so the iframe's own computed transform
+ * is `none`. The empirical width comparison correctly detects the scale.
+ *
  * Used to translate iframe-relative coordinates from
  * `getBoundingClientRect()` to viewport-absolute coordinates for
  * `Page.captureScreenshot` clips.
@@ -157,10 +168,16 @@ async function getAUTIframeBounds() {
         const src = f.getAttribute('src') || f.src || '';
         if (src && !src.includes('/__/') && !src.includes('__cypress') && src !== 'about:blank') {
           const rect = f.getBoundingClientRect();
-          return { x: rect.x + f.clientLeft, y: rect.y + f.clientTop };
+          const contentWidth = f.clientWidth + 2 * f.clientLeft;
+          const scale = contentWidth > 0 ? rect.width / contentWidth : 1;
+          return {
+            x: rect.x + f.clientLeft * scale,
+            y: rect.y + f.clientTop * scale,
+            scale: scale,
+          };
         }
       }
-      return { x: 0, y: 0 };
+      return { x: 0, y: 0, scale: 1 };
     })()`,
         returnByValue: true,
     }));
@@ -244,6 +261,63 @@ async function dispatchKey(key) {
         nativeVirtualKeyCode: keyDef.keyCode,
     });
 }
+// ── Public API ─────────────────────────────────────────────────────
+/**
+ * Create a ready-to-use CDP adapter for the Cypress AUT iframe.
+ *
+ * Encapsulates all the CDP plumbing needed to use
+ * `@a11y-oracle/axe-bridge`'s `resolveAllIncomplete()` in a custom
+ * Cypress command:
+ *
+ * 1. Enables required CDP domains (`DOM.enable`, `Page.enable`)
+ * 2. Discovers the AUT frame ID from `Page.getFrameTree`
+ * 3. Creates an isolated world execution context in the AUT frame
+ * 4. Detects iframe position and CSS transform scale
+ * 5. Returns a `CDPSessionLike` adapter with scale-aware coordinate
+ *    translation for `Page.captureScreenshot`
+ *
+ * @example
+ * ```typescript
+ * import { createCypressCDPAdapter } from '@a11y-oracle/cypress-plugin';
+ * import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+ *
+ * const cdp = await createCypressCDPAdapter();
+ * const resolved = await resolveAllIncomplete(cdp, axeResults, options);
+ * ```
+ */
+export async function createCypressCDPAdapter() {
+    await sendCDP('DOM.enable');
+    await sendCDP('Page.enable');
+    const frameId = await findAUTFrameId();
+    const contextId = frameId ? await findAUTContextId(frameId) : null;
+    const iframeBounds = await getAUTIframeBounds();
+    return {
+        send: (method, params) => {
+            const p = { ...params };
+            if (method === 'Accessibility.getFullAXTree' && frameId) {
+                p['frameId'] = frameId;
+            }
+            if (method === 'Runtime.evaluate' && contextId !== null) {
+                p['contextId'] = contextId;
+            }
+            if (method === 'Page.captureScreenshot' &&
+                p['clip'] &&
+                iframeBounds &&
+                (iframeBounds.x !== 0 || iframeBounds.y !== 0 || iframeBounds.scale !== 1)) {
+                const clip = p['clip'];
+                const s = iframeBounds.scale;
+                p['clip'] = {
+                    x: iframeBounds.x + clip.x * s,
+                    y: iframeBounds.y + clip.y * s,
+                    width: clip.width * s,
+                    height: clip.height * s,
+                    scale: (clip.scale || 1) / s,
+                };
+            }
+            return sendCDP(method, p);
+        },
+    };
+}
 // ── Commands ───────────────────────────────────────────────────────
 Cypress.Commands.add('initA11yOracle', (options) => {
     cy.wrap(null, { log: false }).then(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-oracle/cypress-plugin",
-  "version": "1.1.4",
+  "version": "1.3.0",
   "description": "Cypress custom commands for accessibility speech assertions with iframe-aware CDP routing",
   "license": "MIT",
   "author": "a11y-oracle",
@@ -45,9 +45,9 @@
     "cypress": ">=12.0.0"
   },
   "dependencies": {
-    "@a11y-oracle/core-engine": "1.1.4",
-    "@a11y-oracle/keyboard-engine": "1.1.4",
-    "@a11y-oracle/audit-formatter": "1.1.4",
+    "@a11y-oracle/core-engine": "1.3.0",
+    "@a11y-oracle/keyboard-engine": "1.3.0",
+    "@a11y-oracle/audit-formatter": "1.3.0",
     "tslib": "^2.3.0"
   }
 }