@delacour/warden-e2e 0.6.0 → 0.8.0

package/types/e2e/src/env.d.ts

@@ -1,3 +1,5 @@
+import { type A11yAuditConfig } from "../../core/src/a11y/a11y.config";
+import { type CameraSuiteFeeds, type ConditionsConfig } from "../../core/src/conditions/conditions.config";
 import type { Result } from "../../types/src/result";
 /**
  * The env names `warden e2e` writes and the spec process reads (`apps/cli` imports these). `WARDEN_HEADLESS` and
@@ -12,6 +14,8 @@ export declare const ENV_NAMES: {
     readonly appPath: "WARDEN_APP_PATH";
     readonly metroUrl: "WARDEN_METRO_URL";
     readonly launchArgs: "WARDEN_LAUNCH_ARGS";
+    /** the dev client's url scheme (`exp+<slug>`): an Android launch has no args, so Metro's `--initialUrl` becomes a deep link on this scheme */
+    readonly devClientScheme: "WARDEN_DEV_CLIENT_SCHEME";
     readonly out: "WARDEN_E2E_OUT";
     readonly timeout: "WARDEN_E2E_TIMEOUT";
     readonly actionTimeout: "WARDEN_E2E_ACTION_TIMEOUT";
@@ -20,7 +24,16 @@ export declare const ENV_NAMES: {
     readonly helperDir: "WARDEN_HELPER_DIR";
     readonly simd: "WARDEN_SIMD";
     readonly simdSocket: "WARDEN_SIMD_SOCKET";
+    /** unix socket of a physical iPhone's resident runner host (`warden __ios-runner-host`): the iOS device driver connects there instead of to `warden-simd` */
+    readonly iosRunnerSocket: "WARDEN_IOS_RUNNER_SOCKET";
     readonly logTimestamps: "WARDEN_LOG_TIMESTAMPS";
+    /** `physical` when the job's device is a real phone/tablet (set by `warden e2e` / `batch`; absent for a simulator or emulator) */
+    readonly deviceKind: "WARDEN_DEVICE_KIND";
+    /**
+     * JSON argv (`{udid}` is replaced) that restarts a physical iPhone's runner host (`warden __ios-runner-restart`); the
+     * session runs it once when the runner connection is lost, and never reboots the phone
+     */
+    readonly iosRunnerRestart: "WARDEN_IOS_RUNNER_RESTART";
     /**
      * JSON argv (`{udid}` is replaced) the session runs after it rebooted the sim following a lost HID connection;
      * `warden` sets it for non-headless runs so the sim's viewer window comes back (packages/e2e cannot import apps/cli)
@@ -34,6 +47,20 @@ export declare const ENV_NAMES: {
     readonly perf: "WARDEN_PERF";
     /** JSON of the suite's `perf.budgets`; a breach fails the test with `PERF_BUDGET` */
     readonly perfBudgets: "WARDEN_PERF_BUDGETS";
+    /** JSON of the suite's `conditions` (network / location / clock applied before each spec, the rest reported as not applied) */
+    readonly conditions: "WARDEN_CONDITIONS";
+    /** the id of the lease holding `WARDEN_UDID`: conditions a spec sets are recorded on it and its shaping proxy hangs off it */
+    readonly leaseId: "WARDEN_LEASE_ID";
+    /** JSON argv that runs the shaping proxy (`warden __netproxy`) when specs run from a compiled `warden`; the JSON argument is appended */
+    readonly netproxyCommand: "WARDEN_NETPROXY_COMMAND";
+    /** `1` when the suite's devices are biometrics devices: the session enrolls an iOS sim again before the app is installed */
+    readonly biometrics: "WARDEN_BIOMETRICS";
+    /** JSON of the suite's `a11y` (`ignore` / `minSeverity` / `rules`): the defaults `device.a11yAudit()` and `toPassA11yAudit()` use */
+    readonly a11yAudit: "WARDEN_A11Y_AUDIT";
+    /** `1`: iOS apps launch with the injected library, so hint, custom actions, reading order and announcements can be read */
+    readonly a11y: "WARDEN_A11Y";
+    /** JSON of the suite's `camera` with absolute paths (`{ back?: { path, loop }, front? }`): staged and fed before the first `app.open()` */
+    readonly cameraFeeds: "WARDEN_CAMERA_FEEDS";
 };
 export declare const DEFAULT_TIMEOUT_MS = 120000;
 export declare const DEFAULT_ACTION_TIMEOUT_MS = 30000;
@@ -46,6 +73,8 @@ export type E2eEnv = {
     bundleId: string;
     appPath?: string;
     metroUrl?: string;
+    /** `WARDEN_DEV_CLIENT_SCHEME` */
+    devClientScheme?: string;
     launchArgs: string[];
     /** where `results.jsonl` and per-attempt artifacts go (may be relative to cwd) */
     out: string;
@@ -56,6 +85,12 @@ export type E2eEnv = {
     helperDir?: string;
     simd?: string;
     simdSocket?: string;
+    /** `WARDEN_IOS_RUNNER_SOCKET`: the runner host's socket for a physical iPhone */
+    iosRunnerSocket?: string;
+    /** `WARDEN_DEVICE_KIND`: `physical` for a real phone/tablet, absent for a simulator or emulator */
+    deviceKind?: "physical";
+    /** `WARDEN_IOS_RUNNER_RESTART`: argv that restarts the iPhone's runner host, `{udid}` not yet replaced */
+    iosRunnerRestart?: string[];
     /** warden already stamps the log lines: the spec reporter prints no clock of its own */
     logTimestamps: boolean;
     /** `WARDEN_AFTER_REBOOT`: argv run after a HID-loss reboot, `{udid}` not yet replaced (see `runAfterReboot`) */
@@ -68,6 +103,18 @@ export type E2eEnv = {
     perf?: string[];
     /** `WARDEN_PERF_BUDGETS`: raw JSON of the suite's budgets */
     perfBudgets?: string;
+    /** `WARDEN_CONDITIONS`: what every spec starts from (`conditions/suite-conditions.ts` applies it) */
+    conditions?: ConditionsConfig;
+    /** `WARDEN_LEASE_ID`: the device's lease; absent under a bare `bun test`, where network shaping is unsupported */
+    leaseId?: string;
+    /** `WARDEN_NETPROXY_COMMAND`: argv that starts the shaping proxy; absent from source (`bun netproxy.main.ts`) */
+    netproxyCommand?: string[];
+    /** `WARDEN_BIOMETRICS`: this is a biometrics device (profile `<p>+bio`); iOS enrollment does not survive a reboot or a spec's `unenroll` */
+    biometrics?: boolean;
+    /** `WARDEN_A11Y_AUDIT`: the suite's accessibility audit settings; absent = rules all, ignore none, minSeverity `error` */
+    a11yAudit?: A11yAuditConfig;
+    /** `WARDEN_CAMERA_FEEDS`: the suite's `camera` (absolute paths), applied before the first `app.open()` */
+    cameraFeeds?: CameraSuiteFeeds;
 };
 /**
  * Reads the spec env contract. `undefined` data = not running under warden (no `WARDEN_UDID`); an

package/types/e2e/src/expect/a11y-matchers.d.ts

@@ -0,0 +1,33 @@
+import type { A11yTarget } from "../a11y/a11y-target";
+import type { DeviceA11yAuditOptions } from "../device-a11y";
+import type { TextMatch } from "../screen/text";
+import type { AssertionContext } from "./matchers";
+export type AnnouncedOptions = {
+    /** how long to wait for the announcement (default: the assertion timeout); `.not` waits this long for none */
+    timeoutMs?: number;
+    /** same as `timeoutMs`, spelled as the other matchers do */
+    timeout?: number;
+    /** cursor from `device.announcements()`: only what came after it counts (default: everything the device kept) */
+    since?: number;
+};
+export type PassA11yAuditOptions = DeviceA11yAuditOptions;
+/**
+ * The matchers of `expect(device)` / `expect(screen)`: `toPassA11yAudit` and `toHaveAnnounced`. A failure carries the
+ * issue table or the announcements seen, and the screen as text with the `--a11y` columns (`screen-at-failure.txt`).
+ */
+export declare class DeviceAssertions {
+    private readonly target;
+    private readonly context;
+    constructor(target: A11yTarget, context: AssertionContext);
+    get not(): DeviceAssertions;
+    /**
+     * The screen as it is now has no issue at `minSeverity` (default `error`) or worse, from warden's rules and the
+     * platform's own audit. Takes the options of `device.a11yAudit` (suite `a11y` config applies); runs once, so settle
+     * first. Warnings (target size, platform guidelines) are reported only with `{ minSeverity: "warning" }`.
+     */
+    toPassA11yAudit(options?: PassA11yAuditOptions): Promise<void>;
+    /** An announcement or live-region change whose text contains the string or matches the RegExp arrived (`.not`: none did within the timeout). */
+    toHaveAnnounced(expected: TextMatch, options?: AnnouncedOptions): Promise<void>;
+    private failure;
+    private run;
+}

package/types/e2e/src/expect/expect.d.ts

@@ -1,20 +1,25 @@
 import { type Expect as BunExpect, type Matchers } from "bun:test";
+import type { Device } from "../device";
 import { E2eError } from "../errors";
 import { type Locator } from "../screen/locator";
+import type { Screen } from "../screen/screen";
 import { type Session } from "../session";
+import { DeviceAssertions } from "./a11y-matchers";
 import { LocatorAssertions } from "./matchers";
 /** Receives a failure `expect.soft` kept instead of throwing. */
 export type SoftSink = (error: E2eError) => void;
 /** `expect.soft`: `expect` whose failures are kept on the running attempt, which fails once its body has settled. */
 export type SoftExpect = {
     (actual: Locator): LocatorAssertions;
+    (actual: Device | Screen): DeviceAssertions;
     <T = unknown>(actual: T, message?: string): Matchers<T>;
 };
 /**
- * The spec `expect`: `expect(locator)` gives the polling locator matchers, anything else is bun's own `expect`
+ * The spec `expect`: `expect(locator)` gives the polling locator matchers, `expect(device)` / `expect(screen)` the
+ * accessibility ones (`toPassA11yAudit`, `toHaveAnnounced`), anything else is bun's own `expect`
  * (all of its statics — `any`, `arrayContaining`, `extend`, `not`, … — are on it too).
  */
-export type E2eExpect = ((actual: Locator) => LocatorAssertions) & BunExpect & {
+export type E2eExpect = ((actual: Locator) => LocatorAssertions) & ((actual: Device | Screen) => DeviceAssertions) & BunExpect & {
     readonly soft: SoftExpect;
 };
 export type ExpectDeps = {

package/types/e2e/src/expect/matchers.d.ts

@@ -1,5 +1,6 @@
 import { E2eError } from "../errors";
 import { type Locator } from "../screen/locator";
+import type { QueryRole } from "../screen/roles";
 import { type TextMatch } from "../screen/text";
 /**
  * A negated matcher passes only after its condition held this long without a break (or the whole timeout, if shorter).
@@ -63,6 +64,19 @@ export declare class LocatorAssertions {
     toBeChecked(options?: CheckedOptions): Promise<void>;
     toBeEnabled(options?: AssertionOptions): Promise<void>;
     toBeDisabled(options?: AssertionOptions): Promise<void>;
+    /** The computed accessible name (label, else text, else merged child text) equals the string (whitespace normalised) or matches the RegExp. */
+    toHaveAccessibleName(expected: TextMatch, options?: AssertionOptions): Promise<void>;
+    /** The element's role in the `getByRole` vocabulary (`button`, `switch`, `heading`, …). */
+    toHaveRole(expected: QueryRole, options?: AssertionOptions): Promise<void>;
+    /** The accessibility hint equals the string or matches the RegExp. iOS needs the app launched with the injected library to see hints. */
+    toHaveHint(expected: TextMatch, options?: AssertionOptions): Promise<void>;
+    /**
+     * The announcement warden's speech model composes for the element ("Save, button, double tap to save") equals the
+     * string (`exact: false`: contains it, ignoring case) or matches the RegExp. Simulated: never what the real reader says.
+     */
+    toAnnounce(expected: TextMatch, options?: TextAssertionOptions): Promise<void>;
+    /** The element holds screen-reader focus (Android TalkBack's accessibility focus; iOS does not report it). */
+    toBeA11yFocused(options?: AssertionOptions): Promise<void>;
     /** Exactly `expected` current matches (zero included). */
     toHaveCount(expected: number, options?: AssertionOptions): Promise<void>;
     private assert;

package/types/e2e/src/fixture-session.d.ts

@@ -9,6 +9,10 @@ import type { TraceEvent } from "./runner/trace";
 export type FixtureSession = {
     /** absolute `WARDEN_E2E_OUT` (screenshot fallback when no attempt is running) */
     readonly out: string;
+    /** the process's `results.jsonl`; `device.network` / `location` / `clock` append condition events to it */
+    readonly results?: {
+        readonly path: string;
+    };
     /** the running attempt's deadline / cancel signal; every driver call honours it */
     readonly signal?: AbortSignal;
     /** `<out>/<specId>/<title-slug>-<hash6>` of the running attempt */

package/types/e2e/src/fixtures.d.ts

@@ -1,6 +1,11 @@
-import { type Device } from "./device";
+import { type AlertAction, type Device } from "./device";
 import type { BaseFixtures, FixtureContext } from "./runner/fixtures.types";
 import type { ScreenHost } from "./screen/context";
+/**
+ * `device.alert(action)` for a read that answers sheets on the side: a sheet that stays up after every press
+ * (`ACTION_FAILED`) is left for the read to go on with, not thrown out of an unrelated `isVisible()`.
+ */
+export declare function answerAlertQuietly(device: Pick<Device, "alert">, action: AlertAction): Promise<boolean>;
 /**
  * What `screen` needs from one attempt: the live driver, its timeouts and deadline, and reported steps. With
  * `systemAlerts` set (`test.use`) and a `device` to press with, reads and waits answer the alerts they see.

package/types/e2e/src/index.d.ts

@@ -1,5 +1,11 @@
+export type { A11yAuditOptions, A11yAuditResult, A11yEvent, A11yEventKind, A11yEventSource, A11yIgnore, A11yIssue, A11yRuleId, A11ySeverity, A11ySource, Announcement, ScreenReaderState, SpokenLine, } from "./a11y/a11y.types";
 export type { OpenOptions, OpenWaitUntil } from "./app";
+export type { CameraFacingChoice, CameraSetOptions, ClockInput, ConditionRun, DeviceCamera, DeviceClock, DeviceLocation, DeviceNetwork, DevicePermissions, Duration, FlapOptions, LocationPoint, NetworkSetOptions, NetworkStatus, RouteOptions, TimelineStepInput, } from "./conditions/device-conditions";
+export type { BiometricState, DeviceBiometrics } from "./device";
+export type { A11yAnnouncement, A11yAnnouncements, A11yAnnouncementsOptions, DeviceA11y, DeviceA11yAuditOptions, DeviceScreenReader, ScreenReaderSpokenOptions, } from "./device-a11y";
+export type { A11yOp, A11yState, CameraState } from "./driver/driver.types";
 export { E2eError } from "./errors";
+export type { AnnouncedOptions, PassA11yAuditOptions } from "./expect/a11y-matchers";
 export { expect } from "./expect/expect";
 export type { PerfBreach, PerfBudgets } from "./perf/budgets";
 export type { DevicePerf } from "./perf/device-perf";

package/types/e2e/src/runner/callsite.d.ts

@@ -1,2 +1,4 @@
 /** The absolute path of the first stack frame outside the e2e runner: the spec file calling `test()`. */
-export declare function callerFile(stack?: string | undefined): string;
+export declare function callerFile(stack?: string | undefined, 
+/** more files that never count as the caller (an API that resolves paths against the spec) */
+extraOwn?: (path: string) => boolean): string;

package/types/e2e/src/runner/scope.d.ts

@@ -57,6 +57,7 @@ export declare function registrationDefaults(env?: Readonly<Record<string, strin
     actionTimeoutMs: number;
     assertionTimeoutMs: number;
     platform: "ios" | "android" | undefined;
+    deviceKind: "physical" | undefined;
 };
 /** Records that a `.only` was collected (kept on `globalThis`: the preload and the specs may be separate bundles). */
 export declare function markOnly(): void;

package/types/e2e/src/runner/test.d.ts

@@ -1,4 +1,5 @@
 import type { Platform } from "../driver/driver.types";
+import { type Requirement } from "../driver/requirements";
 import { type BaseFixtures } from "./fixtures.types";
 import { type Hook, type UseOptions } from "./scope";
 export type TestOptions = {
@@ -8,6 +9,11 @@ export type TestOptions = {
     only?: boolean;
     /** run only on these platforms (decided at collection time from `WARDEN_PLATFORM`) */
     platforms?: readonly Platform[];
+    /**
+     * driver capabilities the test needs (`pinch`, `multiTouch`). The test is skipped, when collected, on a device whose
+     * driver is known to lack one: a physical iPhone has neither. Elsewhere the driver decides at run time.
+     */
+    requires?: readonly Requirement[];
     /** extra attempts after a failure; only the last attempt writes to `results.jsonl` */
     retry?: number;
 };

package/types/e2e/src/screen/render.d.ts

@@ -7,6 +7,8 @@ export type RenderOptions = {
     refs: ReadonlyMap<string, string>;
     /** cap on element lines; a `… N more (use --all)` line follows when cut */
     maxLines?: number;
+    /** append the screen-reader facts of `Element.a11y` (see {@link a11yWords}) to each line */
+    a11y?: boolean;
 };
 export type RenderedSnapshot = {
     lines: string[];
@@ -19,10 +21,16 @@ export type RenderedSnapshot = {
 };
 /** `[button] "Sign in" id=sign-in-submit`: enough to tell matches apart in an error message. */
 export declare function describeEntry(entry: NodeEntry): string;
+/**
+ * The `--a11y` tail of an entry line: `hint="…"`, `actions=["…"]`, `a11y-focused`, `not-important`, `live=polite|assertive`.
+ * Only facts the backend read are printed; an element without `a11y` adds nothing.
+ */
+export declare function a11yWords(entry: NodeEntry): string[];
 /** `@e3 [button] "Sign in" id=sign-in-submit value="…" enabled hittable (24,332 345×48)`; `indent` is in levels. */
 export declare function renderEntryLine(entry: NodeEntry, options?: {
     ref?: string;
     indent?: number;
+    a11y?: boolean;
 }): string;
 /** The entries `interactiveOnly` lists: visible ones that are interactive or carry a testID. */
 export declare function isListed(entry: NodeEntry): boolean;

package/types/e2e/src/traced-device.d.ts

@@ -2,7 +2,8 @@ import type { Device } from "./device";
 import type { SpanRunner } from "./runner/span";
 /**
  * `device` with every call timed as a `device.<name>` span in the attempt's `trace.jsonl` (trace only: no console
- * line, since a settle or an alert is not a step). The driver calls a device call makes are `driver.*` spans of
+ * line, since a settle or an alert is not a step). The condition calls are `device.network.<call>`,
+ * `device.location.<call>`, `device.clock.<call>` and `device.timeline`. The driver calls a device call makes are `driver.*` spans of
  * their own, so a slow `device.openLink` shows what it spent its time on. Without a span runner (a bare
  * `FixtureSession`) the device is returned unchanged.
  */