@delacour/warden-e2e 0.6.0 → 0.8.0

package/index.mjs

@@ -1,6 +1,7 @@
 // @bun
 import {
   E2eError2,
+  a11yTargetOf,
   canObserve,
   fieldValue,
   normalizeText,
@@ -11,16 +12,25 @@ import {
   isLocator,
   pickOne,
   textOf,
-  isHidLost,
+  isRecoverableLoss,
   runStep,
   attemptSession,
   getSession,
+  accessibleName,
+  announce,
+  failing,
+  formatIssues,
+  toE2eError,
+  withA11yRead,
+  renderA11yScreen,
+  IOS_DEVICE_CAPABILITIES,
+  callerFile,
+  conditionsOf,
   perfStartFor,
   hash6,
   attemptDir,
   specIdOf,
   captureNativeLog,
-  callerFile,
   BUN_TIMEOUT_MARGIN_MS2,
   ownHook,
   currentScope,
@@ -31,10 +41,106 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-yb1hcjqm.mjs";
+} from "./chunk-vs5npy59.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
+// ../../packages/e2e/src/expect/a11y-matchers.ts
+function show(match) {
+  return typeof match === "string" ? JSON.stringify(match) : String(match);
+}
+function checkMillis(matcher, key, value) {
+  if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) {
+    throw new E2eError2("INVALID_ARGUMENT", `${matcher}: "${key}" must be a non-negative number of milliseconds`);
+  }
+}
+
+class DeviceAssertions {
+  target;
+  context;
+  constructor(target, context) {
+    this.target = target;
+    this.context = context;
+  }
+  get not() {
+    return new DeviceAssertions(this.target, { ...this.context, negate: !this.context.negate });
+  }
+  async toPassA11yAudit(options = {}) {
+    const call = `toPassA11yAudit(${Object.keys(options).length === 0 ? "" : JSON.stringify(options)})`;
+    return this.run(call, async () => {
+      const result = await this.target.audit(options);
+      const min = options.minSeverity ?? "error";
+      const bad = failing(result, min);
+      const passes = bad.length === 0;
+      if (passes !== this.context.negate)
+        return;
+      const table = formatIssues(result, min);
+      const lines = [
+        `expect(device)${this.context.negate ? ".not" : ""}.${call}`,
+        `Expected: ${this.context.negate ? "at least one" : "no"} ${min}${min === "error" ? "" : " or worse"} accessibility issue`,
+        `Received: ${table}`
+      ];
+      throw await this.failure(lines);
+    });
+  }
+  async toHaveAnnounced(expected, options = {}) {
+    for (const key of Object.keys(options)) {
+      if (key !== "timeoutMs" && key !== "timeout" && key !== "since") {
+        throw new E2eError2("INVALID_ARGUMENT", `toHaveAnnounced does not take "${key}"; it takes timeoutMs, since`);
+      }
+    }
+    checkMillis("toHaveAnnounced", "timeoutMs", options.timeoutMs);
+    checkMillis("toHaveAnnounced", "timeout", options.timeout);
+    const timeoutMs = options.timeoutMs ?? options.timeout ?? this.target.assertionTimeout();
+    const call = `toHaveAnnounced(${show(expected)})`;
+    return this.run(call, async () => {
+      const waited = await this.target.waitForAnnouncement(expected, {
+        timeoutMs,
+        ...options.since === undefined ? {} : { since: options.since }
+      });
+      const { negate } = this.context;
+      if (waited.success) {
+        if (!negate)
+          return;
+        throw await this.failure([
+          `expect(device).not.${call}`,
+          `Expected: no announcement matching ${show(expected)}`,
+          `Received: ${JSON.stringify(waited.data.event.text ?? "")}`
+        ]);
+      }
+      if (waited.error.code !== "E_TIMEOUT")
+        throw toE2eError(waited.error, "read announcements");
+      if (negate)
+        return;
+      const seen = waited.error.detail?.seen ?? [];
+      throw await this.failure([
+        `expect(device).${call}`,
+        `Expected: an announcement matching ${show(expected)} within ${timeoutMs} ms`,
+        `Received: ${seen.length === 0 ? "(no announcements)" : seen.map((text) => JSON.stringify(text)).join(", ")}`
+      ]);
+    });
+  }
+  async failure(lines) {
+    const screen = await this.target.a11yScreen();
+    const head = lines.join(`
+`);
+    return new E2eError2("ASSERTION", screen === undefined ? head : `${head}
+
+${screen}`, screen);
+  }
+  async run(call, body) {
+    try {
+      await this.target.step(`expect device.${call}`, body);
+    } catch (error) {
+      if (this.context.soft !== undefined && error instanceof E2eError2 && error.code !== "TIMEOUT") {
+        this.context.soft(error);
+        return;
+      }
+      throw error;
+    }
+  }
+}
+
 // ../../packages/e2e/src/expect/matchers.ts
 var NEGATION_GRACE_MS = 1000;
 var NEGATION_QUIET_MS = 250;
@@ -45,7 +151,7 @@ function missing() {
 function judged(matches, received) {
   return { kind: "judged", matches, received };
 }
-function show(match) {
+function show2(match) {
   return typeof match === "string" ? JSON.stringify(match) : String(match);
 }
 function assertOptions(matcher, options, allowed) {
@@ -112,8 +218,8 @@ class LocatorAssertions {
     assertOptions("toHaveText", options, ["exact", "timeout"]);
     const exact = options.exact ?? true;
     return this.assert({
-      call: `toHaveText(${show(expected)})`,
-      expected: exact ? show(expected) : `${show(expected)} (substring, ignoring case)`,
+      call: `toHaveText(${show2(expected)})`,
+      expected: exact ? show2(expected) : `${show2(expected)} (substring, ignoring case)`,
       strict: true,
       judge: (entry) => {
         if (entry === undefined)
@@ -127,8 +233,8 @@ class LocatorAssertions {
     assertOptions("toContainText", options, ["ignoreCase", "timeout"]);
     const ignoreCase = options.ignoreCase ?? false;
     return this.assert({
-      call: `toContainText(${show(expected)})`,
-      expected: `text containing ${show(expected)}`,
+      call: `toContainText(${show2(expected)})`,
+      expected: `text containing ${show2(expected)}`,
       strict: true,
       judge: (entry) => {
         if (entry === undefined)
@@ -141,8 +247,8 @@ class LocatorAssertions {
   async toHaveValue(expected, options = {}) {
     assertOptions("toHaveValue", options, ["timeout"]);
     return this.assert({
-      call: `toHaveValue(${show(expected)})`,
-      expected: show(expected),
+      call: `toHaveValue(${show2(expected)})`,
+      expected: show2(expected),
       strict: true,
       judge: (entry) => {
         if (entry === undefined)
@@ -189,6 +295,78 @@ class LocatorAssertions {
       judge: (entry) => entry === undefined ? missing() : judged(entry.states.disabled, entry.states.disabled ? "disabled" : "enabled")
     }, options);
   }
+  async toHaveAccessibleName(expected, options = {}) {
+    assertOptions("toHaveAccessibleName", options, ["timeout"]);
+    return this.assert({
+      call: `toHaveAccessibleName(${show2(expected)})`,
+      expected: show2(expected),
+      strict: true,
+      a11y: true,
+      judge: (entry, _count, ctx) => {
+        if (entry === undefined)
+          return missing();
+        const name = accessibleName(ctx.element(entry), ctx.platform) ?? "";
+        return judged(matchesText(name, expected, { exact: true }), JSON.stringify(name));
+      }
+    }, options);
+  }
+  async toHaveRole(expected, options = {}) {
+    assertOptions("toHaveRole", options, ["timeout"]);
+    return this.assert({
+      call: `toHaveRole(${JSON.stringify(expected)})`,
+      expected: JSON.stringify(expected),
+      strict: true,
+      judge: (entry) => entry === undefined ? missing() : judged(entry.role === expected, JSON.stringify(entry.role))
+    }, options);
+  }
+  async toHaveHint(expected, options = {}) {
+    assertOptions("toHaveHint", options, ["timeout"]);
+    return this.assert({
+      call: `toHaveHint(${show2(expected)})`,
+      expected: show2(expected),
+      strict: true,
+      a11y: true,
+      judge: (entry, _count, ctx) => {
+        if (entry === undefined)
+          return missing();
+        const hint = ctx.element(entry).a11y?.hint;
+        if (hint === undefined || hint === "")
+          return judged(false, "(no hint)");
+        return judged(matchesText(hint, expected, { exact: true }), JSON.stringify(hint));
+      }
+    }, options);
+  }
+  async toAnnounce(expected, options = {}) {
+    assertOptions("toAnnounce", options, ["exact", "timeout"]);
+    const exact = options.exact ?? true;
+    return this.assert({
+      call: `toAnnounce(${show2(expected)})`,
+      expected: exact ? show2(expected) : `${show2(expected)} (substring, ignoring case)`,
+      strict: true,
+      a11y: true,
+      judge: (entry, _count, ctx) => {
+        if (entry === undefined)
+          return missing();
+        const text = announce(ctx.element(entry), ctx.platform).text;
+        return judged(matchesText(text, expected, { exact }), JSON.stringify(text));
+      }
+    }, options);
+  }
+  async toBeA11yFocused(options = {}) {
+    assertOptions("toBeA11yFocused", options, ["timeout"]);
+    return this.assert({
+      call: "toBeA11yFocused()",
+      expected: "a11y-focused",
+      strict: true,
+      a11y: true,
+      judge: (entry, _count, ctx) => {
+        if (entry === undefined)
+          return missing();
+        const focused = ctx.element(entry).a11y?.a11yFocused === true;
+        return judged(focused, focused ? "a11y-focused" : "not a11y-focused");
+      }
+    }, options);
+  }
   async toHaveCount(expected, options = {}) {
     assertOptions("toHaveCount", options, ["timeout"]);
     if (!Number.isInteger(expected) || expected < 0) {
@@ -229,7 +407,8 @@ class LocatorAssertions {
       const entries = resolve(this.locator.expr, observed.index);
       if (spec.strict && entries.length > 1)
         pickOne(rt, this.locator.expr, entries, observed);
-      const judgement = spec.judge(entries[0], entries.length);
+      const { seen, context } = await judgementContext(spec, observed);
+      const judgement = spec.judge(entries[0], entries.length, context);
       const verdict = await hold.next(judgement.kind === "judged" && judgement.matches !== negate, observed.driver);
       if (verdict === "pass")
         return { done: true, value: true };
@@ -237,7 +416,7 @@ class LocatorAssertions {
         done: false,
         state: {
           received: judgement.kind === "missing" ? NOT_FOUND : judgement.received,
-          snapshot: observed.snapshot
+          snapshot: seen
         },
         ...verdict.wakeMs === undefined ? {} : { maxWaitMs: verdict.wakeMs }
       };
@@ -253,7 +432,7 @@ class LocatorAssertions {
       `Expected: ${negate ? "not " : ""}${spec.expected}`,
       `Received: ${last?.received ?? NOT_FOUND}`
     ];
-    const screen = last?.snapshot === undefined ? undefined : this.locator.runtime.excerpt(last.snapshot);
+    const screen = last?.snapshot === undefined ? undefined : spec.a11y === true ? renderA11yScreen(last.snapshot) : this.locator.runtime.excerpt(last.snapshot);
     const message = screen === undefined ? lines.join(`
 `) : `${lines.join(`
 `)}
@@ -262,6 +441,19 @@ ${screen}`;
     return new E2eError2("ASSERTION", message, screen);
   }
 }
+async function judgementContext(spec, observed) {
+  let seen = observed.snapshot;
+  if (spec.a11y === true) {
+    const merged = await withA11yRead(observed.driver, observed.snapshot);
+    if (merged.success)
+      seen = merged.data;
+  }
+  const byId = new Map(seen.flat.map((element) => [element.id, element]));
+  return {
+    seen,
+    context: { platform: seen.platform, element: (entry) => byId.get(entry.element.id) ?? entry.element }
+  };
+}
 function conditionHold(negate, holdMs, now) {
   let since;
   let asked = false;
@@ -345,11 +537,22 @@ function softMatchers(target, sink) {
 }
 var NOT_STATIC = new Set(["length", "name", "prototype"]);
 function createExpect(deps) {
-  const call = (actual, message) => isLocator(actual) ? new LocatorAssertions(actual, { negate: false }) : valueExpect(actual, message);
+  const call = (actual, message) => {
+    if (isLocator(actual))
+      return new LocatorAssertions(actual, { negate: false });
+    const target = a11yTargetOf(actual);
+    if (target !== undefined)
+      return new DeviceAssertions(target, { negate: false });
+    return valueExpect(actual, message);
+  };
   const soft = (actual, message) => {
     const sink = deps.softSink();
     if (isLocator(actual))
       return new LocatorAssertions(actual, { negate: false, ...sink === undefined ? {} : { soft: sink } });
+    const target = a11yTargetOf(actual);
+    if (target !== undefined) {
+      return new DeviceAssertions(target, { negate: false, ...sink === undefined ? {} : { soft: sink } });
+    }
     const matchers = valueExpect(actual, message);
     return sink === undefined ? matchers : softMatchers(matchers, sink);
   };
@@ -371,6 +574,25 @@ var expect = createExpect({ softSink: currentSoftSink });
 // ../../packages/e2e/src/runner/test.ts
 import { afterAll as bunAfterAll, beforeAll as bunBeforeAll, describe as bunDescribe, test as bunTest } from "bun:test";
 
+// ../../packages/e2e/src/driver/requirements.ts
+function staticCapabilities(target) {
+  return target.platform === "ios" && target.deviceKind === "physical" ? IOS_DEVICE_CAPABILITIES : undefined;
+}
+var met = (capabilities, requirement) => {
+  switch (requirement) {
+    case "pinch":
+      return capabilities.pinch;
+    case "multiTouch":
+      return capabilities.maxPointers >= 2;
+  }
+};
+function missingRequirements(target, requires) {
+  const capabilities = staticCapabilities(target);
+  if (capabilities === undefined || requires === undefined)
+    return [];
+  return requires.filter((requirement) => !met(capabilities, requirement));
+}
+
 // ../../packages/e2e/src/runner/attempt.ts
 import { readdirSync } from "fs";
 import { join as join2 } from "path";
@@ -789,7 +1011,7 @@ 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 && isHidLost(outcome.failure) && await session.recoverHid()) {
+  if (outcome.failed && session.recoverHid !== undefined && isRecoverableLoss(outcome.failure, session.env.deviceKind) && await session.recoverHid()) {
     return "again";
   }
   if (!outcome.failed || spec.final)
@@ -838,6 +1060,12 @@ async function setUpAndRun(session, spec, use, signal, state, teardowns) {
       }
     });
   }
+  const conditions = conditionsOf(base.device);
+  if (conditions !== undefined) {
+    teardowns.push({ name: "conditions", run: () => conditions.teardown(), when: () => conditions.dirty() });
+    if (conditions.declared)
+      await session.step("conditions", "conditions.baseline", () => conditions.applyBaseline());
+  }
   if (use.launch === "fresh")
     await session.step("app", "app.open", () => base.app.open());
   for (const entry of spec.fixtures) {
@@ -892,6 +1120,8 @@ async function runCleanup(session, spec, ctx, built, teardowns, budget, bind) {
     }
   }
   for (const fixture of [...teardowns].reverse()) {
+    if (fixture.when?.() === false)
+      continue;
     await attempt(`fixture ${fixture.name} teardown`, () => step("fixture", `${fixture.name} teardown`, fixture.run));
   }
   cleanup.abort(new E2eError2("SESSION", "attempt finished"));
@@ -921,6 +1151,7 @@ function registerTest(fixtures, mode, title, second, third) {
   const use = resolveUse(scope, defaults, options.timeout);
   const retry = options.retry ?? 0;
   const wrongPlatform = options.platforms !== undefined && defaults.platform !== undefined && !options.platforms.includes(defaults.platform);
+  const lacking = missingRequirements({ platform: defaults.platform, deviceKind: defaults.deviceKind }, options.requires).length > 0;
   const only = mode === "only" || options.only === true;
   if (only)
     markOnly();
@@ -942,7 +1173,7 @@ function registerTest(fixtures, mode, title, second, third) {
     });
   };
   const bunOptions = { timeout: bunTimeoutMs, retry };
-  if (mode === "skip" || options.skip === true || wrongPlatform)
+  if (mode === "skip" || options.skip === true || wrongPlatform || lacking)
     bunTest.skip(title, run, bunOptions);
   else if (only)
     bunTest.only(title, run, bunOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeScript spec API for `warden e2e`: test, expect, screen, device, app",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@delacour/warden": "0.6.0"
+    "@delacour/warden": "0.8.0"
   },
   "dependencies": {
     "zod": "^4.4.3"