@delacour/warden-e2e 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,105 @@
+import { type DevtoolsFacet, type DevtoolsResult } from "./devtools/devtools.types";
+import type { Driver, DriverResult } from "./driver/driver.types";
+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;
+    /** 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;
+    /** 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 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.