@specific.dev/spectest 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/browser.ts

@@ -78,6 +78,16 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
+  /**
+   * Script installed (before the session's first navigation) to run in every
+   * document loaded from now on, BEFORE the document's own scripts — the
+   * deterministic way to plant shims (reduced-motion, `Notification`, …) that
+   * must beat the app bundle. Unlike installing one after the session is
+   * handed back, this wins the race on the FIRST document too, so no relaunch
+   * is needed. Rides snapshots into `dependsOn` children. For a mobile app,
+   * declare it once on the handle instead — `expo({ initScript })`.
+   */
+  initScript?: string;
   /**
    * Sink that receives rrweb event chunks. Each Browser op (navigate,
    * click, …) calls `recordStep` with the events that landed in
@@ -212,16 +222,6 @@ export interface Browser {
     fn: string | ((arg?: unknown) => T | Promise<T>),
     arg?: unknown,
   ): Promise<Wrapped<T>>;
-  /**
-   * Install a script that runs in every document loaded from now on, BEFORE
-   * the document's own scripts (CDP `Page.addScriptToEvaluateOnNewDocument` —
-   * Playwright's `addInitScript`). The deterministic way to plant shims that
-   * must beat the app bundle. Does NOT run in the *current* document — call it
-   * before the `goto`/`location.assign` whose document needs it. Persists for
-   * the session's lifetime (rides snapshots into `dependsOn` children).
-   * `description` labels the step.
-   */
-  addInitScript(description: string, source: string): Promise<void>;
   /**
    * Poll `fn` in the page until it returns a truthy value (Playwright's
    * `page.waitForFunction`), recorded as ONE step with the total wait + poll
@@ -307,6 +307,22 @@ export interface MobileBackend extends Browser {
    * single recorded event; `touchscreen.tap` is the recorded public twin.
    */
   rawTap(x: number, y: number, durationMs?: number): Promise<void>;
+  /**
+   * Record ONE settled browser event for an `expect(locator)` web-first
+   * matcher and return its seq. The matcher already read the value by polling
+   * {@link silentRead} (one event per retry would flood the timeline); this
+   * emits the single timeline step — the locator label + the session seek
+   * point (`sessionTimestamp`) to the settled frame — so the assertion the
+   * caller records next nests under it via `sourceSeq`, exactly as
+   * `expect(await loc.isVisible())` does. Drains rrweb like any recorded op.
+   * Returns `undefined` when nothing is recording.
+   */
+  recordSettled(
+    action: BrowserAction,
+    fields: Partial<RecordableFields>,
+    waitedMs: number,
+    error?: string,
+  ): Promise<number | undefined>;
 }
 
 // Default extra flags for headless Chromium inside a Firecracker microVM.
@@ -955,8 +971,9 @@ interface ViewHolder {
    *  views or when the CDP override is unavailable). Stamped onto the
    *  session record so the replay can mirror them. */
   safeAreaInsets: SafeAreaInsets | null;
-  /** User scripts installed via `addInitScript`, kept so the DNS-recovery
-   *  rebuild can re-install them on the replacement page. */
+  /** Declared init scripts installed on this session (via
+   *  `BrowserOptions.initScript` / a mobile app's `initScript`), kept so the
+   *  DNS-recovery rebuild can re-install them on the replacement page. */
   initScripts: string[];
 }
 
@@ -1096,6 +1113,7 @@ export async function openMobileBackend(
   // We deliberately don't forward `opts.url` to the constructor — going
   // through our own `navigate()` keeps the recorder log uniform (one
   // event per navigation, with timing) and drains rrweb after the load.
+  if (opts.initScript !== undefined) await installInitScript(holder, opts.initScript);
   if (opts.url !== undefined) {
     await backend.goto(opts.url);
   }
@@ -1141,6 +1159,20 @@ async function newHolder(
   return holder;
 }
 
+/**
+ * Install a declared init script (from `BrowserOptions.initScript` / a mobile
+ * app's `initScript`) on a fresh holder's page: it runs before every document
+ * loaded from now on, ahead of the document's own scripts. Called BEFORE the
+ * session's first navigation, so it wins the race on the first document too.
+ * Recorded via `holder.initScripts` so a DNS-recovery page rebuild
+ * (`rebuildView`) re-installs it. Declared config, not a test action, so it
+ * emits no timeline event.
+ */
+async function installInitScript(holder: ViewHolder, source: string): Promise<void> {
+  await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+  holder.initScripts.push(source);
+}
+
 /**
  * What acquiring a persistent session returns. `detach` is the test-end
  * hook (final rrweb drain, stop writing to this test's recorder, keep the
@@ -1211,6 +1243,12 @@ export async function acquirePersistentBrowser(
       if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
     },
   });
+  // Fresh session only: an attached view already carries the init script on
+  // its (forked) holder, and first-call-wins means a later call's options
+  // don't retroactively apply.
+  if (!attached && opts.initScript !== undefined) {
+    await installInitScript(holder, opts.initScript);
+  }
   if (!attached && opts.url !== undefined) await backend.goto(opts.url);
   return { browser: backend, attached, detach };
 }
@@ -1222,6 +1260,7 @@ export async function acquirePersistentBrowser(
 export async function acquirePersistentMobileBackend(
   url: string,
   recorder: BrowserSessionRecorder | null,
+  initScript?: string,
 ): Promise<PersistentBrowser> {
   const existing = SHARED_MOBILE.get(url);
   const holder =
@@ -1242,7 +1281,12 @@ export async function acquirePersistentMobileBackend(
       if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
     },
   });
-  if (!existing) await backend.goto(url);
+  if (!existing) {
+    // Fresh session: install the app's init script before the first
+    // navigation so its first document already has the shims.
+    if (initScript !== undefined) await installInitScript(holder, initScript);
+    await backend.goto(url);
+  }
   return { browser: backend, attached: existing !== undefined, detach };
 }
 
@@ -1541,26 +1585,6 @@ function buildBackend(
         { wrap: true },
       ) as Promise<Wrapped<T>>;
     },
-    addInitScript(description: string, source: string): Promise<void> {
-      const truncated = truncateUtf8(source);
-      return instrumented(
-        "addInitScript",
-        {
-          description,
-          script: truncated.value,
-          scriptTruncated: truncated.truncated,
-        },
-        async () => {
-          // Raw CDP (not context.addInitScript) so the script stays scoped
-          // to THIS page — the desktop context is shared across views.
-          await holder.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
-            source,
-          });
-          // Remember it so a DNS-recovery page rebuild re-installs it.
-          holder.initScripts.push(source);
-        },
-      );
-    },
     async waitForFunction<T = unknown>(
       description: string,
       fn: string | ((arg?: unknown) => T),
@@ -1732,6 +1756,26 @@ function buildBackend(
     silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T> {
       return fn(holder.page);
     },
+    async recordSettled(action, fields, waitedMs, error) {
+      // No page work — the matcher already read the value via silentRead. We
+      // only mint the timeline anchor: the seq the assertion nests under, plus
+      // `sessionTimestamp` (post-settle wall clock) so the dashboard seeks the
+      // replay to the frame the assertion observed.
+      const endT = Date.now();
+      const seq = recordBrowser({
+        action,
+        ...fields,
+        ...(recorder
+          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
+          : {}),
+        durationMs: waitedMs,
+        ...(error ? { error } : {}),
+      });
+      // Drain the rrweb the page buffered while the matcher waited into this
+      // step's chunk, so `settledTarget` has bounds to seek into.
+      await drain(action);
+      return seq;
+    },
     pageOp<T>(
       action: BrowserAction,
       fields: Partial<RecordableFields>,

package/src/components/expo.ts

@@ -35,6 +35,13 @@ export interface ExpoOptions {
    * too late. Everything else applies to the static-server container only.
    */
   env?: Record<string, string>;
+  /**
+   * Script installed before each `ctx.mobile(ctx.svc.app)` session's first
+   * navigation, so it runs ahead of the app bundle on the very first document
+   * — no relaunch. Declare shims here once (reduced-motion, `Notification`, …)
+   * instead of calling them at the top of every test.
+   */
+  initScript?: string;
 }
 
 /** The handle `expo()` exposes on `ctx.svc.<name>` — a {@link MobileApp}. */
@@ -154,7 +161,7 @@ ${publicEnvLines ? `${publicEnvLines}\n` : ""}RUN npx expo export --platform web
       // TLS → net::ERR_SSL_PROTOCOL_ERROR), while a dotted host navigates as
       // plain HTTP. Node-side `fetch` is unaffected, but the mobile session
       // drives a real browser, so the URL must be browser-navigable.
-      return mobileApp(`http://${name}.internal:${port}`);
+      return mobileApp(`http://${name}.internal:${port}`, opts.initScript);
     },
   } satisfies ServiceDefinition<ExpoHelpers>;
 }

package/src/daemon.ts

@@ -3973,6 +3973,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
       url: app.url,
       recorder: session.recorder,
+      initScript: app.initScript,
     });
     if (safeAreaInsets) session.record.safeAreaInsets = safeAreaInsets;
     if (attached && session.record.initialUrl === undefined) {
@@ -4295,6 +4296,7 @@ async function evalCode(
     const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
       url: app.url,
       recorder: session.recorder,
+      initScript: app.initScript,
     });
     if (safeAreaInsets) session.record.safeAreaInsets = safeAreaInsets;
     if (attached && session.record.initialUrl === undefined) {

package/src/index.ts

@@ -1608,6 +1608,32 @@ export interface DefinedEnvironment<
   project(opts: ProjectOpts<S, F>): Project<S, F>;
 }
 
+/**
+ * The `ctx` type for an environment, for typing shared test helpers without
+ * `any`. Instantiate with the environment from `defineEnvironment`:
+ *
+ * ```ts
+ * const env = defineEnvironment({ ... });
+ * export type AppCtx = Ctx<typeof env>;
+ *
+ * // A helper reaching into ctx.svc / ctx.fakes stays fully typed:
+ * async function runJob(ctx: AppCtx) {
+ *   await ctx.svc.db.client`SELECT 1`;
+ * }
+ * ```
+ *
+ * This is the same `ctx` an `env.test(...)` callback receives. The parent
+ * return type is left as `unknown` (helpers rarely touch `ctx.parent` — read
+ * it in the test body and pass the value in). Prefer this over `ctx: any`:
+ * an `any`-typed ctx also defeats the `expect(...)` overloads, silently
+ * resolving `expect(value)` to the `expect(locator)` overload so value
+ * matchers like `.toBe(...)` disappear.
+ */
+export type Ctx<E> =
+  E extends DefinedEnvironment<infer S, infer F>
+    ? TestContext<unknown, S, F>
+    : never;
+
 /**
  * Define an environment and get back a builder you can hang tests off.
  * The builder's `.test(...)` returns test cases typed against the
@@ -1918,9 +1944,14 @@ function buildLocatorMatchers(
   const probe = getLocatorProbe(loc);
 
   // Poll `check` (a silent, non-recorded read) until the desired condition
-  // holds or the deadline elapses, then record ONE assertion event (like a
-  // value expect) and throw on failure. `check` returns whether the base
-  // condition is satisfied plus the observed value for the timeline.
+  // holds or the deadline elapses, then emit ONE settled browser step (the
+  // locator label + replay seek point) and record ONE assertion nested under
+  // it via `sourceSeq` — so a web-first `expect(locator)` assertion carries
+  // the same provenance a value assertion does (`expect(await loc.isVisible())`
+  // renders identically). Without the anchor step these assertions floated as
+  // disconnected top-level "value ✓" rows with no element and no replay seek.
+  // `check` returns whether the base condition is satisfied plus the observed
+  // value for the timeline.
   const run = async (
     matcher: string,
     timeout: number | undefined,
@@ -1928,7 +1959,8 @@ function buildLocatorMatchers(
     describe: (actual: unknown) => string,
     expected?: unknown,
   ): Promise<void> => {
-    const deadline = Date.now() + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+    const started = Date.now();
+    const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
     let actual: unknown;
     for (;;) {
       let satisfied: boolean;
@@ -1946,6 +1978,7 @@ function buildLocatorMatchers(
       }
       const passed = satisfied !== negated;
       if (passed) {
+        const sourceSeq = await probe.settle(matcher, Date.now() - started);
         recordAssertion({
           matcher,
           negated,
@@ -1953,11 +1986,13 @@ function buildLocatorMatchers(
           actual: safeSerialize(actual),
           expected: expected === undefined ? undefined : safeSerialize(expected),
           message,
+          sourceSeq,
         });
         return;
       }
       if (Date.now() >= deadline) {
         const msg = describe(actual);
+        const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
         recordAssertion({
           matcher,
           negated,
@@ -1966,6 +2001,7 @@ function buildLocatorMatchers(
           expected: expected === undefined ? undefined : safeSerialize(expected),
           error: msg,
           message,
+          sourceSeq,
         });
         throw new ExpectationError(msg);
       }

package/src/locator.ts

@@ -279,6 +279,15 @@ export interface LocatorBackend {
   silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T>;
   /** CDP touch tap with press dwell (mobile only). */
   rawTap(x: number, y: number, durationMs?: number): Promise<void>;
+  /** Record ONE settled browser event for an `expect(locator)` matcher (label
+   *  + session seek point) and return its seq, so the assertion nests under it.
+   *  See {@link "./browser".MobileBackend.recordSettled}. */
+  recordSettled(
+    action: string,
+    fields: Partial<RecordableFields>,
+    waitedMs: number,
+    error?: string,
+  ): Promise<number | undefined>;
 }
 
 /** Silent (non-recorded) reads a locator exposes for `expect(...)` matchers to
@@ -292,6 +301,12 @@ export interface LocatorProbe {
   count(): Promise<number>;
   isEnabled(timeout?: number): Promise<boolean>;
   isChecked(timeout?: number): Promise<boolean>;
+  /** After the silent poll settles, emit the single settled browser step this
+   *  locator's `expect(...)` matcher assertion nests under, and return its seq
+   *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
+   *  poll time, `error` marks the step failed on a timed-out matcher. Returns
+   *  `undefined` when nothing is recording. */
+  settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
 }
 
 const PROBE: unique symbol = Symbol.for("spectest.locatorProbe");
@@ -393,11 +408,12 @@ export interface Locator {
   check(opts?: TimeoutOption): Promise<void>;
   uncheck(opts?: TimeoutOption): Promise<void>;
   setChecked(checked: boolean, opts?: TimeoutOption): Promise<void>;
-  /** Select `<option>`(s) by value/label/index; returns the selected values. */
+  /** Select `<option>`(s) by value/label/index; returns the selected values,
+   *  provenance-wrapped so `expect(...)` on them nests under this step. */
   selectOption(
     values: string | string[] | { label?: string; value?: string; index?: number },
     opts?: TimeoutOption,
-  ): Promise<string[]>;
+  ): Promise<Wrapped<string[]>>;
   hover(opts?: TimeoutOption): Promise<void>;
   focus(opts?: TimeoutOption): Promise<void>;
   blur(opts?: TimeoutOption): Promise<void>;
@@ -479,6 +495,8 @@ export function makeLocator(
     count: () => backend.silentRead((page) => lower(page, chain).count()),
     isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
     isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
+    settle: (action, waitedMs, error) =>
+      backend.recordSettled(action, { selector: label }, waitedMs, error),
   };
 
   const loc: InternalLocator = {
@@ -524,7 +542,7 @@ export function makeLocator(
     setChecked: (checked, opts) =>
       act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
     selectOption: (values, opts) =>
-      act("selectOption", {}, (l) => l.selectOption(values as never, { timeout: opts?.timeout })),
+      read("selectOption", (l) => l.selectOption(values as never, { timeout: opts?.timeout })),
     hover: (opts) => act("hover", {}, (l) => l.hover({ timeout: opts?.timeout })),
     focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
     blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),

package/src/mobile.ts

@@ -36,6 +36,11 @@ export interface MobileApp {
   readonly [MOBILE_APP]: true;
   /** Resolved in-VM URL of the app's web build (e.g. `http://app.internal:8081`). */
   readonly url: string;
+  /** Optional script installed before the session's first navigation, so it
+   *  runs ahead of the app bundle on the very first document (no relaunch) —
+   *  the place to plant reduced-motion / `Notification` shims once for every
+   *  `ctx.mobile(app)` call. Set via `expo({ initScript })`. */
+  readonly initScript?: string;
 }
 
 /** True if `x` is a {@link MobileApp} handle. */
@@ -48,9 +53,10 @@ export function isMobileApp(x: unknown): x is MobileApp {
   );
 }
 
-/** Build a {@link MobileApp} handle from a resolved URL. */
-export function mobileApp(url: string): MobileApp {
-  return { [MOBILE_APP]: true, url };
+/** Build a {@link MobileApp} handle from a resolved URL (and an optional
+ *  init script installed before the session's first navigation). */
+export function mobileApp(url: string, initScript?: string): MobileApp {
+  return { [MOBILE_APP]: true, url, initScript };
 }
 
 // ────────────────────────────────────────────────────────────────────────
@@ -102,6 +108,9 @@ export async function openMobile(opts: {
 export async function openPersistentMobile(opts: {
   url: string;
   recorder: BrowserSessionRecorder | null;
+  /** Installed before the fresh session's first navigation (ignored on an
+   *  attached session, which already carries it on the forked holder). */
+  initScript?: string;
 }): Promise<{
   mobile: Mobile;
   attached: boolean;
@@ -113,6 +122,7 @@ export async function openPersistentMobile(opts: {
   const { browser, attached, detach } = await acquirePersistentMobileBackend(
     opts.url,
     opts.recorder,
+    opts.initScript,
   );
   return {
     mobile: browser,

package/src/recorder.ts

@@ -375,7 +375,7 @@ export interface EnvEvent extends BaseEvent {
 // method name verbatim. Both renderers (control-plane web + CLI) treat it as
 // an opaque string with a generic `{action} <target>` fallback, so new method
 // names need no Rust change. Representative values: "goto", "goBack",
-// "goForward", "reload", "evaluate", "addInitScript", "waitForFunction",
+// "goForward", "reload", "evaluate", "waitForFunction",
 // "click", "dblclick", "tap", "fill", "clear", "press", "type", "scroll",
 // "check", "hover", "textContent", "inputValue", "count", "screenshot".
 export type BrowserAction = string;