@specific.dev/spectest 0.16.0 → 0.17.0

package/package.json

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

package/src/browser.ts

@@ -159,8 +159,10 @@ export interface Browser {
   /** Navigate to a URL; resolves when the main frame's load completes. */
   navigate(url: string): Promise<void>;
   /**
-   * Evaluate a JS expression in the page and return the
-   * JSON-deserialised result.
+   * Evaluate JS in the page and return the JSON-deserialised result.
+   * Accepts a single expression or a statement body (`const x = …;
+   * return x;`) — statement bodies are auto-wrapped in an async IIFE, so
+   * `return` and `await` work without manual wrapping.
    *
    * `description` is a short human-readable label for what the
    * snippet is doing ("read rendered todo list"); it surfaces in the
@@ -255,8 +257,9 @@ export interface MobileBackend extends Browser {
    *  when the CDP override is unavailable). The daemon stamps these onto
    *  the session record for the dashboard's replay. */
   readonly safeAreaInsets: SafeAreaInsets | null;
-  /** Touch-tap at viewport CSS coordinates (touchStart→touchEnd). */
-  tapAt(x: number, y: number): Promise<void>;
+  /** Touch-tap at viewport CSS coordinates (touchStart → short dwell →
+   *  touchEnd; `durationMs` overrides the dwell). */
+  tapAt(x: number, y: number, opts?: { durationMs?: number }): Promise<void>;
   /** Touch-drag from (x,y) by (dx,dy) over a short move sequence. */
   swipeBy(x: number, y: number, dx: number, dy: number): Promise<void>;
   /**
@@ -289,6 +292,32 @@ const CHROME_ARGV = [
   "--dns-over-https-mode=off",
 ];
 
+/** Default touchStart→touchEnd dwell for `tapAt` — see the comment there. */
+const TAP_DWELL_MS = 60;
+
+/**
+ * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
+ * single EXPRESSION (it wraps the source in `await (...)`), so a statement
+ * body (`const x = …; return x;`) is a syntax error. Rather than forcing
+ * authors to IIFE-wrap by hand, wrap it for them when it isn't an expression.
+ *
+ * The check is parse-only (`new Function` compiles without executing) and
+ * happens BEFORE the script runs — deciding by catching the page-side error
+ * and retrying would re-execute side-effecting expressions whose *runtime*
+ * error happens to look syntactic (`JSON.parse` throws SyntaxError too).
+ */
+function toEvaluable(script: string): string {
+  try {
+    new Function(`return (${script}\n);`);
+    return script;
+  } catch {
+    // Statement body — an async IIFE makes `return`, declarations, and
+    // multi-statement snippets valid, with `await` still available. The
+    // newlines keep a trailing line comment from eating the wrapper.
+    return `(async () => {\n${script}\n})()`;
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Device emulation (mobile frame)
 // ────────────────────────────────────────────────────────────────────────
@@ -1144,7 +1173,7 @@ function buildBackend(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await holder.view.evaluate<T>(script);
+          const v = await holder.view.evaluate<T>(toEvaluable(script));
           return v;
         },
       ) as Promise<Wrapped<T>>;
@@ -1183,6 +1212,8 @@ function buildBackend(
         scriptTruncated: truncatedScript.truncated,
         attempts: 0,
       };
+      // Normalised once up front — see `toEvaluable` (statement bodies work).
+      const evaluable = toEvaluable(expression);
       return instrumented<T>("waitFor", fields, async () => {
         const deadline = Date.now() + timeoutMs;
         // (return value wrapped by `instrumented`; cast below matches.)
@@ -1195,7 +1226,7 @@ function buildBackend(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await holder.view.evaluate<unknown>(expression);
+            v = await holder.view.evaluate<unknown>(evaluable);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -1272,7 +1303,7 @@ function buildBackend(
       }
     },
     // ── Mobile-only primitives ──────────────────────────────────────────
-    tapAt(x, y) {
+    tapAt(x, y, opts) {
       // Recorded as a "click" (the event schema stays desktop-shaped; the
       // mobile facade owns the author-facing "tap" vocabulary). Dispatches
       // a real touch so RN-Web's responder system fires.
@@ -1281,6 +1312,13 @@ function buildBackend(
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
+        // Dwell between start and end, like a real finger. An instant
+        // touchStart→touchEnd starves RN Pressables whose `onPressIn`
+        // mutates state (optimistic label flips, scale animations): React
+        // re-renders mid-gesture and the press never completes. The dwell
+        // lets that commit land before release; well under any long-press
+        // threshold (RN default 500ms).
+        await new Promise((r) => setTimeout(r, opts?.durationMs ?? TAP_DWELL_MS));
         await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],

package/src/components/expo.ts

@@ -28,7 +28,12 @@ export interface ExpoOptions {
   nodeVersion?: string;
   /** Output dir `expo export` writes to (relative to the app dir). Default `"dist"`. */
   outputDir?: string;
-  /** Extra environment variables for the static server container. */
+  /**
+   * Extra environment variables. `EXPO_PUBLIC_*` keys are additionally baked
+   * into the image build so `expo export` inlines them into the bundle —
+   * Expo resolves them at export time, so runtime-only container env would be
+   * too late. Everything else applies to the static-server container only.
+   */
   env?: Record<string, string>;
 }
 
@@ -106,6 +111,23 @@ export function expo(opts: ExpoOptions = {}) {
   const nodeVersion = opts.nodeVersion ?? "20-bookworm-slim";
   const outputDir = opts.outputDir ?? "dist";
 
+  // Expo inlines EXPO_PUBLIC_* variables into the bundle at `expo export`
+  // time, so they must exist during the image build — runtime container env
+  // is too late. Bake them as ENV lines placed after `npm install` (an env
+  // edit re-exports without re-installing) and before the export RUN. They
+  // remain in `env` too, so server-side reads in the container agree.
+  const publicEnv = Object.entries(opts.env ?? {}).filter(([k]) =>
+    k.startsWith("EXPO_PUBLIC_"),
+  );
+  for (const [k, v] of publicEnv) {
+    if (/[\r\n]/.test(v)) {
+      throw new Error(`expo(): env ${k} must not contain newlines (baked into the Dockerfile)`);
+    }
+  }
+  const publicEnvLines = publicEnv
+    .map(([k, v]) => `ENV ${k}="${v.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`)
+    .join("\n");
+
   // CI=1 keeps `expo export` non-interactive. Static export resolves the web
   // bundle deterministically into `outputDir`.
   const dockerfile = `FROM node:${nodeVersion}
@@ -113,7 +135,7 @@ WORKDIR /app
 ENV CI=1
 COPY ${appDir}/ ./
 RUN npm install
-RUN npx expo export --platform web --output-dir ${outputDir}
+${publicEnvLines ? `${publicEnvLines}\n` : ""}RUN npx expo export --platform web --output-dir ${outputDir}
 `;
 
   return {

package/src/daemon.ts

@@ -845,6 +845,19 @@ async function buildServiceImage(
     await fs.mkdir(dfDir, { recursive: true });
     const dfPath = path.join(dfDir, "Dockerfile");
     await fs.writeFile(dfPath, image.content);
+    // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
+    // (next to the Dockerfile) in preference to the context root's
+    // `.dockerignore`, so this build sees the defaults plus ITS OWN
+    // `exclude` only — one service excluding `handhelds/**` no longer
+    // empties a sibling's build context. Verified on both the remote-buildx
+    // and DOCKER_BUILDKIT paths (client-side context filtering). The root
+    // union `.dockerignore` written at bootstrap stays as the fallback for
+    // the legacy non-BuildKit builder, which predates per-Dockerfile
+    // ignores.
+    await fs.writeFile(
+      `${dfPath}.dockerignore`,
+      [...DEFAULT_DOCKERIGNORE, ...(image.exclude ?? [])].join("\n") + "\n",
+    );
     const useRemote = await ensureRemoteBuilder();
     // Both the remote builder and a local buildx are BuildKit, so both emit
     // per-step timing on stderr under `--progress=plain` (parsed below). Only
@@ -2045,6 +2058,16 @@ async function proxyToService(
   // the public hostname. Lets origin servers that vhost by Host header
   // continue to find the right virtual host.
   fwdHeaders.set("host", `${service}:${port}`);
+  // Fresh connection per upstream request — never reuse a pooled
+  // keep-alive conn. Upstreams with short idle timeouts (uvicorn defaults
+  // to 5s) close pooled connections under Bun's fetch, and the next
+  // request on the dead socket fails with "socket closed unexpectedly"
+  // even though the service is healthy. In-VM connects to a peer
+  // container are sub-ms, so per-request connects cost nothing at test
+  // scale. `connection: close` makes the upstream tear down immediately;
+  // `keepalive: false` on the fetch below keeps Bun from pooling its end.
+  // (Both verified effective on Bun 1.3.14.)
+  fwdHeaders.set("connection", "close");
 
   // Buffer bounded request bodies so a transient upstream connect failure
   // can be retried (a ReadableStream body is consumed by the first
@@ -2085,8 +2108,13 @@ async function proxyToService(
         redirect: "manual",
       });
       // decompress:false → forward the encoded body untouched (see fn doc).
+      // keepalive:false → fresh connection per request (see fwdHeaders above).
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const upstreamRes = await NATIVE_FETCH(upstreamReq, { decompress: false } as any);
+      const upstreamRes = await NATIVE_FETCH(upstreamReq, {
+        decompress: false,
+        keepalive: false,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
       // Strip hop-by-hop response headers; let Bun set content-length / TE.
       const respHeaders = new Headers();
       for (const [k, v] of upstreamRes.headers) {
@@ -2100,11 +2128,18 @@ async function proxyToService(
       });
     } catch (err) {
       lastErr = err;
-      // Only connect-class failures are safely retryable — if the request
-      // reached the upstream we must not replay it.
+      // Retry connection-level failures: connect errors, plus a socket
+      // that died before any response bytes ("socket closed unexpectedly",
+      // ECONNRESET, hang-up) — under boot-time bursts an upstream accepts
+      // and drops connections while still warming up. Pre-response
+      // failures are the standard retry class for reverse proxies
+      // (nginx's proxy_next_upstream error). Anything that produced a
+      // response is never replayed.
       const msg = (err as Error)?.message ?? String(err);
       const connectFailure =
-        /unable to connect|connection refused|connect|typo in the url/i.test(msg);
+        /unable to connect|connection refused|connect|typo in the url|socket closed|connection closed|econnreset|socket hang ?up|epipe/i.test(
+          msg,
+        );
       if (!connectFailure || attempt === attempts) break;
       // The cached IP may be stale (container recreated) — re-resolve.
       PROXY_IP_CACHE.delete(service);

package/src/mobile.ts

@@ -69,12 +69,13 @@ interface LocatorDesc {
  *  moment an action runs. Mirrors the select-then-act idiom shared by
  *  Playwright, Detox, and RN Testing Library. */
 export interface MobileLocator {
-  /** Wait for the element to be visible, then touch-tap its center. */
-  tap(): Promise<void>;
+  /** Wait for the element to be visible (default 5s, `timeoutMs` overrides),
+   *  then touch-tap its center. `durationMs` overrides the touch dwell. */
+  tap(opts?: { timeoutMs?: number; durationMs?: number }): Promise<void>;
   /** Tap to focus, then type `text` via real key events. */
-  typeText(text: string): Promise<void>;
+  typeText(text: string, opts?: { timeoutMs?: number }): Promise<void>;
   /** Clear a text input's current value (RN-Web controlled input safe). */
-  clearText(): Promise<void>;
+  clearText(opts?: { timeoutMs?: number }): Promise<void>;
   /** Scroll the element to the center of the viewport. */
   scrollIntoView(): Promise<void>;
   /** Wait until the element is attached and visible (throws on timeout). */
@@ -168,6 +169,11 @@ function descLabel(desc: LocatorDesc): string {
   return `${desc.kind} ${JSON.stringify(desc.value)}`;
 }
 
+/** Default wait for a locator action's target to become visible. Override
+ *  per action with `{ timeoutMs }` (animations that move elements mid-flight
+ *  often need more than the default). */
+const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+
 function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
   const label = descLabel(desc);
 
@@ -188,17 +194,17 @@ function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
   }
 
   return {
-    async tap() {
-      const { x, y } = await waitCoords(5_000);
-      await backend.tapAt(x, y);
+    async tap(opts) {
+      const { x, y } = await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
+      await backend.tapAt(x, y, { durationMs: opts?.durationMs });
     },
-    async typeText(text) {
-      const { x, y } = await waitCoords(5_000);
+    async typeText(text, opts) {
+      const { x, y } = await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
       await backend.tapAt(x, y);
       await backend.type(text);
     },
-    async clearText() {
-      await waitCoords(5_000);
+    async clearText(opts) {
+      await waitCoords(opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
       // Native value-setter + input event so RN-Web's controlled TextInput
       // sees the change (a plain `.value = ""` is swallowed by React).
       await backend.evaluate(
@@ -269,6 +275,13 @@ export interface Mobile {
   getByLabel(text: string): MobileLocator;
   /** Escape hatch: select by a raw CSS selector. */
   locator(css: string): MobileLocator;
+  /**
+   * Touch-tap at viewport CSS coordinates — the escape hatch for targets no
+   * locator can select (unlabeled icon-only buttons, canvas hit areas). Same
+   * real-touch dispatch and dwell as a locator `tap()`. Prefer locators when
+   * the element has a testID/label; coordinates break on layout changes.
+   */
+  tapAt(x: number, y: number, opts?: { durationMs?: number }): Promise<void>;
   /** Swipe the screen in a direction (a touch drag from the center). */
   swipe(direction: "up" | "down" | "left" | "right", opts?: { distance?: number }): Promise<void>;
   /** Wheel-scroll the viewport by a pixel delta. */
@@ -334,6 +347,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
     locator(css) {
       return makeLocator(backend, { kind: "css", value: css });
     },
+    tapAt(x, y, opts) {
+      return backend.tapAt(x, y, opts);
+    },
     async swipe(direction, opts) {
       const vp = await backend.probe<{ w: number; h: number }>(
         "({ w: window.innerWidth, h: window.innerHeight })",

package/src/recorder.ts

@@ -115,8 +115,12 @@ export interface DbEvent extends BaseEvent {
   query: string;
   /** Parameter values. Best-effort JSON-safe; large/binary values stringified. */
   params?: unknown[];
-  /** Rows returned, when known. */
+  /** Rows returned — or rows AFFECTED when `rowsAffected` is set. */
   rowCount?: number;
+  /** Set when `rowCount` counts affected rows (a non-RETURNING
+   *  INSERT/UPDATE/DELETE) rather than a result set — rendered as
+   *  "N affected" so an `UPDATE → 0 rows` can't read as "nothing updated". */
+  rowsAffected?: boolean;
   /** Captured rows for table rendering in the web UI. Capped at
    *  MAX_DB_ROWS; `rowsTruncated` is set when there were more. */
   rows?: unknown[];

package/src/sql.ts

@@ -124,6 +124,7 @@ export function instrumentSql(raw: RawSqlClient, label: string): SqlClient {
             query,
             params: params.length > 0 ? params.map(safeSerialize) : undefined,
             rowCount: rowCountOf(value),
+            rowsAffected: isAffectedCount(query, value) || undefined,
             rows,
             rowsTruncated,
             columns,
@@ -192,15 +193,34 @@ function reconstructSqlTemplate(
 }
 
 function rowCountOf(value: unknown): number | undefined {
-  if (Array.isArray(value)) return value.length;
   if (value && typeof value === "object") {
     const obj = value as { count?: unknown; rowCount?: unknown };
+    // Bun.SQL (postgres.js semantics): `.count` is rows RETURNED for
+    // SELECT/RETURNING queries and rows AFFECTED for other writes — where
+    // the result array itself is empty. Check it before `.length`, or a
+    // non-RETURNING `UPDATE` that touched 3 rows records a misleading 0.
     if (typeof obj.count === "number") return obj.count;
     if (typeof obj.rowCount === "number") return obj.rowCount;
   }
+  if (Array.isArray(value)) return value.length;
   return undefined;
 }
 
+/** True when the recorded count means "rows affected" rather than "rows
+ *  returned" — a write with no result set. Lets the dashboard render
+ *  `3 affected` instead of `3 rows` (and keeps `UPDATE … (0 rows)` from
+ *  reading as "nothing updated"). */
+function isAffectedCount(query: string, value: unknown): boolean {
+  if (Array.isArray(value) && value.length > 0) return false; // rows came back
+  const q = query.trimStart().slice(0, 8).toUpperCase();
+  return (
+    q.startsWith("INSERT") ||
+    q.startsWith("UPDATE") ||
+    q.startsWith("DELETE") ||
+    q.startsWith("MERGE")
+  );
+}
+
 const MAX_DB_ROWS = 50;
 
 function captureRows(value: unknown): {