@delacour/warden-e2e 0.13.0 → 0.15.0

package/index.mjs

@@ -3,17 +3,19 @@ import {
   E2eError2,
   a11yTargetOf,
   canObserve,
+  isOnScreen,
   fieldValue,
   normalizeText,
   matchesText,
   renderSnapshot,
   renderHeader,
-  resolve,
   isLocator,
   pickOne,
   textOf,
   formatNativeTail,
   captureNativeLog,
+  bridgeStallFromSpan,
+  formatBridgeStall,
   isRecoverableLoss,
   parseDuration,
   runStep,
@@ -44,11 +46,12 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-tnr47n9c.mjs";
+} from "./chunk-e3cry5br.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
 // ../../packages/e2e/src/expect/a11y-matchers.ts
+var KEYBOARD_POLL_MS = 100;
 function show(match) {
   return typeof match === "string" ? JSON.stringify(match) : String(match);
 }
@@ -123,6 +126,30 @@ class DeviceAssertions {
       ]);
     });
   }
+  async toHaveKeyboard(options = {}) {
+    for (const key of Object.keys(options)) {
+      if (key !== "timeout")
+        throw new E2eError2("INVALID_ARGUMENT", `toHaveKeyboard does not take "${key}"; it takes timeout`);
+    }
+    checkMillis("toHaveKeyboard", "timeout", options.timeout);
+    const timeoutMs = options.timeout ?? this.target.assertionTimeout();
+    const want = !this.context.negate;
+    return this.run("toHaveKeyboard()", async () => {
+      const deadline = Date.now() + timeoutMs;
+      let visible = await this.target.keyboardVisible();
+      while (visible !== want && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, KEYBOARD_POLL_MS));
+        visible = await this.target.keyboardVisible();
+      }
+      if (visible === want)
+        return;
+      throw await this.failure([
+        `expect(device)${this.context.negate ? ".not" : ""}.toHaveKeyboard()`,
+        `Expected: ${want ? "a keyboard on screen" : "no keyboard on screen"} within ${timeoutMs} ms`,
+        `Received: ${visible ? "a keyboard on screen" : "no keyboard on screen"}`
+      ]);
+    });
+  }
   async failure(lines) {
     const screen = await this.target.a11yScreen();
     const head = lines.join(`
@@ -148,6 +175,15 @@ ${screen}`, screen);
 var NEGATION_GRACE_MS = 1000;
 var NEGATION_QUIET_MS = 250;
 var NOT_FOUND = "element not found";
+var UNKNOWN = "unknown (degraded read)";
+function reactShown(matches, screen) {
+  const [only] = matches;
+  return only !== undefined && only.frame.width > 0 && only.frame.height > 0 && isOnScreen(only.tapPoint, screen);
+}
+function reactText(matches) {
+  const [only] = matches;
+  return only?.text === undefined ? undefined : normalizeText(only.text);
+}
 function missing() {
   return { kind: "missing" };
 }
@@ -205,7 +241,11 @@ class LocatorAssertions {
       call: "toBeVisible()",
       expected: "visible",
       strict: true,
-      judge: (entry) => entry === undefined ? judged(false, "not found") : judged(entry.visible, entry.visible ? "visible" : "hidden")
+      judge: (entry) => entry === undefined ? judged(false, "not found") : judged(entry.visible, entry.visible ? "visible" : "hidden"),
+      judgeReact: (matches, screen) => {
+        const shown = reactShown(matches, screen);
+        return judged(shown, shown ? "visible (React tree)" : "hidden (React tree)");
+      }
     }, options);
   }
   async toBeHidden(options = {}) {
@@ -214,7 +254,11 @@ class LocatorAssertions {
       call: "toBeHidden()",
       expected: "hidden",
       strict: true,
-      judge: (entry) => entry === undefined ? judged(true, "not found") : judged(!entry.visible, entry.visible ? "visible" : "hidden")
+      judge: (entry) => entry === undefined ? judged(true, "not found") : judged(!entry.visible, entry.visible ? "visible" : "hidden"),
+      judgeReact: (matches, screen) => {
+        const shown = reactShown(matches, screen);
+        return judged(!shown, shown ? "visible (React tree)" : "hidden (React tree)");
+      }
     }, options);
   }
   async toHaveText(expected, options = {}) {
@@ -229,6 +273,12 @@ class LocatorAssertions {
           return missing();
         const value = textOf(entry);
         return judged(matchesText(value, expected, { exact }), JSON.stringify(value));
+      },
+      judgeReact: (matches) => {
+        const value = reactText(matches);
+        if (value === undefined)
+          return;
+        return judged(matchesText(value, expected, { exact }), `${JSON.stringify(value)} (React tree)`);
       }
     }, options);
   }
@@ -244,6 +294,12 @@ class LocatorAssertions {
           return missing();
         const value = textOf(entry);
         return judged(containsText(value, expected, ignoreCase), JSON.stringify(value));
+      },
+      judgeReact: (matches) => {
+        const value = reactText(matches);
+        if (value === undefined)
+          return;
+        return judged(containsText(value, expected, ignoreCase), `${JSON.stringify(value)} (React tree)`);
       }
     }, options);
   }
@@ -379,7 +435,8 @@ class LocatorAssertions {
       call: `toHaveCount(${expected})`,
       expected: String(expected),
       strict: false,
-      judge: (_entry, count) => judged(count === expected, String(count))
+      judge: (_entry, count) => judged(count === expected, String(count)),
+      judgeReact: (matches) => judged(matches.length === expected, `${matches.length} (React tree)`)
     }, options);
   }
   async assert(spec, options) {
@@ -407,11 +464,12 @@ class LocatorAssertions {
         return { done: false, state: { received: "(screen unreadable)" } };
       }
       const { observed } = observation;
-      const entries = resolve(this.locator.expr, observed.index);
-      if (spec.strict && entries.length > 1)
-        pickOne(rt, this.locator.expr, entries, observed);
-      const { seen, context } = await judgementContext(spec, observed);
-      const judgement = spec.judge(entries[0], entries.length, context);
+      const look = await this.judgeLook(spec, observed);
+      if (look.kind === "unsettled") {
+        hold.broken();
+        return { done: false, state: look.last };
+      }
+      const { judgement, seen } = look;
       const verdict = await hold.next(judgement.kind === "judged" && judgement.matches !== negate, observed.driver);
       if (verdict === "pass")
         return { done: true, value: true };
@@ -426,8 +484,35 @@ class LocatorAssertions {
     }, timeoutMs);
     if (result.status === "done")
       return;
+    const degraded = result.last?.degraded;
+    if (degraded !== undefined)
+      throw this.locator.degradedFailure(degraded, timeoutMs, result.last?.snapshot);
     throw this.failure(spec, result.last);
   }
+  async judgeLook(spec, observed) {
+    const rt = this.locator.runtime;
+    const resolved = await this.locator.resolveIn(observed);
+    if (resolved.kind === "unknown") {
+      return { kind: "unsettled", last: { received: UNKNOWN, snapshot: observed.snapshot, degraded: resolved.read } };
+    }
+    if (resolved.kind === "react") {
+      const { matches } = resolved;
+      if (spec.strict && matches.length > 1 && spec.judgeReact !== undefined) {
+        const message = `${this.locator} matched ${matches.length} components in the React tree`;
+        throw new E2eError2("LOCATOR_AMBIGUOUS", message, rt.excerpt(observed.snapshot), matches.length);
+      }
+      const judgement = spec.judgeReact?.(matches, observed.snapshot.screen);
+      if (judgement === undefined) {
+        return { kind: "unsettled", last: { received: "only in the React tree", snapshot: observed.snapshot } };
+      }
+      return { kind: "judged", judgement, seen: observed.snapshot };
+    }
+    const { entries } = resolved;
+    if (spec.strict && entries.length > 1)
+      pickOne(rt, this.locator.expr, entries, observed);
+    const { seen, context } = await judgementContext(spec, observed);
+    return { kind: "judged", judgement: spec.judge(entries[0], entries.length, context), seen };
+  }
   failure(spec, last) {
     const { negate } = this.context;
     const lines = [
@@ -710,6 +795,36 @@ function missingRequirements(target, requires) {
 import { readdirSync } from "fs";
 import { join as join2 } from "path";
 
+// ../../packages/e2e/src/runner/bridge-evidence.ts
+function bridgeEvidence() {
+  let fallbacks = 0;
+  let first;
+  let last;
+  return {
+    observe(event) {
+      if (event.type !== "span" || event.detail === undefined)
+        return;
+      const detail = event.detail;
+      const stall = bridgeStallFromSpan(detail);
+      const reason = typeof detail.fallback === "string" ? detail.fallback : undefined;
+      const fellBack = reason !== undefined && detail.backend !== "axbridge";
+      if (stall === undefined && !fellBack)
+        return;
+      const read = {
+        ...fellBack ? { reason } : {},
+        ...event.ok || event.code === undefined ? {} : { code: event.code },
+        ...stall
+      };
+      fallbacks += 1;
+      first ??= read;
+      last = read;
+    },
+    summary() {
+      return first === undefined || last === undefined ? undefined : { fallbacks, first, last };
+    }
+  };
+}
+
 // ../../packages/e2e/src/runner/failure.ts
 import { mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
@@ -782,7 +897,9 @@ async function captureSnapshot(driver, dir, ms, capture) {
     }
     const rendered = renderSnapshot(result.data, { interactiveOnly: false, refs: new Map });
     const header = renderHeader({ snapshot: result.data, rendered, interactiveOnly: false });
-    writeFileSync(join(dir, SCREEN_AT_FAILURE), `${[header, ...rendered.lines].join(`
+    const fellBack = fallbackLine(result.data);
+    const lines = fellBack === undefined ? [header, ...rendered.lines] : [header, fellBack, ...rendered.lines];
+    writeFileSync(join(dir, SCREEN_AT_FAILURE), `${lines.join(`
 `)}
 `);
     capture.files.push(SCREEN_AT_FAILURE);
@@ -790,6 +907,12 @@ async function captureSnapshot(driver, dir, ms, capture) {
     capture.problems.push(`snapshot: ${message(cause)}`);
   }
 }
+function fallbackLine(snapshot) {
+  if (snapshot.fellBackFrom === undefined)
+    return;
+  const head = `# read on ${snapshot.backend}: ${snapshot.fellBackFrom}`;
+  return snapshot.bridgeStall === undefined ? `${head} did not answer` : `${head} stalled (${formatBridgeStall(snapshot.bridgeStall)})`;
+}
 async function captureDevtoolsArtifacts(facet, dir, timeoutMs = CAPTURE_TIMEOUT_MS, budget = unlimited) {
   const capture = { files: [], problems: [] };
   const ms = Math.min(timeoutMs, budget());
@@ -1059,8 +1182,10 @@ async function runAttemptOnce(session, spec) {
   };
   const files = new Set;
   let binding;
+  const bridge = bridgeEvidence();
   const trace = openTrace(join2(dir, "trace.jsonl"), (event) => {
     files.add("trace.jsonl");
+    bridge.observe(event);
     print(formatConsoleLine(event, { clock, short, depth: binding?.context.depth ?? 0 }));
   });
   const controller = new AbortController;
@@ -1093,7 +1218,7 @@ async function runAttemptOnce(session, spec) {
   session.leaveAttempt(ctx);
   trace.flush();
   outcome = failIf(outcome, cleanupErrors.length > 0, () => cleanupErrors[0]);
-  return concludeAttempt(session, spec, ctx, { startedAt, device }, outcome, print, clock);
+  return concludeAttempt(session, spec, ctx, { startedAt, device, bridge: bridge.summary() }, outcome, print, clock);
 }
 async function raceDeadline(controller, timeoutMs, run) {
   let deadlineHit = false;
@@ -1124,15 +1249,19 @@ async function concludeAttempt(session, spec, ctx, run, outcome, print, clock) {
     ctx.files.add(shot);
   const result = buildResult(spec, ctx, run, outcome.failed ? { failed: true, error: outcome.failure, timedOut: outcome.deadlineHit } : { failed: false });
   print(formatConsoleLine({ type: "test-end", result }, { clock }));
-  if (outcome.failed && session.recoverHid !== undefined && isRecoverableLoss(outcome.failure, session.env.deviceKind) && await session.recoverHid()) {
+  if (outcome.failed && await recovered(session, outcome.failure, run.startedAt))
     return "again";
-  }
   if (!outcome.failed || spec.final)
     session.results.append(result);
   if (outcome.failed)
     throw outcome.failure instanceof Error ? outcome.failure : new Error(String(outcome.failure));
   return;
 }
+async function recovered(session, failure, startedAt) {
+  if (session.recoverHid !== undefined && isRecoverableLoss(failure, session.env.deviceKind) && await session.recoverHid())
+    return true;
+  return session.recoverAxWedge !== undefined && await session.recoverAxWedge(Date.now() - startedAt);
+}
 function softFailureError(failures) {
   if (failures.length === 1 && failures[0] !== undefined)
     return failures[0];
@@ -1154,6 +1283,7 @@ function buildResult(spec, ctx, run, outcome) {
     ...spec.only ? { only: true } : {},
     ...outcome.failed ? { error: errorInfo(outcome.error) } : {},
     ...ctx.files.size > 0 ? { artifacts: { dir: ctx.dir, files: [...ctx.files].sort() } } : {},
+    ...run.bridge === undefined ? {} : { bridge: run.bridge },
     device: run.device
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "TypeScript e2e testing for React Native and Expo on iOS simulators and Android emulators, run by `warden e2e`: test, expect, screen, device, app",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@delacour/warden": "0.13.0"
+    "@delacour/warden": "0.15.0"
   },
   "dependencies": {
     "zod": "^4.4.3"