@delacour/warden-e2e 0.0.0-stage → 0.1.0

package/types/e2e/src/driver/typing.d.ts

@@ -0,0 +1,48 @@
+import type { Driver, DriverResult, KeyName } from "./driver.types";
+/**
+ * The one place that decides how text and keys are sent to a device (specs' `fill`/`type`/`clear` and `warden ui
+ * fill`/`type` all go through it).
+ *
+ * iOS: `warden-simd` holds, paces and spaces repeated keys itself (`WARDEN_SIMD_PACE_MS`, `WARDEN_SIMD_HOLD_MS`,
+ * `WARDEN_SIMD_REPEAT_GAP_MS`), so the whole string goes in one request and the client adds no gap. Before that
+ * the client sent one grapheme per request, 25 ms apart (set `KEY_PACE_MS` 25 and `SPLIT_TEXT` true to go back).
+ */
+/** Gap after each key on iOS. */
+export declare const KEY_PACE_MS = 0;
+/** iOS types one grapheme per request. */
+export declare const SPLIT_TEXT = false;
+export type Sleep = (ms: number) => Promise<void>;
+/**
+ * Optional fast path a driver can offer next to the frozen `Driver` interface: `times` presses of `key` in one
+ * device round trip. Android needs it because every `input keyevent` is a process start (clearing a 20 character
+ * field one key at a time takes seconds); iOS paces keys itself.
+ */
+export type RepeatingKeys = {
+    pressKeyRepeat(key: KeyName, times: number): DriverResult<void>;
+};
+export declare function canRepeatKeys(driver: Driver): driver is Driver & RepeatingKeys;
+/**
+ * Optional fast path next to the frozen `Driver`: select everything in the focused text field (iOS Cmd+A through
+ * `warden-simd`, Android Ctrl+A through `input keycombination` on API 33+), so one Backspace empties a field of any
+ * length instead of one per character. A field that refuses the shortcut is caught by the read-back after the fill.
+ */
+export type SelectsAll = {
+    selectAll(): DriverResult<void>;
+};
+export declare function canSelectAll(driver: Driver): driver is Driver & SelectsAll;
+/**
+ * Optional fast path next to the frozen `Driver`: replace the whole text of the focused field in one call (Android
+ * `warden-uiad` `setText`, `ACTION_SET_TEXT`: the same action its `typeText` inserts with). `screen/field.ts` uses it,
+ * opt-in only (`ClearMethod` `setText`, or `WARDEN_ANDROID_SETTEXT=1`), for a `fill` over a field that holds text,
+ * instead of select-all then typing; the read-back checks it took. A refusal (no server, no focused input) is an error,
+ * and the caller types the old way. Opt-in because the server writes to the node its cached focus names, which may
+ * still be the field focused before the tap.
+ */
+export type SetsText = {
+    setText(text: string): DriverResult<void>;
+};
+export declare function canSetText(driver: Driver): driver is Driver & SetsText;
+/** Types `text` at the caret. Android types the whole string in one call. */
+export declare function typeText(driver: Driver, sleep: Sleep, text: string): DriverResult<void>;
+/** Presses `key` `times` times, paced like typed characters. */
+export declare function pressKeys(driver: Driver, sleep: Sleep, key: KeyName, times: number): DriverResult<void>;

package/types/e2e/src/driver/unwrap.d.ts

@@ -0,0 +1,13 @@
+import type { Result } from "../../../types/src/result";
+import { E2eError } from "../errors";
+import type { DriverError, DriverResult } from "./driver.types";
+/** `TIMEOUT` for time limits, `DRIVER` when the helper / device is broken, else `ACTION_FAILED`. */
+export declare function toE2eError(error: DriverError, action: string): E2eError;
+/**
+ * Runs one driver call, racing it against `signal`: an already-aborted signal never starts the call,
+ * an abort while it runs rejects with `E2eError{TIMEOUT}`. Returns the raw `Result` (use {@link unwrap}
+ * when a failure should throw).
+ */
+export declare function settled<T>(call: () => DriverResult<T>, action: string, signal?: AbortSignal): Promise<Result<T, DriverError>>;
+/** {@link settled}, throwing the mapped `E2eError` (see {@link toE2eError}) on a driver failure. */
+export declare function unwrap<T>(call: () => DriverResult<T>, action: string, signal?: AbortSignal): Promise<T>;

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

@@ -0,0 +1,78 @@
+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
+ * `WARDEN_WORKER` are also set for the spec process but are for the spec's own tools (`process.env`): nothing here
+ * reads them, so a bad value cannot fail spec-env validation.
+ */
+export declare const ENV_NAMES: {
+    readonly udid: "WARDEN_UDID";
+    readonly deviceName: "WARDEN_DEVICE_NAME";
+    readonly platform: "WARDEN_PLATFORM";
+    readonly bundleId: "WARDEN_BUNDLE_ID";
+    readonly appPath: "WARDEN_APP_PATH";
+    readonly metroUrl: "WARDEN_METRO_URL";
+    readonly launchArgs: "WARDEN_LAUNCH_ARGS";
+    readonly out: "WARDEN_E2E_OUT";
+    readonly timeout: "WARDEN_E2E_TIMEOUT";
+    readonly actionTimeout: "WARDEN_E2E_ACTION_TIMEOUT";
+    readonly assertionTimeout: "WARDEN_E2E_ASSERTION_TIMEOUT";
+    readonly specsDir: "WARDEN_E2E_SPECS_DIR";
+    readonly helperDir: "WARDEN_HELPER_DIR";
+    readonly simd: "WARDEN_SIMD";
+    readonly simdSocket: "WARDEN_SIMD_SOCKET";
+    readonly logTimestamps: "WARDEN_LOG_TIMESTAMPS";
+    /**
+     * 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)
+     */
+    readonly afterReboot: "WARDEN_AFTER_REBOOT";
+    /** the `warden` that started this process: the preload refuses to run when it is not this package's version */
+    readonly version: "WARDEN_VERSION";
+    /** JSON argv that re-runs the `warden` that started this process (`device.perf` shells out to it) */
+    readonly bin: "WARDEN_BIN";
+    /** `warden e2e --perf`: the capture flags (`all`, or a comma list like `react,js`) every attempt records */
+    readonly perf: "WARDEN_PERF";
+    /** JSON of the suite's `perf.budgets`; a breach fails the test with `PERF_BUDGET` */
+    readonly perfBudgets: "WARDEN_PERF_BUDGETS";
+};
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare const DEFAULT_ACTION_TIMEOUT_MS = 30000;
+export declare const DEFAULT_ASSERTION_TIMEOUT_MS = 5000;
+export type E2eEnv = {
+    udid: string;
+    /** the leased device's name: pins devtools to its own Metro inspector page when several devices share one Metro */
+    deviceName?: string;
+    platform: "ios" | "android";
+    bundleId: string;
+    appPath?: string;
+    metroUrl?: string;
+    launchArgs: string[];
+    /** where `results.jsonl` and per-attempt artifacts go (may be relative to cwd) */
+    out: string;
+    timeoutMs: number;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    specsDir?: string;
+    helperDir?: string;
+    simd?: string;
+    simdSocket?: 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`) */
+    afterReboot?: string[];
+    /** `WARDEN_VERSION`: the warden that started this run */
+    wardenVersion?: string;
+    /** `WARDEN_BIN`: argv of the `warden` that started this run */
+    wardenBin?: string[];
+    /** `WARDEN_PERF`: capture names every attempt records (`all`, `react`, `js`…) */
+    perf?: string[];
+    /** `WARDEN_PERF_BUDGETS`: raw JSON of the suite's budgets */
+    perfBudgets?: string;
+};
+/**
+ * Reads the spec env contract. `undefined` data = not running under warden (no `WARDEN_UDID`); an
+ * error lists every invalid variable by its env name. Empty values count as unset.
+ */
+export declare function readEnv(env: Readonly<Record<string, string | undefined>>, opts?: {
+    now?: () => Date;
+}): Result<E2eEnv | undefined>;

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

@@ -0,0 +1,26 @@
+import type { ErrorResult } from "../../types/src/result";
+export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET";
+/** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
+export type E2eErrorShape = {
+    code: E2eErrorCode;
+    message: string;
+    /** text render of the accessibility tree at the moment of failure, when the caller had one */
+    screen?: string;
+    /** number of candidates for `LOCATOR_AMBIGUOUS` */
+    matches?: number;
+};
+/**
+ * Every failure a spec can see (`screen`, `expect`, `test`, session), discriminated by `code`.
+ * A thrown class so specs can `instanceof` it; `e2eErr()` wraps one in a failed `Result`.
+ */
+export declare class E2eError extends Error implements E2eErrorShape {
+    readonly code: E2eErrorCode;
+    readonly screen?: string;
+    readonly matches?: number;
+    constructor(code: E2eErrorCode, message: string, screen?: string, matches?: number);
+    static from(shape: E2eErrorShape): E2eError;
+}
+/** `err()` for results carrying an `E2eError`. */
+export declare function e2eErr(error: E2eErrorShape): ErrorResult<E2eError>;
+/** One line for logs and thrown messages: `CODE: message`. */
+export declare function describeE2eError(error: E2eErrorShape): string;

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

@@ -0,0 +1,27 @@
+import { type Expect as BunExpect, type Matchers } from "bun:test";
+import { E2eError } from "../errors";
+import { type Locator } from "../screen/locator";
+import { type Session } from "../session";
+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;
+    <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`
+ * (all of its statics — `any`, `arrayContaining`, `extend`, `not`, … — are on it too).
+ */
+export type E2eExpect = ((actual: Locator) => LocatorAssertions) & BunExpect & {
+    readonly soft: SoftExpect;
+};
+export type ExpectDeps = {
+    /** where `expect.soft` keeps failures right now; undefined (outside an attempt) means throw as usual */
+    softSink: () => SoftSink | undefined;
+};
+/** The running attempt's collector (`AttemptContext.softFailures`), if a test is running. */
+export declare function softSinkFor(session: Pick<Session, "attempt">): SoftSink | undefined;
+export declare function createExpect(deps: ExpectDeps): E2eExpect;
+export declare const expect: E2eExpect;

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

@@ -0,0 +1,72 @@
+import { E2eError } from "../errors";
+import { type Locator } from "../screen/locator";
+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).
+ *
+ * It can end sooner: once the condition held on one poll, a driver with native settle (iOS `axbridge`, Android
+ * `warden-uiad`: both watch the app's own activity stream, ~250-300 ms) is asked once whether the screen is quiet
+ * (`NEGATION_QUIET_MS`, bounded by what is left of the hold). If it is, one fresh poll that still holds passes. A screen
+ * that is quiet but about to change by itself (a toast after a timer) can therefore pass before that change, where the
+ * full hold would have seen it. Without native settle the hold stays plain: there, knowing the screen is quiet means
+ * polled snapshots or a `uiautomator dump` (~1.9 s), longer than the window it would save.
+ *
+ * The settle is asked only when no input came within the last `NEGATION_GRACE_MS` (the observation cache's
+ * `sinceInputMs`; no input yet counts as none). A quiet app is not a settled one right after a tap: a submit waiting on
+ * the network is idle until the reply comes, so `submit.tap()` then `expect(error).not.toBeVisible()` keeps the full
+ * hold, which sees an error that comes within it. Without the cache the time of the last input is unknown: plain hold.
+ * Input is every driver call that is not a read, the matcher's own native settle included (so a second `.not` right
+ * after one that ended early holds the full time). Devtools calls (`device.devtools.evaluate`, `reloadJs`) go to Metro,
+ * not the driver, so they do not count: a `.not` right after one may end early. Tap, `wait` or assert something
+ * positive first.
+ */
+export declare const NEGATION_GRACE_MS = 1000;
+/** The quiet window a negated matcher asks the driver for before it ends its hold early. */
+export declare const NEGATION_QUIET_MS = 250;
+export type AssertionOptions = {
+    timeout?: number;
+};
+export type TextAssertionOptions = AssertionOptions & {
+    exact?: boolean;
+};
+export type ContainAssertionOptions = AssertionOptions & {
+    ignoreCase?: boolean;
+};
+export type CheckedOptions = AssertionOptions & {
+    checked?: boolean;
+};
+export type AssertionContext = {
+    negate: boolean;
+    /** collects a failure instead of throwing it (`expect.soft`) */
+    soft?: (error: E2eError) => void;
+};
+/**
+ * The locator matchers of `expect(locator)`. Each one polls (100 ms apart for the first second, then 250 ms) until its
+ * condition holds or the assertion timeout passes, then fails with `ASSERTION`. `.not` inverts the condition (and must
+ * see it hold for a grace window; the polls land exactly on its end).
+ * Except `toHaveCount`, a matcher needs exactly one match: none keeps polling, several fail at once.
+ */
+export declare class LocatorAssertions {
+    private readonly locator;
+    private readonly context;
+    constructor(locator: Locator, context: AssertionContext);
+    get not(): LocatorAssertions;
+    toBeVisible(options?: AssertionOptions): Promise<void>;
+    toBeHidden(options?: AssertionOptions): Promise<void>;
+    /** Whole-text after whitespace normalisation (`exact: false`: a case-insensitive substring); a RegExp as written. */
+    toHaveText(expected: TextMatch, options?: TextAssertionOptions): Promise<void>;
+    /** The (normalised) text contains the string, case-sensitively unless `ignoreCase`; a RegExp is tested as written. */
+    toContainText(expected: TextMatch, options?: ContainAssertionOptions): Promise<void>;
+    /** The field value as it is (no whitespace normalisation). Secure fields cannot be judged. */
+    toHaveValue(expected: TextMatch, options?: AssertionOptions): Promise<void>;
+    /** Checked by default; `{ checked: false }` expects unchecked. A node that is not checkable counts as unchecked. */
+    toBeChecked(options?: CheckedOptions): Promise<void>;
+    toBeEnabled(options?: AssertionOptions): Promise<void>;
+    toBeDisabled(options?: AssertionOptions): Promise<void>;
+    /** Exactly `expected` current matches (zero included). */
+    toHaveCount(expected: number, options?: AssertionOptions): Promise<void>;
+    private assert;
+    private poll;
+    /** The screen is rendered here, from the last snapshot read, because only a failure needs the text. */
+    private failure;
+}

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

@@ -0,0 +1,38 @@
+import type { DevtoolsFacet, DevtoolsResult } from "./devtools/devtools.types";
+import type { SpanRunner } from "./runner/span";
+import type { TraceEvent } from "./runner/trace";
+/**
+ * What the `app` / `device` fixtures need from the session. `Session` satisfies it structurally;
+ * the runner (T3) mutates `signal`, `attemptDir` and `trace` per attempt, so fixtures read them at
+ * call time, never at construction.
+ */
+export type FixtureSession = {
+    /** absolute `WARDEN_E2E_OUT` (screenshot fallback when no attempt is running) */
+    readonly out: 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 */
+    readonly attemptDir?: string;
+    /** the running attempt's recorded files (`device.perf` adds its `perf/` ones) */
+    readonly attempt?: {
+        readonly files: Set<string>;
+    };
+    /** the running attempt's `trace.jsonl` */
+    readonly trace?: {
+        write(event: TraceEvent): void;
+    };
+    /** one reported step (`▸`/`▪` lines, `trace.jsonl`) that gives up when the attempt deadline aborts; absent = just run it */
+    step?<T>(kind: string, label: string, fn: () => Promise<T>): Promise<T>;
+    /** times one call as a trace-only `span` (`device.*`, `read.*`); absent = untraced */
+    span?: SpanRunner;
+    /** attaches the app's devtools on first call (the session shares one connection); absent = no devtools */
+    devtools?(): Promise<DevtoolsResult<DevtoolsFacet>>;
+    /** the facet if already attached; never attaches */
+    peekDevtools?(): DevtoolsFacet | undefined;
+};
+/** Injected time: tests drive a fake clock. */
+export type Clock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare const systemClock: Clock;

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

@@ -0,0 +1,14 @@
+import { type Device } from "./device";
+import type { BaseFixtures, FixtureContext } from "./runner/fixtures.types";
+import type { ScreenHost } from "./screen/context";
+/**
+ * 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.
+ */
+export declare function screenHostFor(ctx: FixtureContext, device?: Pick<Device, "alert">): ScreenHost;
+/**
+ * The `app` / `device` / `screen` / `platform` every test gets, over the session's driver. `device` calls and
+ * locator reads are trace-only spans (`device.*`, `read.*`); the driver's own calls are `driver.*` spans (the session
+ * traces its driver).
+ */
+export declare function defaultFixtureFactory(ctx: FixtureContext): Promise<BaseFixtures>;

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

@@ -0,0 +1,11 @@
+export type { OpenOptions, OpenWaitUntil } from "./app";
+export { E2eError } from "./errors";
+export { expect } from "./expect/expect";
+export type { PerfBreach, PerfBudgets } from "./perf/budgets";
+export type { DevicePerf } from "./perf/device-perf";
+export type { PerfMetrics, PerfReport, PerfStartOptions } from "./perf/perf.types";
+export type { App, Device, Screen, SystemAlerts, TestFixtures } from "./runner/fixtures.types";
+export { afterAll, afterEach, beforeAll, beforeEach, describe, test } from "./runner/test";
+export type { Locator, LocatorReading, PinchOptions, RotateOptions, TapOptions, TapUntil } from "./screen/locator";
+export type { ScreenGestures, ScreenPathOptions, ScreenPinchOptions, ScreenRotateOptions, } from "./screen/screen";
+export { WARDEN_E2E_VERSION } from "./version";

package/types/e2e/src/perf/budgets.d.ts

@@ -0,0 +1,33 @@
+import type { PerfReport } from "./perf.types";
+/** Ceilings a perf report must stay under; every field is optional and lower-is-better. */
+export type PerfBudgets = {
+    /** cold start, ms */
+    startupColdMs?: number;
+    /** share of janky frames, percent */
+    jankPct?: number;
+    /** the slowest React commit, ms */
+    maxCommitMs?: number;
+    /** 95th percentile app CPU, percent */
+    p95CpuPct?: number;
+    /** peak memory (PSS on Android, RSS on iOS), MB */
+    peakMemoryMb?: number;
+};
+export declare const BUDGET_KEYS: readonly ["startupColdMs", "jankPct", "maxCommitMs", "p95CpuPct", "peakMemoryMb"];
+export type BudgetKey = (typeof BUDGET_KEYS)[number];
+/** One metric over its ceiling. */
+export type PerfBreach = {
+    metric: BudgetKey;
+    value: number;
+    budget: number;
+};
+/** What the report measured for `metric`, or `undefined` when its capture did not run. */
+export declare function measured(report: Pick<PerfReport, "metrics">, metric: BudgetKey): number | undefined;
+/**
+ * Budgets set in `overrides` replace the same key of `base` (config); a metric the report has no number for (its
+ * capture did not run) cannot breach.
+ */
+export declare function checkBudgets(report: Pick<PerfReport, "metrics">, base: PerfBudgets | undefined, overrides?: PerfBudgets): PerfBreach[];
+/** The failure text: each breach, then where the full report is. */
+export declare function describeBreaches(breaches: readonly PerfBreach[], reportPath: string | undefined): string;
+/** Parses the `WARDEN_PERF_BUDGETS` JSON warden writes; unknown keys and non-numbers are dropped. */
+export declare function parseBudgets(raw: string | undefined): PerfBudgets;

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

@@ -0,0 +1,45 @@
+import { type PerfBudgets } from "./budgets";
+import type { PerfReport, PerfStartOptions } from "./perf.types";
+/** One `warden` invocation: argv (without the warden command itself) in, exit code and streams out. */
+export type PerfExec = (argv: readonly string[]) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Subdirectory of the attempt dir a perf session's report is copied to. */
+export declare const PERF_DIR = "perf";
+export type DevicePerf = {
+    /** opens a perf session on this device; one per device at a time */
+    start(options?: PerfStartOptions): Promise<{
+        sessionId: string;
+    }>;
+    /** drops a label on the session timeline; commits, hangs and jank are tagged with the last mark before them */
+    mark(label: string): Promise<void>;
+    /**
+     * Ends the session and returns its report (`reportPath` is the copy under the attempt's `perf/`). Throws
+     * `PERF_BUDGET` when a metric is over the suite's budget (`warden.config.ts` `perf.budgets`) or `budgets`, which
+     * replaces the suite's per key.
+     */
+    stop(options?: {
+        budgets?: PerfBudgets;
+    }): Promise<PerfReport>;
+    /** a session this device opened and has not stopped */
+    readonly active: boolean;
+};
+export type DevicePerfDeps = {
+    exec: PerfExec;
+    udid: string;
+    /** budgets of the suite (`WARDEN_PERF_BUDGETS`) */
+    budgets: PerfBudgets;
+    /** the running attempt's dir; absent outside an attempt (the report stays in the session dir) */
+    attemptDir: () => string | undefined;
+    /** records a file written into the attempt dir (relative path) so `results.jsonl` lists it */
+    addFile?: (relative: string) => void;
+    /** `warden` is not reachable (no `WARDEN_BIN`) */
+    unavailable?: string;
+};
+export declare function createDevicePerf(deps: DevicePerfDeps): DevicePerf;
+/** `--perf=react,js` (or `all`) as the options `perf.start` takes; an unknown name is ignored, none named = warden's default set. */
+export declare function perfStartFor(names: readonly string[]): PerfStartOptions;
+/** Runs the `warden` that started the spec process (`WARDEN_BIN`). */
+export declare function spawnWarden(bin: readonly string[] | undefined): PerfExec;

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

@@ -0,0 +1,59 @@
+/** The capture switches `device.perf.start` takes (the `warden perf start` flags of the same name). */
+export type PerfStartOptions = {
+    js?: boolean;
+    react?: boolean;
+    native?: boolean | "perfetto" | "simpleperf";
+    metrics?: boolean;
+    frames?: boolean;
+    logs?: boolean;
+    all?: boolean;
+    /** stop the app, arm the captures, launch it: startup and early JS/React are recorded */
+    relaunch?: boolean;
+    /** like `relaunch`, but wipe the app's data first */
+    reset?: boolean;
+    /** hard cap on the session; warden's default is 30 s, the maximum 5 min */
+    maxDurationMs?: number;
+};
+/** The numbers of a report, each lower-is-better (the `metrics` of `report.json`). */
+export type PerfMetrics = {
+    startupColdMs?: number;
+    startupWarmMs?: number;
+    jankPct?: number;
+    fps?: number;
+    cpuP95Pct?: number;
+    peakPssKb?: number;
+    peakRssKb?: number;
+    /** the slowest React commit */
+    topCommitMs?: number;
+    hangCount?: number;
+    hangTotalMs?: number;
+    topFunctions: Array<{
+        name: string;
+        selfPct: number;
+    }>;
+};
+/** `report.json` of a perf session, as far as a spec reads it (the full document is at `reportPath`). */
+export type PerfReport = {
+    version: 1;
+    sessionId: string;
+    app?: string;
+    durationMs: number;
+    stopReason?: string;
+    banners: string[];
+    summary: string[];
+    findings: Array<{
+        kind: string;
+        severity: string;
+        costMs: number;
+        evidence: string;
+        fix: string;
+    }>;
+    metrics: PerfMetrics;
+    marks: Array<{
+        label: string;
+        atMs: number;
+    }>;
+    next: string[];
+    /** where `report.json` is (inside the attempt's `perf/` dir when the spec runs under `warden e2e`) */
+    reportPath?: string;
+};

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

@@ -0,0 +1,29 @@
+import { BUN_TIMEOUT_MARGIN_MS } from "./runner/scope";
+import { getSession } from "./session";
+export { BUN_TIMEOUT_MARGIN_MS };
+export type PreloadDeps = {
+    env: Readonly<Record<string, string | undefined>>;
+    setDefaultTimeout: (ms: number) => void;
+    afterAll: (fn: () => Promise<void>) => void;
+    createSession: typeof getSession;
+    /** this package's version (`WARDEN_E2E_VERSION`) */
+    version: string;
+    /** whether a `test.only` was collected */
+    onlySeen: () => boolean;
+    stderr: (text: string) => void;
+    exit: (code: number) => void;
+};
+/**
+ * The protocol handshake: `warden e2e` and this package version in lock-step. A mismatch refuses the run (exit 2)
+ * with the install fix spelled out. Nothing to compare without `WARDEN_VERSION`
+ * (a by-hand run) or from the workspace sources (not a published build).
+ */
+export declare function versionMismatch(wardenVersion: string | undefined, e2eVersion: string): string | undefined;
+/** `CI=1`, `CI=true`, … — anything but empty, `0` and `false`. */
+export declare function isCi(env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * `bun test --preload`: a no-op without `WARDEN_UDID` (safe in `bunfig.toml`); otherwise validates
+ * the env (exit 2 when invalid), raises bun's default timeout above the test timeout, opens the
+ * session eagerly and, in `afterAll`, closes it and (under `CI`) fails the run if a `.only` was collected.
+ */
+export declare function installPreload(deps: PreloadDeps): void;

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

@@ -0,0 +1,13 @@
+/** Lowercase, runs of non-alphanumerics become `-`, trimmed, capped at 60 chars; `fallback` when empty. */
+export declare function slug(text: string, fallback?: string): string;
+/** First 6 hex chars of a sha1 over the parts: keeps equal slugs from colliding. */
+export declare function hash6(...parts: string[]): string;
+/** `<out>/<specId>/<title-slug>-<hash6>/` for one test attempt. */
+export declare function attemptDir(out: string, specId: string, title: readonly string[], hash: string): string;
+/** `<dir>/screenshots/NNN-name.png` (3-digit, 1-based order). */
+export declare function screenshotPath(dir: string, n: number, name: string): string;
+/**
+ * Stable per-file id: the path under `specsDir` without extension (`auth/sign-in.e2e.ts` →
+ * `auth/sign-in`), segments slugged. A file outside `specsDir` (or no `specsDir`) uses its basename.
+ */
+export declare function specIdOf(file: string, specsDir?: string): string;

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

@@ -0,0 +1,63 @@
+import { E2eError } from "../errors";
+import { type Session } from "../session";
+import type { BaseFixtures } from "./fixtures.types";
+import { type ResolvedUse, type Scope } from "./scope";
+/** Longest one hook or fixture teardown may take once the test itself is over. */
+export declare const CLEANUP_TIMEOUT_MS = 10000;
+/** Part of bun's margin the runner never spends after a deadline: the `■` line and the results line still need it. */
+export declare const POST_DEADLINE_RESERVE_MS = 5000;
+/** The runner's own time limits around a test body (see {@link setRunnerTiming}). */
+export type RunnerTiming = {
+    /** longest one `afterEach` hook or fixture teardown may take ({@link CLEANUP_TIMEOUT_MS}) */
+    cleanupTimeoutMs: number;
+    /** longest one failure capture call may take (`CAPTURE_TIMEOUT_MS`) */
+    captureTimeoutMs: number;
+    /** what bun's own per-test timeout adds over warden's deadline (`BUN_TIMEOUT_MARGIN_MS`) */
+    bunMarginMs: number;
+    /** part of that margin left unspent ({@link POST_DEADLINE_RESERVE_MS}) */
+    reserveMs: number;
+};
+export declare function runnerTiming(): Readonly<RunnerTiming>;
+/**
+ * Test seam: a runner fixture spec shrinks the limits (before it registers its tests) so a slow-cleanup case runs
+ * in milliseconds. `undefined` restores the defaults.
+ */
+export declare function setRunnerTiming(next: Partial<RunnerTiming> | undefined): void;
+/** `test.extend` fixture: set up, `use(value)`, and everything after `use` is the teardown. */
+export type FixtureSetup = (base: Record<string, unknown>, use: (value: unknown) => Promise<void>) => Promise<void>;
+export type FixtureEntry = {
+    name: string;
+    setup: FixtureSetup;
+};
+export type AttemptSpec<F extends object> = {
+    /** absolute path of the spec file */
+    file: string;
+    /** describe titles, then the test title */
+    title: readonly string[];
+    scope: Scope;
+    fixtures: readonly FixtureEntry[];
+    body: (fixtures: F) => void | Promise<void>;
+    /** per-test `timeout` option (beats `test.use`) */
+    timeout?: number;
+    only: boolean;
+    /** no retries left: only a final (or passing) attempt appends to `results.jsonl` */
+    final: boolean;
+    /** bun's own timeout for this test, fixed when it was registered (default: the resolved timeout + bun's margin) */
+    bunTimeoutMs?: number;
+};
+/** `app`/`device`/`screen`/`platform` from the session's factory (throwing stand-ins when none is registered). */
+export declare function buildBaseFixtures(session: Session, signal: AbortSignal, use: ResolvedUse): Promise<BaseFixtures>;
+/**
+ * When the runner must be done with an attempt: bun's own timeout for the test (or the resolved timeout plus bun's
+ * margin, if that is sooner) minus the reserve. Failure capture, `afterEach` hooks and fixture teardowns all spend
+ * from this one budget, so bun never gives up on a test (and starts the next one) while its cleanup still runs.
+ */
+export declare function cleanupDeadline(startedAt: number, timeoutMs: number, bunTimeoutMs: number | undefined): number;
+/**
+ * One attempt of one test: deadline (`AbortSignal`), fixtures, `beforeEach`, body, then — whatever
+ * happened — failure capture, `afterEach`, fixture teardown (reverse order), the `■` line and the
+ * `results.jsonl` line. Throws the test's own error so bun marks the test failed.
+ */
+export declare function runAttempt<F extends object>(session: Session, spec: AttemptSpec<F>): Promise<void>;
+/** One error for every `expect.soft` failure of the attempt. */
+export declare function softFailureError(failures: readonly E2eError[]): E2eError;

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

@@ -0,0 +1,2 @@
+/** 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;

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

@@ -0,0 +1,40 @@
+import type { DevtoolsFacet } from "../devtools/devtools.types";
+import { type NativeLogDeps, type NativeTarget } from "../devtools/native-log";
+import type { Driver } from "../driver/driver.types";
+import type { E2eEnv } from "../env";
+export declare const FAILURE_PNG = "failure.png";
+export declare const SCREEN_AT_FAILURE = "screen-at-failure.txt";
+export declare const CONSOLE_JSONL = "console.jsonl";
+export declare const NETWORK_JSONL = "network.jsonl";
+/** Longest a single capture call may take: a wedged device must not hold the test run. */
+export declare const CAPTURE_TIMEOUT_MS = 10000;
+/** What is left of the runner's post-deadline budget, in ms; the default never runs out. */
+export type CaptureBudget = () => number;
+export type FailureCapture = {
+    /** files written into `dir`, relative to it */
+    files: string[];
+    /** what could not be captured, for the trace */
+    problems: string[];
+};
+/**
+ * Best-effort `failure.png` (`driver.screenshot`) and `screen-at-failure.txt` (`driver.snapshot`,
+ * rendered like `warden ui snapshot --all`) into `dir`. Never throws: the test's own error is
+ * the one worth reporting. Each call gets `timeoutMs` or what `budget` says is left, whichever is less; a
+ * screenshot that timed out skips the snapshot (the device is not answering).
+ */
+export declare function captureFailure(driver: Driver, dir: string, timeoutMs?: number, budget?: CaptureBudget): Promise<FailureCapture>;
+/**
+ * `console.jsonl` and `network.jsonl` of the app's attached devtools into `dir`. Best effort like
+ * {@link captureFailure}: never throws, gives up after `timeoutMs` (the network drain talks to the page).
+ */
+export declare function captureDevtoolsArtifacts(facet: DevtoolsFacet, dir: string, timeoutMs?: number, budget?: CaptureBudget): Promise<FailureCapture>;
+/** The app a failed attempt ran, from the run's env. */
+export declare function nativeTarget(env: Pick<E2eEnv, "platform" | "udid" | "bundleId">): NativeTarget;
+/**
+ * `native.log` (+ iOS `.ips` crash reports) of the failed attempt, see {@link captureNativeLog}. Best effort
+ * like {@link captureFailure}: never throws, limited by `timeoutMs` and what `budget` has left.
+ */
+export declare function captureNativeArtifacts(target: NativeTarget, deps: NativeLogDeps, win: {
+    dir: string;
+    sinceMs: number;
+}, timeoutMs?: number, budget?: CaptureBudget): Promise<FailureCapture>;