@delacour/warden-e2e 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,61 @@
+import type { Point } from "../driver/driver.types";
+import { type Momentum, type SwipeDirection } from "./actions";
+import { type ScreenHost } from "./context";
+import { type ActionOptions, Locator, type ScrollOptions } from "./locator";
+import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
+import type { QueryRole } from "./roles";
+import type { TextMatch } from "./text";
+export type ScreenSwipeOptions = {
+    direction: SwipeDirection;
+    momentum?: Momentum;
+} | {
+    from: Point;
+    to: Point;
+    durationMs?: number;
+};
+export type ScreenPinchOptions = {
+    scale: number;
+    center?: Point;
+    radius?: number;
+    durationMs?: number;
+};
+export type ScreenRotateOptions = {
+    degrees: number;
+    center?: Point;
+    radius?: number;
+    durationMs?: number;
+};
+/**
+ * `paths` are 1-2 fingers' routes in screen points, each with at least one finite point (give two or more for a
+ * real path; a single point is a held touch). More fingers than the driver's `capabilities.maxPointers` is `INVALID_ARGUMENT`.
+ */
+export type ScreenPathOptions = {
+    paths: readonly (readonly Point[])[];
+    durationMs?: number;
+};
+/** Viewport-level gestures; `screen.swipe` is the same as `screen.gesture.swipe`. */
+export type ScreenGestures = {
+    /** pinch about the screen centre (or `center`); `scale` above 1 zooms in */
+    pinch(options: ScreenPinchOptions): Promise<void>;
+    /** rotate about the screen centre (or `center`); positive `degrees` turn clockwise */
+    rotate(options: ScreenRotateOptions): Promise<void>;
+    /** replay 1-2 finger paths on one timeline; no observation, coordinates are used as given */
+    path(options: ScreenPathOptions): Promise<void>;
+    swipe(options: ScreenSwipeOptions): Promise<void>;
+};
+/** The `screen` of the spec API: lazy queries over the device, plus viewport-level gestures. */
+export type Screen = {
+    getByTestId(id: TextMatch, options?: TestIdOptions): Locator;
+    getByText(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByLabel(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByPlaceholder(text: TextMatch, options?: TextQueryOptions): Locator;
+    getByValue(value: TextMatch, options?: TextQueryOptions): Locator;
+    getByRole(role: QueryRole, nameOrOptions?: TextMatch | RoleOptions, options?: Omit<RoleOptions, "name">): Locator;
+    /** the agent-CLI selector grammar: `locator("id=sign-in role=button nth=1")` */
+    locator(selector: string): Locator;
+    tapAt(point: Point, options?: ActionOptions): Promise<void>;
+    swipe(options: ScreenSwipeOptions): Promise<void>;
+    gesture: ScreenGestures;
+    scrollUntilVisible(target: Locator, options?: ScrollOptions): Promise<void>;
+};
+export declare function createScreen(host: ScreenHost): Screen;

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

@@ -0,0 +1,38 @@
+import { type Result } from "../../../types/src/result";
+import type { NodeEntry } from "./nodes";
+import type { LocatorExpression } from "./query";
+/** A selector value: literal text (bare or quoted on the wire) or a regular expression. */
+export type SelectorValue = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "regex";
+    source: string;
+    flags: string;
+};
+/**
+ * The agent-CLI selector grammar: `id=<v> label=<v> text=<v> role=<v> value=<v> editable=true|false nth=<i>`.
+ * `id` is exact; `label`, `text` and `value` are case-insensitive substrings; a regex is applied as written.
+ */
+export type ParsedSelector = {
+    id?: SelectorValue;
+    label?: SelectorValue;
+    text?: SelectorValue;
+    role?: SelectorValue;
+    value?: SelectorValue;
+    editable?: boolean;
+    nth?: number;
+};
+/** Parses `id=x label="Sign in" text=/regex/i role=button editable=true nth=1`. */
+export declare function parseSelector(input: string): Result<ParsedSelector>;
+/** The canonical text for a selector; `parseSelector(formatSelector(s))` equals `s`. */
+export declare function formatSelector(selector: ParsedSelector): string;
+/** The expression a selector stands for: one selector query, wrapped in `nth` when given. */
+export declare function selectorToQuery(selector: ParsedSelector): LocatorExpression;
+/** One node against one parsed selector (`nth` is not part of matching; see `selectorToQuery`). */
+export declare function matchesSelector(entry: NodeEntry, selector: ParsedSelector): boolean;
+/**
+ * Picks the target of an action among several matches: visible first, then the most exact text terms, then the smallest
+ * frame, then reading order.
+ */
+export declare function pickMostSpecific(matches: readonly NodeEntry[], selector: ParsedSelector): NodeEntry | undefined;

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

@@ -0,0 +1,13 @@
+/** A string (whole-text, or substring with `exact:false`) or a RegExp applied as written. */
+export type TextMatch = string | RegExp;
+export type TextMatchOptions = {
+    exact?: boolean;
+};
+/** Collapses every whitespace run (including no-break spaces) to one space and trims. */
+export declare function normalizeText(text: string): string;
+/**
+ * Whether `value` satisfies `match`. A string must equal the whole text after whitespace normalisation (case-sensitive);
+ * `exact:false` turns it into a case-insensitive substring. A RegExp is tested as written against the normalised value
+ * (its `g`/`y` flags are dropped so repeated calls are not stateful).
+ */
+export declare function matchesText(value: string, match: TextMatch, options?: TextMatchOptions): boolean;

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

@@ -0,0 +1,124 @@
+import { type DevtoolsFacet, type DevtoolsResult } from "./devtools/devtools.types";
+import type { NativeLogDeps } from "./devtools/native-log";
+import type { Driver, DriverResult } from "./driver/driver.types";
+import { type HidRecoveryDeps } from "./driver/ios/hid-recovery";
+import { type E2eEnv } from "./env";
+import type { AttemptContext, FixtureFactory } from "./runner/fixtures.types";
+import { type ResultsWriter } from "./runner/results";
+import { type SpanRunner } from "./runner/span";
+import type { TraceWriter } from "./runner/trace";
+export type DriverFactory = (env: E2eEnv) => DriverResult<Driver>;
+/** How to attach to the app's dev client; default {@link openDevtools}. Tests inject a stub. */
+export type DevtoolsOpener = (env: E2eEnv) => Promise<DevtoolsResult<DevtoolsFacet>>;
+/**
+ * Which inspector page is this env's: the bundle id and the device name. Several devices can share one Metro;
+ * without the name the newest page of any device would win and a reload or evaluate would hit another device's app.
+ */
+export declare function devtoolsTarget(env: E2eEnv): {
+    appId: string;
+    deviceName?: string;
+};
+/** Metro's inspector for this env's app (`WARDEN_METRO_URL`), pinned by {@link devtoolsTarget}. */
+export declare const openDevtools: DevtoolsOpener;
+export type Session = {
+    readonly env: E2eEnv;
+    /** absolute `WARDEN_E2E_OUT` */
+    readonly out: string;
+    readonly results: ResultsWriter;
+    /** builds `app`/`device`/`screen` for each attempt (T4/T6); settable so tests can fake it */
+    fixtures: FixtureFactory | undefined;
+    /** how a failed attempt's `native.log` / crash reports are read; absent in unit tests (nothing is spawned) */
+    nativeLog: NativeLogDeps | undefined;
+    /**
+     * Present for iOS runs with recovery wired: after a test failed with a lost HID connection, reboots the sim and
+     * reopens the driver and devtools, once per session. Resolves `true` when the test is worth running again.
+     */
+    recoverHid: (() => Promise<boolean>) | undefined;
+    /** closes the open driver and devtools so the next call opens them afresh (the device was rebooted under them) */
+    resetDevice(): Promise<void>;
+    /** where the console reporter prints one line; default fd 1 */
+    readonly log: (line: string) => void;
+    /** the running attempt, if any */
+    readonly attempt: AttemptContext | undefined;
+    /** aborts at the running attempt's deadline; never aborts outside an attempt. Pass it to every driver call and poll. */
+    readonly signal: AbortSignal;
+    /** the running attempt's artifacts dir and `trace.jsonl` (read at call time by the `app`/`device` fixtures) */
+    readonly attemptDir: string | undefined;
+    readonly trace: TraceWriter | undefined;
+    /**
+     * opened on first call, then shared; a failed open is thrown as `E2eError{code:"DRIVER"}` and retried next call.
+     * Every call on it is a `driver.*` span in the running attempt's `trace.jsonl`, except a screen read that the
+     * observation cache answers from the snapshot a read just took (`driver/observation-cache.ts`; it offers `observe`).
+     */
+    driver(): Promise<Driver>;
+    /** the driver if it is already open; never opens one (failure capture must not start a device) */
+    peekDriver(): Driver | undefined;
+    /**
+     * The app's devtools (console, network, React tree, evaluate), attached on the first call and shared after;
+     * `devtools_unavailable` without `WARDEN_METRO_URL` (a release build). A failed attach is retried on the next call.
+     */
+    devtools(): Promise<DevtoolsResult<DevtoolsFacet>>;
+    /** the facet if it is already attached; never attaches one (failure capture must not connect to anything) */
+    peekDevtools(): DevtoolsFacet | undefined;
+    /** one reported step (`▸`/`▪` lines, `trace.jsonl`) that gives up when the attempt deadline aborts */
+    step<T>(kind: string, label: string, fn: () => Promise<T>): Promise<T>;
+    /** times one call as a `span` in the running attempt's `trace.jsonl` (no console line); just runs it outside an attempt */
+    span: SpanRunner;
+    /**
+     * Makes `attempt` the running one. With `replacing`, only when that is still the running one: an attempt's
+     * cleanup must not take the slot back from the next test that bun already started.
+     */
+    enterAttempt(attempt: AttemptContext, replacing?: AttemptContext): void;
+    /** Clears the running attempt; with `attempt`, only when that is the running one (never another test's). */
+    leaveAttempt(attempt?: AttemptContext): void;
+    /** idempotent; closes the driver only if it was opened */
+    close(): Promise<void>;
+};
+export type SessionOptions = {
+    /** parsed env; default `readEnv(process.env)` (throws `SESSION` when not under warden) */
+    env?: E2eEnv;
+    /** how to open the device; default {@link setDefaultDriverFactory}'s */
+    driverFactory?: DriverFactory;
+    /** how to attach devtools; default {@link openDevtools} */
+    devtools?: DevtoolsOpener;
+    /** native log reader; default {@link setDefaultNativeLog}'s */
+    nativeLog?: NativeLogDeps;
+    /** sim reboot seams; default {@link setDefaultHidRecovery}'s */
+    hidRecovery?: HidRecoveryDeps;
+    /** fixture factory; default {@link setDefaultFixtureFactory}'s */
+    fixtures?: FixtureFactory;
+    /** console line sink; default writes to fd 1 (bun test captures `process.stdout`, fd 1 is not captured) */
+    log?: (line: string) => void;
+    /** close from `process.on("exit")`; default true */
+    exitHook?: boolean;
+};
+/** Wires the HID-loss recovery used when a session gets none (`preload.ts` registers the real one). */
+export declare function setDefaultHidRecovery(deps: HidRecoveryDeps | undefined): void;
+/** Wires the native-log reader used when a session gets none (`preload.ts` registers the real one). */
+export declare function setDefaultNativeLog(deps: NativeLogDeps | undefined): void;
+/** Wires the factory used when `getSession` gets none (`driver/open.ts`'s opener, set by the package entry). */
+export declare function setDefaultDriverFactory(factory: DriverFactory | undefined): void;
+/** Whether a default driver factory is wired (so the preload leaves a test-installed fake alone). */
+export declare function hasDefaultDriverFactory(): boolean;
+/** Wires the `app`/`device`/`screen` factory used when `getSession` gets none. */
+export declare function setDefaultFixtureFactory(factory: FixtureFactory | undefined): void;
+/** Whether a default fixture factory is wired (so the preload leaves a test-installed one alone). */
+export declare function hasDefaultFixtureFactory(): boolean;
+export declare function createSession(opts?: SessionOptions): Session;
+/** Which context one attempt's own fixtures use right now; `finished` once the runner is done with the attempt. */
+export type AttemptBinding = {
+    readonly context: AttemptContext;
+    readonly finished: boolean;
+};
+/**
+ * `session` as one attempt's fixtures see it: `signal`, `attempt`, `attemptDir`, `trace`, `step` and `span` follow
+ * `binding` (that attempt's run context, then its cleanup context, then an aborted one), never whichever attempt is
+ * running when a call is made. So work the runner gave up on (a timed-out body that swallowed its `TIMEOUT`, an
+ * `afterEach` past its limit) fails its next driver call instead of tapping into the next test. Everything else is
+ * the shared session.
+ */
+export declare function attemptSession(session: Session, binding: () => AttemptBinding): Session;
+/** The process-wide session (`globalThis[Symbol.for("./session")]`), created on first call. */
+export declare function getSession(opts?: SessionOptions): Session;
+/** Closes and forgets the process-wide session, if any. */
+export declare function resetSession(): Promise<void>;

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

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

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

@@ -0,0 +1,7 @@
+/** What `WARDEN_E2E_VERSION` is when running from the workspace sources: not a published build, so no handshake. */
+export declare const WORKSPACE_VERSION = "0.0.0-workspace";
+/**
+ * The version of this `@delacour/warden-e2e`. Published builds carry warden's own version (lock-step);
+ * `warden e2e` hands its version to the spec process (`WARDEN_VERSION`) and the preload refuses to run when they differ.
+ */
+export declare const WARDEN_E2E_VERSION: string;

package/types/types/src/result.d.ts

@@ -0,0 +1,12 @@
+export type SuccessResult<Success> = {
+    success: true;
+    data: Success;
+};
+export type ErrorResult<Error = string> = {
+    success: false;
+    error: Error;
+};
+export type Result<Success, Error = string> = SuccessResult<Success> | ErrorResult<Error>;
+export type AsyncResult<Success, Error = string> = Promise<Result<Success, Error>>;
+export declare function ok<T>(data: T): SuccessResult<T>;
+export declare function err(error: unknown): ErrorResult<string>;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.