@delacour/warden-e2e 0.12.1 → 0.14.0

package/index.mjs

@@ -3,21 +3,25 @@ import {
   E2eError2,
   a11yTargetOf,
   canObserve,
+  isOnScreen,
   fieldValue,
   normalizeText,
   matchesText,
   renderSnapshot,
   renderHeader,
-  resolve,
   isLocator,
   pickOne,
   textOf,
   formatNativeTail,
   captureNativeLog,
+  bridgeStallFromSpan,
+  formatBridgeStall,
   isRecoverableLoss,
+  parseDuration,
   runStep,
   attemptSession,
   getSession,
+  peekSession,
   accessibleName,
   announce,
   failing,
@@ -42,7 +46,7 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-rbbn127e.mjs";
+} from "./chunk-zk3wxa70.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
@@ -146,6 +150,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" };
 }
@@ -203,7 +216,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 = {}) {
@@ -212,7 +229,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 = {}) {
@@ -227,6 +248,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);
   }
@@ -242,6 +269,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);
   }
@@ -377,7 +410,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) {
@@ -405,11 +439,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 };
@@ -424,8 +459,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 = [
@@ -572,6 +634,116 @@ function createExpect(deps) {
   return call;
 }
 var expect = createExpect({ softSink: currentSoftSink });
+// ../../packages/e2e/src/run.ts
+var DEFAULT_TIMEOUT_MS = 60000;
+var MESSAGE_TAIL = 2000;
+var invalid = (message) => new E2eError2("INVALID_ARGUMENT", `run: ${message}`);
+function timeoutMs(value) {
+  if (value === undefined)
+    return DEFAULT_TIMEOUT_MS;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0)
+      throw invalid(`timeout must be over 0, got ${String(value)}`);
+    return value;
+  }
+  const parsed = parseDuration(value);
+  if (!parsed.success)
+    throw invalid(`timeout: ${parsed.error}`);
+  return parsed.data;
+}
+function argvOf(command) {
+  if (typeof command === "string") {
+    if (command.trim() === "")
+      throw invalid("command is empty");
+    return ["sh", "-c", command];
+  }
+  if (command.length === 0 || command[0] === "")
+    throw invalid("argv is empty");
+  return [...command];
+}
+var programOf = (command) => typeof command === "string" ? "sh -c" : command[0] ?? "";
+function envOf(extra) {
+  const merged = { ...process.env, ...extra };
+  const env = {};
+  for (const [key, value] of Object.entries(merged))
+    if (value !== undefined)
+      env[key] = value;
+  return env;
+}
+function tail(text) {
+  const trimmed = text.trim();
+  return trimmed.length > MESSAGE_TAIL ? `\u2026${trimmed.slice(-MESSAGE_TAIL)}` : trimmed;
+}
+function resultOf(exitCode, stdout, stderr, ms) {
+  return {
+    ok: exitCode === 0,
+    exitCode,
+    stdout,
+    stderr,
+    ms,
+    json() {
+      try {
+        return JSON.parse(stdout);
+      } catch {
+        throw invalid(`stdout is not JSON: ${tail(stdout).slice(0, 200) || "(empty)"}`);
+      }
+    }
+  };
+}
+async function exec(command, options) {
+  const argv = argvOf(command);
+  const limit = timeoutMs(options.timeout);
+  const started = Date.now();
+  let proc;
+  try {
+    proc = Bun.spawn(argv, {
+      cwd: options.cwd,
+      env: envOf(options.env),
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new E2eError2("RUN_FAILED", `run: could not start ${programOf(command)}: ${reason}`);
+  }
+  if (options.input !== undefined)
+    proc.stdin.write(options.input);
+  await proc.stdin.end();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill("SIGKILL");
+  }, limit);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    const result = resultOf(exitCode, stdout, stderr, Date.now() - started);
+    if (timedOut) {
+      throw new E2eError2("TIMEOUT", `run: ${programOf(command)} did not finish within ${limit} ms (killed)`);
+    }
+    if (!result.ok && options.check !== false) {
+      const output = tail(stderr) || tail(stdout);
+      throw new E2eError2("RUN_FAILED", `run: ${programOf(command)} failed with exit ${exitCode}${output === "" ? "" : `
+${output}`}`);
+    }
+    return result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function createRun(deps) {
+  return (command, options = {}) => deps.span("run", () => exec(command, options), {
+    verdict: (result) => result.ok ? { ok: true } : { ok: false, code: "RUN_FAILED" },
+    detail: (result) => ({ exitCode: result.exitCode })
+  });
+}
+var run = createRun({
+  span: (op, fn, options) => peekSession()?.span(op, fn, options) ?? fn()
+});
 // ../../packages/e2e/src/runner/test.ts
 import { afterAll as bunAfterAll, beforeAll as bunBeforeAll, describe as bunDescribe, test as bunTest } from "bun:test";
 
@@ -598,6 +770,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";
@@ -670,7 +872,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);
@@ -678,6 +882,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());
@@ -947,8 +1157,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;
@@ -981,7 +1193,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;
@@ -1042,6 +1254,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
   };
 }
@@ -1277,5 +1490,6 @@ export {
   beforeEach,
   describe,
   expect,
+  run,
   test
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.12.1",
+  "version": "0.14.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.12.1"
+    "@delacour/warden": "0.14.0"
   },
   "dependencies": {
     "zod": "^4.4.3"