@a11y-oracle/cypress-plugin 1.3.0 → 1.3.2

package/README.md

@@ -29,6 +29,8 @@ npm install -D @a11y-oracle/cypress-plugin @a11y-oracle/core-engine cypress
 
 > **Chrome/Chromium only.** The plugin uses CDP, which is only available in Chrome-family browsers.
 
+> **⚠️ Stability Notice — Playwright recommended.** The Cypress plugin is functional but has known stability constraints with large test suites. We recommend using [`@a11y-oracle/playwright-plugin`](../playwright-plugin/README.md) for the most reliable experience. See [Known Limitations](#known-limitations) below for details.
+
 ## Setup
 
 ### 1. Import Commands
@@ -513,6 +515,22 @@ If you need types in your test files without importing the support file:
 /// <reference types="@a11y-oracle/cypress-plugin" />
 ```
 
+## Known Limitations
+
+### CDP Resource Accumulation in Long Test Suites
+
+Cypress runs the application under test (AUT) inside an iframe within its runner page. To interact with the AUT's accessibility tree, the plugin must create an **isolated execution world** in the AUT frame via `Page.createIsolatedWorld` on every `initA11yOracle()` call. Unlike Playwright — which provides native, first-class CDP sessions — Cypress's iframe architecture means these isolated worlds accumulate browser-side resources that Chrome does not fully reclaim, even after `disposeA11yOracle()` cleans up its own references.
+
+**What this means in practice:**
+
+- Test suites with many spec files or many tests per file may experience increasing memory pressure over the course of a run.
+- In v1.3.0 and earlier, this caused a deterministic hang after approximately 16 `init`/`dispose` cycles, because `Accessibility.getFullAXTree` would stall when traversing nodes across all accumulated contexts ([#14](https://github.com/a11y-oracle/a11y-oracle/issues/14)).
+- v1.3.1 mitigated the hang by properly destroying isolated worlds on dispose, but the underlying architectural constraint — that Cypress proxies all CDP calls through its runner and manages frame contexts differently than Playwright — remains.
+
+**Recommendation:** If you are starting a new project or have the flexibility to choose your E2E framework, use [`@a11y-oracle/playwright-plugin`](../playwright-plugin/README.md). Playwright provides direct CDP session access without iframe indirection, making it inherently more stable and performant for A11y-Oracle's CDP-heavy workflow.
+
+If you need to stay on Cypress, the plugin is fully functional — just be aware of these constraints for very large suites.
+
 ## Troubleshooting
 
 ### "Could not find the AUT iframe"

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,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"}
+{"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;AA8UD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,cAAc,CAAC,CAwCvE"}

package/dist/lib/commands.js

@@ -38,14 +38,48 @@ let orchestrator = null;
 let autFrameId = null;
 let autContextId = null;
 let autIframeBounds = null;
+/**
+ * Cached isolated world state for reuse across init/dispose cycles.
+ *
+ * `Page.createIsolatedWorld` accumulates execution contexts that Chrome
+ * never garbage-collects during same-origin navigations. After ~16
+ * iterations the browser hangs on subsequent CDP calls. By caching the
+ * context ID and verifying it with a cheap `Runtime.evaluate` probe we
+ * avoid creating a new world when the previous one is still alive.
+ */
+let _cachedWorldFrameId = null;
+let _cachedWorldContextId = null;
+/** Timeout (ms) applied to every CDP call to surface hangs as errors. */
+const CDP_TIMEOUT_MS = 30_000;
+/**
+ * Wrap a promise with a timeout to prevent indefinite hangs.
+ */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`A11y-Oracle: CDP call "${label}" timed out after ${ms}ms`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 /**
  * Send a raw CDP command through Cypress's automation channel.
+ *
+ * Every call is guarded by a timeout so that accumulated isolated worlds
+ * or other browser-side issues surface as errors instead of silent hangs.
  */
 function sendCDP(command, params = {}) {
-    return Cypress.automation('remote:debugger:protocol', {
+    const raw = Cypress.automation('remote:debugger:protocol', {
         command,
         params,
     });
+    return withTimeout(raw, CDP_TIMEOUT_MS, command);
 }
 /**
  * Create a {@link CDPSessionLike} adapter that routes CDP calls through
@@ -131,6 +165,29 @@ async function findAUTFrameId() {
  * calls execute in the AUT, not the Cypress runner.
  */
 async function findAUTContextId(frameId) {
+    // Try to reuse the context that was handed off by the previous
+    // disposeA11yOracle() call. A lightweight Runtime.evaluate probe
+    // confirms the context is still alive (Chrome destroys isolated worlds
+    // on cross-origin navigation but may preserve them for same-origin).
+    // Always consume (clear) the cache regardless of outcome.
+    const cachedCtx = _cachedWorldContextId;
+    const cachedFrame = _cachedWorldFrameId;
+    _cachedWorldContextId = null;
+    _cachedWorldFrameId = null;
+    if (cachedCtx !== null && cachedFrame === frameId) {
+        try {
+            await sendCDP('Runtime.evaluate', {
+                expression: '1',
+                contextId: cachedCtx,
+                returnByValue: true,
+            });
+            // Context is still valid — reuse it.
+            return cachedCtx;
+        }
+        catch {
+            // Context was destroyed (frame navigated), fall through to create.
+        }
+    }
     try {
         const result = await sendCDP('Page.createIsolatedWorld', {
             frameId,
@@ -476,6 +533,13 @@ Cypress.Commands.add('disposeA11yOracle', () => {
             // Engine was already disabled via orchestrator (same CDP session)
             engine = null;
         }
+        // Hand off the current isolated world to the cache so the next
+        // initA11yOracle() can reuse it instead of leaking a new one.
+        // CDP provides no API to destroy an isolated world; reuse is
+        // the only way to prevent accumulation. The cache is consumed
+        // (cleared) at the start of the next findAUTContextId() call.
+        _cachedWorldContextId = autContextId;
+        _cachedWorldFrameId = autFrameId;
         autFrameId = null;
         autContextId = null;
         autIframeBounds = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-oracle/cypress-plugin",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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.3.0",
-    "@a11y-oracle/keyboard-engine": "1.3.0",
-    "@a11y-oracle/audit-formatter": "1.3.0",
+    "@a11y-oracle/core-engine": "1.3.2",
+    "@a11y-oracle/keyboard-engine": "1.3.2",
+    "@a11y-oracle/audit-formatter": "1.3.2",
     "tslib": "^2.3.0"
   }
 }