@delacour/warden-e2e 0.7.0 → 0.8.0

package/types/core/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { WaitReason } from "./queue";
 export type Platform = "ios" | "android";
 /** Facts about a real phone/tablet, from its provider. Only physical devices carry one. */
 export type PhysicalInfo = {
@@ -84,6 +85,11 @@ export type Lease = {
      * attaches to it instead of refusing with `device_busy`, and never releases it. Other owners still see it as foreign.
      */
     shared?: boolean;
+    /**
+     * The `claimDevices` call(s) that took this lease: a wrapper's legs share one id, so the per-owner limit counts
+     * claims, not devices. Absent on leases an older binary wrote (each counts as its own claim).
+     */
+    claimId?: string;
 };
 export type DeviceState = "booted" | "shutdown" | "booting";
 /** A device as seen by a provider, enriched with warden's own bookkeeping. */
@@ -160,6 +166,10 @@ export type QueueEntry = {
     owner: Owner;
     label?: string;
     pid?: number;
+    /** why the claim waits, rewritten every round (absent on rows an older binary wrote) */
+    reason?: WaitReason;
+    /** the claim this row belongs to (absent on rows an older binary wrote) */
+    claimId?: string;
 };
 /** The one constructor of a device lease resource: carries `physical` for real devices. */
 export declare function deviceResourceOf(d: InventoryDevice): DeviceResource;

package/types/core/src/xcode.d.ts

@@ -0,0 +1,22 @@
+import { type AsyncResult } from "../../types/src/result";
+import { type Exec } from "./exec";
+/** The Xcode warden would build with: `DEVELOPER_DIR` when set (Apple's per-agent setup), else `xcode-select`. */
+export type XcodeInfo = {
+    /** the Developer directory (`…/Xcode.app/Contents/Developer`) */
+    path: string;
+    /** `27.1` */
+    version: string;
+    /** `27A9275` */
+    build: string;
+    major: number;
+    source: "DEVELOPER_DIR" | "xcode-select";
+};
+type XcodeVersion = Pick<XcodeInfo, "version" | "build" | "major">;
+/** `Xcode 27.1\nBuild version 27A9275` */
+export declare function parseXcodeVersion(stdout: string): XcodeVersion | undefined;
+/**
+ * The selected Xcode. `version.plist` beside `Developer/` names version + build in two ~10 ms spawns;
+ * `xcodebuild -version` (0.4–1 s) is the fallback and sees the same `DEVELOPER_DIR`.
+ */
+export declare function readXcode(exec: Exec, env: Record<string, string | undefined>): AsyncResult<XcodeInfo>;
+export {};

package/types/e2e/src/a11y/a11y-target.d.ts

@@ -0,0 +1,23 @@
+import type { Result } from "../../../types/src/result";
+import type { DriverError } from "../driver/driver.types";
+import type { A11yAuditOptions, A11yAuditResult } from "./a11y.types";
+import type { AnnouncementMatch } from "./announcements";
+/** What `toPassA11yAudit` / `toHaveAnnounced` need of a `device` (or the `screen` beside it), reached through {@link a11yTargetOf}. */
+export type A11yTarget = {
+    /** the audit `device.a11yAudit` runs, suite defaults applied */
+    audit(options: A11yAuditOptions): Promise<A11yAuditResult>;
+    /** polls announcements and live-region changes until one matches `match` or `timeoutMs` passes (`E_TIMEOUT`) */
+    waitForAnnouncement(match: string | RegExp, options: {
+        timeoutMs: number;
+        since?: number;
+    }): Promise<Result<AnnouncementMatch, DriverError>>;
+    /** the current screen as text with the `--a11y` columns (failure evidence); undefined when it cannot be read */
+    a11yScreen(): Promise<string | undefined>;
+    /** the assertion timeout in ms */
+    assertionTimeout(): number;
+    /** one reported step */
+    step<T>(label: string, fn: () => Promise<T>): Promise<T>;
+};
+/** Ties a device (and the screen made beside it, or a wrapper of either) to its a11y hooks; `Device` itself does not expose them. */
+export declare function registerA11yTarget(target: object, hooks: A11yTarget): void;
+export declare function a11yTargetOf(target: unknown): A11yTarget | undefined;

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

@@ -0,0 +1,81 @@
+import type { Platform, Role } from "../driver/driver.types";
+/** Where a spoken line or issue came from: warden's own model, or a real platform engine. */
+export type A11ySource = "simulated" | "talkback" | "xcuitest" | "atf" | "warden";
+/** What a screen reader says for one element, split so matchers can check each part. */
+export type Announcement = {
+    /** element id in the snapshot it came from */
+    id: string;
+    identifier?: string;
+    /** the full phrase, parts joined in the platform's order */
+    text: string;
+    role: Role;
+    platform: Platform;
+    source: A11ySource;
+    parts: {
+        label?: string;
+        value?: string;
+        /** spoken role word: "button", "heading", "switch button" */
+        role?: string;
+        /** spoken states: "selected", "dimmed", "on", "not checked" */
+        state: readonly string[];
+        hint?: string;
+    };
+};
+export type A11yRuleId = "missing-name" | "image-no-name" | "target-size" | "target-size-platform" | "duplicate-name" | "role-in-name" | "label-in-name" | "hidden-focusable" | "text-clipped" | "native";
+export type A11ySeverity = "error" | "warning";
+export type A11yIssue = {
+    rule: A11yRuleId;
+    severity: A11ySeverity;
+    /** WCAG 2.2 success criterion, e.g. "2.5.8" */
+    wcag?: string;
+    source: Exclude<A11ySource, "simulated" | "talkback">;
+    elementId?: string;
+    identifier?: string;
+    message: string;
+};
+export type A11yIgnore = {
+    rule: A11yRuleId;
+    identifier?: string;
+};
+export type A11yAuditOptions = {
+    rules?: readonly A11yRuleId[];
+    ignore?: readonly A11yIgnore[];
+    /** lowest severity that fails `toPassA11yAudit` / `warden ui a11y audit`; default "error" */
+    minSeverity?: A11ySeverity;
+};
+export type A11yAuditResult = {
+    issues: readonly A11yIssue[];
+    checked: number;
+    sources: readonly A11yIssue["source"][];
+    skipped: readonly {
+        source: A11yIssue["source"];
+        reason: string;
+    }[];
+};
+export type ScreenReaderState = {
+    mode: "real";
+    engine: "talkback";
+} | {
+    mode: "simulated";
+    engine: "voiceover";
+} | {
+    mode: "off";
+};
+export type SpokenLine = {
+    text: string;
+    at: number;
+    source: A11ySource;
+};
+/** Where an {@link A11yEvent} was observed: the Android `warden-uiad` event stream, or the iOS injected library. */
+export type A11yEventSource = "uiad" | "inject";
+export type A11yEventKind = "announcement" | "live-region" | "screen-changed" | "layout-changed";
+/**
+ * Something the app told assistive technology, in the order it happened (WDN-A11Y, A11Y-8). `text` is the announced
+ * string (announcements and live regions); screen/layout changes carry none. `at` is epoch ms on the device.
+ */
+export type A11yEvent = {
+    kind: A11yEventKind;
+    text?: string;
+    at: number;
+    source: A11yEventSource;
+};

package/types/e2e/src/a11y/announcements.d.ts

@@ -0,0 +1,24 @@
+import type { Result } from "../../../types/src/result";
+import type { Driver, DriverError } from "../driver/driver.types";
+import type { A11yEvent } from "./a11y.types";
+export type WaitForAnnouncementOptions = {
+    timeoutMs?: number;
+    /** cursor from an earlier read: only events after it count (default: from the start) */
+    since?: number;
+    pollMs?: number;
+    /** injected clock and sleep (tests) */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare const ANNOUNCEMENT_TIMEOUT_MS = 5000;
+export declare const ANNOUNCEMENT_POLL_MS = 100;
+export type AnnouncementMatch = {
+    event: A11yEvent;
+    cursor: number;
+};
+/**
+ * Poll the driver's a11y events until an announcement or live-region change whose text contains `match` (string) or
+ * matches it (RegExp) arrives. `E_UNSUPPORTED` when the driver cannot read events, `E_TIMEOUT` (with the texts seen)
+ * when nothing matched in time. The returned `cursor` is where the next wait should start.
+ */
+export declare function waitForAnnouncement(driver: Driver, match: string | RegExp, opts?: WaitForAnnouncementOptions): Promise<Result<AnnouncementMatch, DriverError>>;

package/types/e2e/src/a11y/audit.d.ts

@@ -0,0 +1,22 @@
+import type { TextSize } from "../../../core/src/conditions/conditions.types";
+import type { Platform, Snapshot } from "../driver/driver.types";
+import type { A11yAuditOptions, A11yAuditResult, A11yIssue, A11ySeverity } from "./a11y.types";
+import type { RuleEntry } from "./rules/rule.context";
+/** The rules warden runs itself, in report order. `native` findings come from XCUITest / ATF (A11Y-4). */
+export declare const WARDEN_RULES: readonly RuleEntry[];
+export type RunAuditOptions = A11yAuditOptions & {
+    /** active text size; `text-clipped` only runs from `accessibility-medium` (scale 1.6) up */
+    textSize?: TextSize;
+};
+/** Runs warden's own rules on one snapshot. Native (XCUITest / ATF) findings are added with `mergeIssues`. */
+export declare function runAudit(snapshot: Snapshot, platform: Platform, opts?: RunAuditOptions): A11yAuditResult;
+/** Issues at or above `minSeverity` (default `error`): what fails `toPassA11yAudit` / `warden ui a11y audit`. */
+export declare function failing(result: A11yAuditResult, minSeverity?: A11ySeverity): A11yIssue[];
+/**
+ * Adds another source's findings to a result. A finding on the same element and WCAG criterion as one already there
+ * is dropped, and the kept issue notes the other source; findings without a WCAG ref only dedupe on an identical
+ * element + message. `skipped` records engines that could not run (never fails the audit).
+ */
+export declare function mergeIssues(base: A11yAuditResult, extra: readonly A11yIssue[], skipped?: A11yAuditResult["skipped"]): A11yAuditResult;
+/** Compact table for test failure output and the CLI: severity, rule, WCAG, element, message. */
+export declare function formatIssues(result: A11yAuditResult, minSeverity?: A11ySeverity): string;

package/types/e2e/src/a11y/native/atf.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import type { NativeAuditResult } from "../../driver/native-audit";
+import type { A11yIssue } from "../a11y.types";
+export declare const atfReplySchema: z.ZodObject<{
+    checks: z.ZodNumber;
+    ignored: z.ZodOptional<z.ZodNumber>;
+    contrast: z.ZodOptional<z.ZodBoolean>;
+    hierarchyMs: z.ZodOptional<z.ZodNumber>;
+    checksMs: z.ZodOptional<z.ZodNumber>;
+    failedChecks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    results: z.ZodArray<z.ZodObject<{
+        check: z.ZodString;
+        type: z.ZodEnum<{
+            ERROR: "ERROR";
+            WARNING: "WARNING";
+            INFO: "INFO";
+        }>;
+        resultId: z.ZodOptional<z.ZodNumber>;
+        resourceName: z.ZodOptional<z.ZodString>;
+        className: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        contentDescription: z.ZodOptional<z.ZodString>;
+        bounds: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AtfReply = z.infer<typeof atfReplySchema>;
+export type AtfResult = AtfReply["results"][number];
+/** WCAG 2.2 success criterion per ATF check (class name without the `Check` suffix). */
+export declare const ATF_WCAG: Readonly<Record<string, string>>;
+export declare function atfCheckName(check: string): string;
+export declare function mapAtfResult(result: AtfResult): A11yIssue;
+/** The raw `audit` reply -> issues; a reply that does not parse is a `skipped` with the reason, never a throw. */
+export declare function mapAtfReply(raw: unknown): NativeAuditResult;
+/** What the driver can do for ATF: run the op (`undefined` = no `warden-uiad` to run it). */
+export type AtfPort = {
+    run(options: {
+        contrast: boolean;
+    }): Promise<{
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: {
+            message: string;
+        };
+    } | undefined>;
+};
+export declare function atfAudit(port: AtfPort, options?: {
+    contrast?: boolean;
+}): Promise<NativeAuditResult>;

package/types/e2e/src/a11y/native/xcuitest.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import type { NativeAuditResult } from "../../driver/native-audit";
+import type { A11yIssue } from "../a11y.types";
+/**
+ * The XCUITest accessibility audit (`performAccessibilityAudit`, iOS 17+) as `A11yIssue`s. The runner's `audit` op
+ * answers `{issues:[{auditType, compactDescription, detailedDescription, element?}], count, types, ms}`
+ * (`native/ios-runner/RunnerCore/.../AuditEncoder.swift`); this file maps it. Pure: a port supplies the reply.
+ */
+export declare const AUDIT_TYPES: readonly ["contrast", "elementDetection", "hitRegion", "sufficientElementDescription", "dynamicType", "textClipped", "trait"];
+export type XcuitestAuditType = (typeof AUDIT_TYPES)[number];
+export declare const auditReplySchema: z.ZodObject<{
+    issues: z.ZodArray<z.ZodObject<{
+        auditType: z.ZodString;
+        auditTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        compactDescription: z.ZodString;
+        detailedDescription: z.ZodString;
+        element: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            identifier: z.ZodString;
+            label: z.ZodString;
+            frame: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    count: z.ZodNumber;
+    types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuditReply = z.infer<typeof auditReplySchema>;
+export type AuditWireIssue = AuditReply["issues"][number];
+/** WCAG 2.2 success criterion per audit type. */
+export declare const XCUITEST_WCAG: Readonly<Record<string, string>>;
+export declare function mapAuditIssue(issue: AuditWireIssue): A11yIssue;
+export declare function mapAuditReply(raw: unknown): NativeAuditResult;
+/** What the iOS driver gives the audit: the runner `audit` op, or the reason it cannot run. */
+export type XcuitestPort = {
+    audit(params: {
+        bundleId: string;
+        types?: readonly XcuitestAuditType[];
+    }): Promise<{
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    }>;
+};
+export declare function xcuitestAudit(port: XcuitestPort | {
+    unavailable: string;
+}, options?: {
+    bundleId?: string;
+    types?: readonly XcuitestAuditType[];
+}): Promise<NativeAuditResult>;

package/types/e2e/src/a11y/order.d.ts

@@ -0,0 +1,5 @@
+import type { Platform, Snapshot } from "../driver/driver.types";
+import type { Announcement } from "./a11y.types";
+import { type AnnounceOptions } from "./speech";
+/** The announcements a swipe-right sweep would produce, in order. Every entry has `source: "simulated"`. */
+export declare function readingOrder(snapshot: Snapshot, platform: Platform, opts?: AnnounceOptions): Announcement[];

package/types/e2e/src/a11y/rules/duplicate-name.d.ts

@@ -0,0 +1,6 @@
+import { type Rule } from "./rule.context";
+/**
+ * 2.4.6: several controls announced identically ("Delete", "Delete") cannot be told apart by ear. One issue per
+ * extra control; same identifier or same frame means the same control seen twice, not a duplicate.
+ */
+export declare const duplicateName: Rule;

package/types/e2e/src/a11y/rules/hidden-focusable.d.ts

@@ -0,0 +1,3 @@
+import { type Rule } from "./rule.context";
+/** A node the platform still marks focusable and important while it is hidden, empty or off screen: a screen reader lands on nothing. */
+export declare const hiddenFocusable: Rule;

package/types/e2e/src/a11y/rules/image-no-name.d.ts

@@ -0,0 +1,6 @@
+import { type Rule } from "./rule.context";
+/**
+ * 1.1.1: an image a screen reader can reach needs a name. Decorative images (`important: false`, hidden) are not
+ * in `ctx.reachable`, so marking one decorative is the fix.
+ */
+export declare const imageNoName: Rule;

package/types/e2e/src/a11y/rules/label-in-name.d.ts

@@ -0,0 +1,7 @@
+import { type Rule } from "./rule.context";
+/**
+ * 2.5.3: voice-control users say what they see. When the accessible name is a separate label (content-desc /
+ * accessibilityLabel) and the control shows other text, the visible text must be inside the name. Names built from
+ * the visible text itself can't fail.
+ */
+export declare const labelInName: Rule;

package/types/e2e/src/a11y/rules/missing-name.d.ts

@@ -0,0 +1,3 @@
+import { type Rule } from "./rule.context";
+/** 4.1.2: a control a screen reader stops on must have a name, or it is announced as just its role. */
+export declare const missingName: Rule;

package/types/e2e/src/a11y/rules/role-in-name.d.ts

@@ -0,0 +1,3 @@
+import { type Rule } from "./rule.context";
+/** The screen reader already says the role ("Save, button"); a name that says it too is announced twice. */
+export declare const roleInName: Rule;

package/types/e2e/src/a11y/rules/rule.context.d.ts

@@ -0,0 +1,22 @@
+import type { Element, Platform, Snapshot } from "../../driver/driver.types";
+import type { A11yIssue, A11yRuleId } from "../a11y.types";
+/** What every rule reads: the snapshot, its platform and (for text-clipped) the active text size. */
+export type RuleContext = {
+    platform: Platform;
+    /** font scale in force (iOS content-size multiplier / Android font_scale); undefined = not set by the run */
+    textScale?: number;
+    /** nodes a screen reader can reach: not hidden (nor under a hidden node), `important !== false` */
+    reachable: readonly Element[];
+    parents: ReadonlyMap<Element, Element>;
+};
+export type Rule = (snapshot: Snapshot, ctx: RuleContext) => A11yIssue[];
+export type RuleEntry = {
+    id: A11yRuleId;
+    run: Rule;
+};
+/** Points (iOS) / dp (Android) per frame unit: Android frames are px. */
+export declare function unitsPerPoint(snapshot: Snapshot): number;
+export declare function isAncestor(a: Element, b: Element, parents: ReadonlyMap<Element, Element>): boolean;
+export declare function related(a: Element, b: Element, parents: ReadonlyMap<Element, Element>): boolean;
+export declare function issue(rule: A11yRuleId, severity: A11yIssue["severity"], el: Element, message: string, wcag?: string): A11yIssue;
+export declare function describe(el: Element): string;

package/types/e2e/src/a11y/rules/target-size.d.ts

@@ -0,0 +1,21 @@
+import type { Element, Snapshot } from "../../driver/driver.types";
+import { type Rule, type RuleContext } from "./rule.context";
+export declare const WCAG_MIN = 24;
+export declare const IOS_MIN = 44;
+export declare const ANDROID_MIN = 48;
+type Box = {
+    el: Element;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * WCAG 2.5.8 spacing exception, simplified: a 24 pt circle centred on each undersized target must not touch another
+ * target (circle-to-circle for two undersized targets, circle-to-rectangle otherwise). Ancestors and descendants
+ * of a target do not count as "another target". Sub-24 targets that pass the test are not reported.
+ */
+export declare function wcagFailures(snapshot: Snapshot, ctx: RuleContext): Box[];
+export declare const targetSize: Rule;
+export declare const targetSizePlatform: Rule;
+export {};

package/types/e2e/src/a11y/rules/text-clipped.d.ts

@@ -0,0 +1,9 @@
+import { type Rule } from "./rule.context";
+/** iOS `accessibility-medium`; Android font_scale 1.6 is the same step. */
+export declare const CLIPPING_MIN_SCALE = 1.6;
+/**
+ * 1.4.4: at large text sizes text must still be readable. Runs only when the run's text scale is at least
+ * accessibility-medium (`ctx.textScale`). Flags text ending in an ellipsis, and text whose frame spills out of a
+ * non-scrolling parent. Scroll containers and the screen-sized root are exempt.
+ */
+export declare const textClipped: Rule;

package/types/e2e/src/a11y/speech.d.ts

@@ -0,0 +1,26 @@
+import type { Element, Platform } from "../driver/driver.types";
+import type { Announcement } from "./a11y.types";
+/**
+ * Speech model. APPROXIMATES, never equals, what VoiceOver (iOS) or TalkBack (Android) says:
+ * word order and role/state vocabulary follow the documented behaviour of each reader, but
+ * locale, verbosity settings, OS version differences and app-specific custom roles are not modelled.
+ * Every result carries `source: "simulated"`.
+ */
+export type AnnounceOptions = {
+    /** include the hint as the last part (default true) */
+    hints?: boolean;
+};
+/** Can the user activate / edit this node? (what makes a screen reader stop on it and swallow its children) */
+export declare function isActionable(el: Element, platform: Platform): boolean;
+/** Screen-reader focus target: actionable, or the platform says it is focusable. */
+export declare function isFocusTarget(el: Element, platform: Platform): boolean;
+/**
+ * The accessible name. label || text || (Android) value/placeholder of inputs || merged descendant text
+ * when the node is a focus target whose children are not themselves actionable (both readers merge them).
+ */
+export declare function accessibleName(el: Element, platform: Platform): string | undefined;
+/**
+ * What the platform's screen reader would say when focus lands on `el`. SIMULATED: an approximation of
+ * VoiceOver / TalkBack from the snapshot's facts, not their real output. `source` is always `"simulated"`.
+ */
+export declare function announce(el: Element, platform: Platform, opts?: AnnounceOptions): Announcement;

package/types/e2e/src/a11y/talkback-log.d.ts

@@ -0,0 +1,13 @@
+import type { SpokenLine } from "./a11y.types";
+/** One-shot dump of TalkBack's log with epoch timestamps. */
+export declare const TALKBACK_LOGCAT_ARGV: readonly string[];
+export type TalkBackLogOptions = {
+    /** `at` for a line with no epoch prefix */
+    now: number;
+    /** keep only lines after this epoch ms */
+    since?: number;
+};
+/** The spoken fragments in `log`, in log order. */
+export declare function parseTalkBackLog(log: string, opts: TalkBackLogOptions): SpokenLine[];
+/** Is TalkBack's log level verbose, as far as this log can tell: it holds at least one spoken fragment. */
+export declare function hasSpeechLines(log: string): boolean;

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

@@ -30,7 +30,6 @@ export type OpenOptions = {
      */
     wait?: "quiet" | "none" | OpenWaitUntil;
 };
-/** The app under test (`WARDEN_BUNDLE_ID`). */
 export type App = {
     /**
      * Launches the app (terminating a running instance first) with `WARDEN_LAUNCH_ARGS` + `args`, then

package/types/e2e/src/conditions/condition-events.d.ts

@@ -1,4 +1,4 @@
-import type { A11yCondition, BatteryCondition, ClockCondition, HostFault, LocaleCondition, LocationCondition, NetworkCondition, PermissionCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yCondition, BatteryCondition, CameraCondition, ClockCondition, HostFault, LocaleCondition, LocationCondition, NetworkCondition, PermissionCondition } from "../../../core/src/conditions/conditions.types";
 /**
  * One applied condition transition, the evidence line that lets a failure show which network/location was
  * active. Written to `results.jsonl` beside the test results (`readResults` skips lines that are not a
@@ -39,6 +39,11 @@ export type ConditionEvent = {
     area: "battery";
     value: BatteryCondition;
     at: number;
+} | {
+    type: "condition";
+    area: "camera";
+    value: CameraCondition;
+    at: number;
 } | {
     type: "condition";
     area: "faults";

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

@@ -1,6 +1,6 @@
 import { type NetworkInput } from "../../../core/src/conditions/conditions.config";
-import type { ClockCondition, HostFault, LatLon, LocationCondition, LocationScenario, NetworkCondition } from "../../../core/src/conditions/conditions.types";
-import type { A11yOp, A11yState, BatteryOp, BatteryState, Driver, LocaleState, NetworkState, PermissionGrants, PermissionsState, PushPayload, SettingOptions, TimezoneState } from "../driver/driver.types";
+import type { CameraFacing, ClockCondition, HostFault, LatLon, LocationCondition, LocationScenario, NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yOp, A11yState, BatteryOp, BatteryState, CameraState, Driver, LocaleState, NetworkState, PermissionGrants, PermissionsState, PushPayload, SettingOptions, TimezoneState } from "../driver/driver.types";
 import type { E2eEnv } from "../env";
 import { type ConditionSink } from "./condition-events";
 import type { ConditionRecorder } from "./lease-recorder";
@@ -123,7 +123,31 @@ export type ConditionsInternals = {
     /** the suite declares something to apply */
     readonly declared: boolean;
 };
+/** `facing` of `device.camera.set` / `clear`: one camera, or `"both"`. */
+export type CameraFacingChoice = CameraFacing | "both";
+export type CameraSetOptions = {
+    /** which camera plays the asset; default `"back"` */
+    facing?: CameraFacingChoice;
+    /** video only: play again from the start at the end; default true */
+    loop?: boolean;
+};
+export type DeviceCamera = {
+    /**
+     * Feeds the png, jpg, heic, mp4 or mov at `path` (relative to the spec file) into the app's camera, replacing what
+     * that facing played; the other facing keeps its feed. The result says when it shows: `appliesOnLaunch` (iOS: an
+     * app launched without the camera sees it from the next launch), `appliesOnCameraOpen` (Android: the app's next
+     * camera open) or `rebooted` (Android: a video feed restarted the emulator). Android needs a `--camera` device
+     * (`E_CAMERA_DEVICE` otherwise); a missing or unsupported file fails with `E_CAMERA_NOT_FOUND` / `E_CAMERA_MEDIA`.
+     * Taken off when the test ends (back to the suite's `camera`).
+     */
+    set(path: string, options?: CameraSetOptions): Promise<CameraState>;
+    /** Takes the feed off one camera, or both (the default). */
+    clear(facing?: CameraFacingChoice): Promise<CameraState>;
+    /** The feeds this spec has in place. */
+    status(): Promise<CameraState>;
+};
 export type DeviceConditions = {
+    camera: DeviceCamera;
     network: DeviceNetwork;
     location: DeviceLocation;
     clock: DeviceClock;
@@ -156,6 +180,10 @@ export type DeviceConditionsDeps = {
     log?: (line: string) => void;
     /** where changes are written on the device's lease so release can undo them after a crash; default none */
     recorder?: ConditionRecorder;
+    /** the warden home camera assets are staged under; default `$WARDEN_HOME` / `~/.warden` */
+    wardenHome?: string;
+    /** the directory a relative camera path is resolved against; default the calling spec file's, else `specsDir`, else cwd */
+    specDir?: () => string | undefined;
 };
 /** Ties a device (or a wrapper of it) to its conditions' runner hooks; `Device` itself does not expose them. */
 export declare function registerConditions(device: object, internals: ConditionsInternals): void;

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

@@ -0,0 +1,97 @@
+import type { TextSize } from "../../core/src/conditions/conditions.types";
+import type { Result } from "../../types/src/result";
+import type { A11yAuditOptions, A11yAuditResult, A11yEventSource, Announcement, ScreenReaderState, SpokenLine } from "./a11y/a11y.types";
+import type { A11yTarget } from "./a11y/a11y-target";
+import type { Driver, DriverError, Snapshot } from "./driver/driver.types";
+import type { E2eEnv } from "./env";
+/** `device.a11yAudit(opts)`: the audit's own options, plus what only a device knows. */
+export type DeviceA11yAuditOptions = A11yAuditOptions & {
+    /** the text size the app runs at; `text-clipped` only runs from `accessibility-medium` up */
+    textSize?: TextSize;
+    /** also run the platform's own audit (XCUITest on iOS, ATF on Android) when the driver can. Default true. */
+    native?: boolean;
+};
+/** An announcement or live-region change the app made, in the order it happened. */
+export type A11yAnnouncement = {
+    kind: "announcement" | "live-region";
+    text: string;
+    /** epoch ms on the device */
+    at: number;
+    source: A11yEventSource;
+};
+export type A11yAnnouncementsOptions = {
+    /** cursor from an earlier read: only what came after it */
+    since?: number;
+};
+export type A11yAnnouncements = {
+    announcements: A11yAnnouncement[];
+    /** pass back as `since` to read only what is new */
+    cursor: number;
+    /** the Android event buffer overwrote events this caller never read */
+    lost?: boolean;
+};
+export type ScreenReaderSpokenOptions = {
+    since?: number;
+};
+/**
+ * What a screen reader does with the screen. `order()` is warden's model of the reading order and works on both
+ * platforms (every `Announcement` is `source: "simulated"`: an approximation, never what VoiceOver or TalkBack
+ * say). The other calls drive a real TalkBack on an Android emulator (`device.a11y({ screenReader: true })`) and
+ * throw `ACTION_FAILED` (`E_UNSUPPORTED`) anywhere else.
+ */
+export type DeviceScreenReader = {
+    /** reading order of the current screen */
+    order(): Promise<Announcement[]>;
+    state(): Promise<ScreenReaderState>;
+    /** moves screen-reader focus one step on; resolves what it now holds (`undefined` past the end) */
+    next(): Promise<Announcement | undefined>;
+    prev(): Promise<Announcement | undefined>;
+    /** double-tap on the focused node */
+    activate(): Promise<void>;
+    /** the node holding screen-reader focus, if any */
+    focused(): Promise<Announcement | undefined>;
+    /** what the reader said since `since`; `cursor` goes back in as the next `since` */
+    spoken(options?: ScreenReaderSpokenOptions): Promise<{
+        lines: SpokenLine[];
+        cursor: number;
+    }>;
+};
+export type DeviceA11y = {
+    /**
+     * Audits the current screen: warden's rules over the snapshot (with the iOS injected read merged in when the app
+     * runs with it) plus the platform's own audit when the driver offers one. The suite's `a11y` config
+     * (`warden.config.ts`) supplies the defaults; options passed here win key by key.
+     */
+    a11yAudit(options?: DeviceA11yAuditOptions): Promise<A11yAuditResult>;
+    readonly screenReader: DeviceScreenReader;
+    /** announcements and live-region changes since `since` (needs the injected library on iOS) */
+    announcements(options?: A11yAnnouncementsOptions): Promise<A11yAnnouncements>;
+};
+export type DeviceA11yDeps = {
+    driver: Driver;
+    env: Pick<E2eEnv, "a11yAudit" | "assertionTimeoutMs"> & {
+        bundleId?: string;
+    };
+    /** read per call: the runner swaps it for every attempt */
+    signal: () => AbortSignal | undefined;
+    step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+};
+/**
+ * The snapshot with the screen-reader facts a plain snapshot lacks merged in. A driver without the capability, or an
+ * app launched without the injected library (`E_UNSUPPORTED`), leaves it as it is. Any other failure is returned.
+ */
+export declare function withA11yRead(driver: Driver, snapshot: Snapshot): Promise<Result<Snapshot, DriverError>>;
+/** The screen as text with the `--a11y` columns: what an a11y failure attaches as `screen-at-failure.txt`. */
+export declare function renderA11yScreen(snapshot: Snapshot, maxLines?: number): string;
+export type AuditSnapshotOptions = DeviceA11yAuditOptions & {
+    /** the app the platform's own audit checks (iOS XCUITest) */
+    bundleId?: string;
+};
+/**
+ * Audits one snapshot: warden's rules, plus the platform's own audit (XCUITest / ATF) unless `native: false`, `rules`
+ * leaves out `native`, or the driver has none. `device.a11yAudit` and `warden ui a11y audit` share this.
+ */
+export declare function auditSnapshot(driver: Driver, snapshot: Snapshot, options?: AuditSnapshotOptions): Promise<A11yAuditResult>;
+export declare function createDeviceA11y(deps: DeviceA11yDeps): DeviceA11y & {
+    target: A11yTarget;
+};