@delacour/warden-e2e 0.0.0-stage → 0.1.1

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,61 @@
+import type { Result } from "../../types/src/result";
+/** The env names `warden e2e` writes and the spec process reads (`apps/cli` imports these). */
+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 flowsDir: "WARDEN_E2E_FLOWS_DIR";
+    readonly helperDir: "WARDEN_HELPER_DIR";
+    readonly simd: "WARDEN_SIMD";
+    readonly simdSocket: "WARDEN_SIMD_SOCKET";
+    readonly headless: "WARDEN_HEADLESS";
+    readonly logTimestamps: "WARDEN_LOG_TIMESTAMPS";
+    readonly worker: "WARDEN_WORKER";
+    /** the `warden` that started this process: the preload refuses to run when it is not this package's version */
+    readonly version: "WARDEN_VERSION";
+};
+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;
+    flowsDir?: string;
+    helperDir?: string;
+    simd?: string;
+    simdSocket?: string;
+    /** nothing in this package reads it: kept for specs and helpers that honour a headless run (`guides/headless`) */
+    headless: boolean;
+    /** warden already stamps the log lines: the spec reporter prints no clock of its own */
+    logTimestamps: boolean;
+    /** nothing in this package reads it: the 0-based worker index, for specs that shard or name per-worker data (`guides/e2e`) */
+    worker?: string;
+    /** `WARDEN_VERSION`: the warden that started this run */
+    wardenVersion?: 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";
+/** 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,34 @@
+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>/<flowId>/<title-slug>-<hash6>` of the running attempt */
+    readonly attemptDir?: 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,8 @@
+export type { OpenOptions, OpenWaitUntil } from "./app";
+export { E2eError } from "./errors";
+export { expect } from "./expect/expect";
+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/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 is a warning, not an
+ * error (most pairs still work), but the install fix is 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>/<flowId>/<title-slug>-<hash6>/` for one test attempt. */
+export declare function attemptDir(out: string, flowId: 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 `flowsDir` without extension (`auth/sign-in.e2e.ts` →
+ * `auth/sign-in`), segments slugged. A file outside `flowsDir` (or no `flowsDir`) uses its basename.
+ */
+export declare function flowIdOf(file: string, flowsDir?: 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,28 @@
+import type { DevtoolsFacet } from "../devtools/devtools.types";
+import type { Driver } from "../driver/driver.types";
+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>;

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

@@ -0,0 +1,60 @@
+import type { App } from "../app";
+import type { Device } from "../device";
+import type { Platform } from "../driver/driver.types";
+import type { E2eError } from "../errors";
+import type { Screen } from "../screen/screen";
+import type { Session } from "../session";
+import type { TraceWriter } from "./trace";
+export type { App, Device, Screen };
+/** What every test receives from the runner; `test.extend` adds to it. */
+export type TestFixtures = BaseFixtures;
+/** What every test receives; `test.extend` adds to it. */
+export type BaseFixtures = {
+    app: App;
+    device: Device;
+    screen: Screen;
+    platform: Platform;
+};
+export type LaunchMode = "fresh" | "none";
+/**
+ * `test.use({ systemAlerts })`: what to do when a read or wait sees an alert or sheet over the app (a permission
+ * prompt, "Open in …?", the Keychain "Save Password?" sheet, an app alert). `accept` / `dismiss` answer it with the
+ * buttons `device.alert("accept")` / `("dismiss")` press; `off` (the default) leaves it for the test.
+ */
+export type SystemAlerts = "accept" | "dismiss" | "off";
+export declare const SYSTEM_ALERTS: readonly SystemAlerts[];
+/** What a fixture factory gets for one attempt (or, for `beforeAll`/`afterAll`, the idle session). */
+export type FixtureContext = {
+    /**
+     * Inside an attempt, a view of the session bound to that attempt (`attemptSession`): its `signal`, `step`, `span`
+     * and `trace` stay that attempt's, so a fixture never acts in a later test.
+     */
+    session: Session;
+    /** aborts at the attempt deadline; every driver call and poll must honour it */
+    signal: AbortSignal;
+    launch: LaunchMode;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    /** absent = `off` */
+    systemAlerts?: SystemAlerts;
+};
+/**
+ * Builds `app`/`device`/`screen`. Registered on `session.fixtures` or via `setDefaultFixtureFactory`.
+ * The runner itself calls `app.open()` before the body when `launch` is `"fresh"`.
+ */
+export type FixtureFactory = (ctx: FixtureContext) => BaseFixtures | Promise<BaseFixtures>;
+/** The running attempt: where steps, screenshots and failure files go. Read it through the session. */
+export type AttemptContext = {
+    readonly signal: AbortSignal;
+    /** `<out>/<flowId>/<title-slug>-<hash6>/` */
+    readonly dir: string;
+    /** spec name tagging step lines */
+    readonly short: string;
+    readonly trace: TraceWriter;
+    /** nesting depth of the step in progress (indents console lines) */
+    depth: number;
+    /** files written into `dir`, relative to it (reported in `TestResult.artifacts`) */
+    readonly files: Set<string>;
+    /** failures kept by `expect.soft`; the attempt fails with all of them once the body has settled */
+    readonly softFailures: E2eError[];
+};

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+export declare const testStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    passed: "passed";
+    skipped: "skipped";
+    "timed-out": "timed-out";
+}>;
+export declare const testResultSchema: z.ZodObject<{
+    file: z.ZodString;
+    title: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+        "timed-out": "timed-out";
+    }>;
+    durationMs: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    only: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    artifacts: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    device: z.ZodObject<{
+        udid: z.ZodString;
+        platform: z.ZodEnum<{
+            ios: "ios";
+            android: "android";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TestResult = z.infer<typeof testResultSchema>;
+export type TestStatus = z.infer<typeof testStatusSchema>;
+export type ResultsWriter = {
+    readonly path: string;
+    /** one JSON line; `appendFileSync` so a crash right after never loses an earlier line */
+    append(result: TestResult): void;
+};
+/** Append-only `results.jsonl` writer; the directory is created on first use. */
+export declare function openResults(path: string): ResultsWriter;
+/** Valid results in file order. Blank, truncated (killed mid-write) and invalid lines are skipped. */
+export declare function readResults(text: string): TestResult[];

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

@@ -0,0 +1,62 @@
+import type { BaseFixtures, LaunchMode, SystemAlerts } from "./fixtures.types";
+/** Headroom over the test timeout so warden's `AbortSignal` deadline fires before bun's own. */
+export declare const BUN_TIMEOUT_MARGIN_MS = 30000;
+export type UseOptions = {
+    timeout?: number;
+    actionTimeout?: number;
+    assertionTimeout?: number;
+    launch?: LaunchMode;
+    /**
+     * Answer an alert or sheet over the app whenever a read or wait sees one (it already has the snapshot, so a screen
+     * without one costs nothing): `dismiss` presses what `device.alert("dismiss")` would, `accept` what `("accept")`
+     * would, `off` (default) leaves it. It also answers the app's own alerts, so a test that taps those buttons
+     * itself keeps it `off`.
+     */
+    systemAlerts?: SystemAlerts;
+};
+export type ResolvedUse = {
+    timeoutMs: number;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    launch: LaunchMode;
+    systemAlerts: SystemAlerts;
+};
+/** `beforeEach`/`afterEach` hooks get the base fixtures (bun's own hooks take no arguments). */
+export type Hook = (fixtures: BaseFixtures) => void | Promise<void>;
+export type Scope = {
+    /** describe titles from the root down to this scope */
+    readonly title: readonly string[];
+    readonly parent: Scope | undefined;
+    use: UseOptions;
+    readonly beforeEach: Hook[];
+    readonly afterEach: Hook[];
+    /** accepted for API parity: bun runs a file's tests serially unless `--concurrent` */
+    readonly serial: boolean;
+};
+/** The innermost `describe` being collected, else the root scope of the spec file making the call. */
+export declare function currentScope(): Scope;
+/**
+ * The scope of a `describe` call. Created when `describe()` is called — its parent is whatever is
+ * current then — because bun runs the callback later (nested ones after the parent's callback has
+ * returned), when the stack no longer says where it belongs.
+ */
+export declare function createScope(title: string, serial: boolean): Scope;
+/** Runs `body` (bun's `describe` callback) with `scope` current. */
+export declare function runInScope(scope: Scope, body: () => void): void;
+/** Root first, `scope` last. */
+export declare function scopeChain(scope: Scope): Scope[];
+/** `beforeEach`: outermost first. `afterEach`: innermost first. */
+export declare function hooksFor(scope: Scope, kind: "beforeEach" | "afterEach"): Hook[];
+/** Session defaults (env contract) under the nearest `test.use`, under the test's own `timeout`. */
+export declare function resolveUse(scope: Scope, defaults: Pick<ResolvedUse, "timeoutMs" | "actionTimeoutMs" | "assertionTimeoutMs">, testTimeout?: number): ResolvedUse;
+/** Timeouts known at collection time: the env when set, else the contract defaults. */
+export declare function registrationDefaults(env?: Readonly<Record<string, string | undefined>>): {
+    timeoutMs: number;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    platform: "ios" | "android" | undefined;
+};
+/** Records that a `.only` was collected (kept on `globalThis`: the preload and the specs may be separate bundles). */
+export declare function markOnly(): void;
+export declare function onlyWasSeen(): boolean;
+export declare function resetOnly(): void;