@e2edev/e2e 0.2.0

package/dist/run/events.js

@@ -0,0 +1,59 @@
+/**
+ * Structured run events (`@e2edev/e2e/run`): the run's single event spine.
+ *
+ * Every event is plain JSON data — the same records the report persists and
+ * the worker IPC already carries, so a host can stream them over any wire
+ * without touching live handles. The list reporter consumes exactly this
+ * stream (`ListReporter.handle`, report/list.ts), so the CLI's rendering and a
+ * host's dashboard can never drift: there is one dispatch, not two. The
+ * report stays the canonical record; the stream exists so consumers can
+ * render progress while the run is still going.
+ *
+ * The emitter is the single writer: it stamps `seq` and `at`, so ordering
+ * survives any transport that preserves per-connection order. A sink that
+ * throws is quarantined for the rest of the run; a sink whose returned
+ * promise rejects is quarantined once the rejection settles, so events
+ * emitted before then may still reach it. Either way a broken consumer can
+ * never fail the run.
+ */
+import { timestamp } from '../internal/ids.js';
+import { encodeResult } from './worker/protocol.js';
+/** Strips the live target from a result, keeping its stable identity. */
+export function toEventResult(record) {
+    return {
+        ...encodeResult(record),
+        target: { name: record.target.name, platform: record.target.platform },
+    };
+}
+/**
+ * Builds the run's single event writer over every configured sink. Sinks are
+ * quarantined independently, so a broken host callback cannot silence the
+ * list reporter or vice versa. Returns a no-op when no sink is configured,
+ * so call sites never branch.
+ */
+export function createRunEventEmitter(sinks) {
+    const active = sinks.filter((sink) => sink !== undefined);
+    if (active.length === 0)
+        return () => undefined;
+    let seq = 0;
+    const quarantined = new Set();
+    return (fact) => {
+        seq += 1;
+        const event = { seq, at: timestamp(), ...fact };
+        for (const sink of active) {
+            if (quarantined.has(sink))
+                continue;
+            try {
+                const result = sink(event);
+                // An async sink's rejection must neither surface as an unhandled
+                // rejection nor keep the sink subscribed.
+                if (result instanceof Promise)
+                    result.catch(() => quarantined.add(sink));
+            }
+            catch {
+                quarantined.add(sink);
+            }
+        }
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/run/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/run/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAyB,MAAM,sBAAsB,CAAC;AAoE3E,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,OAAO;QACL,GAAG,YAAY,CAAC,MAAM,CAAC;QACvB,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE;KACvE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA4C;IAE5C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IAChD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,MAAM,WAAW,GAAG,IAAI,GAAG,EAAgB,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,GAAG,IAAI,CAAC,CAAC;QACT,MAAM,KAAK,GAAa,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3B,iEAAiE;gBACjE,0CAA0C;gBAC1C,IAAI,MAAM,YAAY,OAAO;oBAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3E,CAAC;YAAC,MAAM,CAAC;gBACP,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/run/execute.d.ts

@@ -0,0 +1,119 @@
+/** Test-target execution engine (spec 11-lifecycle.md). */
+import type { TargetSession } from '../backend/surface.ts';
+import type { ResolvedConfig, ResolvedTarget } from '../config/resolve.ts';
+import { type SerializedError } from '../internal/errors.ts';
+import { DebugTrace } from '../internal/debug.ts';
+import type { CollectedFile } from '../collect/collect.ts';
+import type { ModuleRegistration, RegisteredTest } from '../collect/registry.ts';
+import type { TestTargetPair } from '../collect/select.ts';
+import type { ArtifactStore } from '../types.ts';
+import { type ArtifactSink } from './fixtures.ts';
+import { RealmManager, type Realm } from './realm.ts';
+import type { AttemptRecord, ResultRecord, RunError, SerialGroupRecord } from './records.ts';
+import { type SerialHost, type SharedSerialSession } from './serial.ts';
+import { SessionStaging, SessionStore } from './sessions.ts';
+import { type StepProgress } from './steps.ts';
+export interface ExecutionEvents {
+    onResult?(result: ResultRecord): void;
+    onSerialGroup?(group: SerialGroupRecord): void;
+    /** Fires before a runnable pair (or serial unit via its first member) starts. */
+    onPairStart?(pair: TestTargetPair): void;
+    /** Live step progress of one running attempt, for reporters. */
+    onProgress?(testId: string, progress: StepProgress): void;
+}
+export interface TargetExecutorOptions {
+    readonly config: ResolvedConfig;
+    readonly target: ResolvedTarget;
+    readonly runId: string;
+    readonly artifactsRoot: string;
+    readonly sessionStore: SessionStore;
+    readonly headed: boolean;
+    readonly interruptSignal: AbortSignal;
+    readonly debug?: DebugTrace;
+    readonly events?: ExecutionEvents;
+}
+/** The file-path slice of a collected file that unit execution needs. */
+export type FileRef = Pick<CollectedFile, 'file' | 'absolutePath'>;
+/** How one attempt acquires its session and session-staging hooks. */
+export type AttemptContext = {
+    readonly kind: 'ordinary';
+} | {
+    readonly kind: 'setup';
+    readonly staging: SessionStaging;
+} | {
+    readonly kind: 'serial';
+    readonly shared: SharedSerialSession;
+};
+/** Executes every selected pair for one target sequentially. */
+export declare class TargetExecutor implements SerialHost {
+    private readonly options;
+    readonly target: ResolvedTarget;
+    get runId(): string;
+    get artifactStore(): ArtifactStore | undefined;
+    readonly artifactsRoot: string;
+    readonly interruptSignal: AbortSignal;
+    readonly realms: RealmManager;
+    readonly debug: DebugTrace;
+    private readonly runErrors;
+    private readonly sessionIdentity;
+    /** Resolves once the backend's init hook completed for this worker. */
+    private backendReady;
+    constructor(options: TargetExecutorOptions);
+    private get config();
+    /** Emits one final result record (SerialHost). Records are not retained. */
+    emit(result: ResultRecord): void;
+    /** Builds one backend operation context. */
+    private op;
+    /** Run-level errors recorded so far, in order. */
+    collectedRunErrors(): readonly RunError[];
+    /**
+     * Runs the backend's init hook once per worker, before the first session.
+     * Boot work (simulators, device leases) is bounded by the launch timeout
+     * but never charged against a step budget.
+     */
+    private initBackendOnce;
+    /**
+     * Runs one lifecycle call on the backend seam within the given budget. The
+     * signal handed to `run` follows `parent` and is aborted the moment the call
+     * fails, timeout included, so a hook that outlived its budget is told to
+     * stop instead of running on into the retry. Synchronous throws are caught,
+     * and every failure is translated onto the runner taxonomy: a backend
+     * failing outside its contract is infrastructure, never a test error.
+     */
+    private lifecycle;
+    /**
+     * Disposes the backend at worker end of life, bounded by the cleanup budget.
+     * Runs whether or not `init` did: a backend may hold resources it acquired
+     * lazily, and the contract makes `dispose` safe to call on a cold backend.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Runs one file-target unit: runnable pairs of a single file, in declaration
+     * order, sharing a realm between passing non-serial tests (spec
+     * 11-lifecycle.md). Dispatch-time gating (selection dispositions and
+     * setup-failure dependencies) belongs to the scheduler, so every pair
+     * reaching here is runnable.
+     */
+    runFileUnit(file: FileRef, filePairs: readonly TestTargetPair[], freshRegistration?: ModuleRegistration): Promise<void>;
+    /** Records a deterministic-registration violation as a run-level error. */
+    recordDisappeared(message: string): void;
+    private runOrdinaryPair;
+    /** Runs one setup pair to completion, persisting staged sessions on success. */
+    runSetupUnit(pair: TestTargetPair, freshRegistration?: ModuleRegistration): Promise<void>;
+    /** Starts one attempt on the backend, restores a configured session, and starts tracing. */
+    launchSession(pair: TestTargetPair, attemptId: string, artifactsDir: string, signal: AbortSignal): Promise<TargetSession>;
+    /** Ends one attempt's isolation within the cleanup budget. */
+    private endAttempt;
+    /** Finalizes trace and ends the attempt with a fresh cleanup budget. */
+    closeSession(session: TargetSession, attemptId: string, record: {
+        cleanup: 'complete' | 'failed' | 'forced';
+    }, artifactSink: ArtifactSink, secondaryErrors: SerializedError[]): Promise<void>;
+    /** Runs one attempt to completion (SerialHost). */
+    /**
+     * Runs one attempt under its AI trace scope, so every model call the
+     * attempt makes is attributed to this test, target, and attempt.
+     */
+    runAttempt(pair: TestTargetPair, registered: RegisteredTest, realm: Realm, attemptIndex: number, context: AttemptContext): Promise<AttemptRecord>;
+    private executeAttempt;
+}
+//# sourceMappingURL=execute.d.ts.map

package/dist/run/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/run/execute.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAkB,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAwB,MAAM,eAAe,CAAC;AACnF,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAG7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,aAAa,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/C,iFAAiF;IACjF,WAAW,CAAC,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,gEAAgE;IAChE,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;CACnC;AAOD,yEAAyE;AACzE,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEtE,gEAAgE;AAChE,qBAAa,cAAe,YAAW,UAAU;IAkBnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjBpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,aAAa,IAAI,aAAa,GAAG,SAAS,CAE7C;IACD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,uEAAuE;IACvE,OAAO,CAAC,YAAY,CAA4B;IAEhD,YAA6B,OAAO,EAAE,qBAAqB,EAsC1D;IAED,OAAO,KAAK,MAAM,GAEjB;IAED,4EAA4E;IAC5E,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE/B;IAED,4CAA4C;IAC5C,OAAO,CAAC,EAAE;IAIV,kDAAkD;IAClD,kBAAkB,IAAI,SAAS,QAAQ,EAAE,CAExC;IAED;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA+BvB;;;;;;;OAOG;YACW,SAAS;IAoBvB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAc7B;IAED;;;;;;OAMG;IACG,WAAW,CACf,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,iBAAiB,CAAC,EAAE,kBAAkB,GACrC,OAAO,CAAC,IAAI,CAAC,CA4Bf;IAED,2EAA2E;IAC3E,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMvC;YAIa,eAAe;IAyD7B,gFAAgF;IAC1E,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkE9F;IAID,4FAA4F;IACtF,aAAa,CACjB,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAkDxB;IAED,8DAA8D;IAC9D,OAAO,CAAC,UAAU;IAUlB,wEAAwE;IAClE,YAAY,CAChB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;QAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;KAAE,EACrD,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,eAAe,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CA0Bf;IAED,mDAAmD;IACnD;;;OAGG;IACH,UAAU,CACR,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAUxB;YAEa,cAAc;CAmM7B"}