@specific.dev/spectest 0.39.0 → 0.41.0

package/src/mobile.ts

@@ -0,0 +1,133 @@
+// Mobile app handle for tests — drives an Expo/React-Native-Web app rendered
+// in a phone-emulated headless Chromium and recorded as an rrweb session that
+// the dashboard replays inside a phone bezel.
+//
+// `ctx.mobile(ctx.svc.app)` opens one of these already pointed at the app. The
+// surface is the SAME Playwright-native one as `ctx.browser()` (the shared
+// `Browser` session + `Locator`s from browser.ts/locator.ts) plus two mobile
+// extensions: a `touchscreen` and `swipe`. There is no mobile-specific locator
+// type — `getByTestId`/`getByRole`/`getByText`/… return the same `Locator`,
+// and on a mobile session a locator's `tap()` dispatches a real CDP touch with
+// the press dwell RN Pressables need (the `mobileStrategy` in locator.ts;
+// desktop `tap()` throws and steers you to `click()`).
+//
+// This file is now just the `MobileApp` handle (`ctx.mobile` accepts it) and
+// the `Mobile` public view of the shared backend. React Native Web renders
+// `testID="x"` to `data-testid="x"` and `accessibilityLabel` to `aria-label`,
+// so `getByTestId`/`getByLabel` map straight onto Playwright's built-ins.
+
+import { acquirePersistentMobileBackend, openMobileBackend } from "./browser.js";
+import type {
+  Browser,
+  BrowserSessionRecorder,
+  SafeAreaInsets,
+  Touchscreen,
+} from "./browser.js";
+
+/** Branded handle a mobile-app component (e.g. `expo()`) exposes on
+ *  `ctx.svc.<name>`. The brand is a `Symbol.for` key so `JSON.stringify`
+ *  drops it (wire-invisible) while `ctx.mobile(...)` can still type-check
+ *  against it. */
+export const MOBILE_APP: unique symbol = Symbol.for("spectest.mobileApp");
+
+/** What `ctx.mobile(...)` accepts — produced by a mobile-app component's
+ *  `helpers` factory. Carries the in-VM URL the session auto-navigates to. */
+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. */
+export function isMobileApp(x: unknown): x is MobileApp {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    (x as Record<symbol, unknown>)[MOBILE_APP] === true &&
+    typeof (x as { url?: unknown }).url === "string"
+  );
+}
+
+/** 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 };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Mobile session
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * A phone-emulated app session. The full {@link Browser} surface (locators,
+ * `keyboard`/`mouse`, `evaluate`, …) plus a `touchscreen` and `swipe`. Opened
+ * via `ctx.mobile(app)` already on the app.
+ *
+ * The device is fixed (latest iPhone: viewport, DPR, mobile UA, touch). A
+ * locator's `tap()` on this session uses a real CDP touch with the RN press
+ * dwell; `getByTestId` targets `testID`, `getByLabel` targets
+ * `accessibilityLabel`.
+ */
+export interface Mobile extends Browser {
+  /** Coordinate touch taps (mobile escape hatch — prefer locator `tap()`). */
+  readonly touchscreen: Touchscreen;
+  /** Swipe the screen in a direction (a touch drag from the center). */
+  swipe(direction: "up" | "down" | "left" | "right", opts?: { distance?: number }): Promise<void>;
+}
+
+/**
+ * Open an EPHEMERAL phone-emulated session pointed at `url` (`close()`
+ * destroys it). Library callers only — the daemon's `ctx.mobile(app)` goes
+ * through {@link openPersistentMobile} so sessions survive across tests.
+ */
+export async function openMobile(opts: {
+  url?: string;
+  recorder: BrowserSessionRecorder | null;
+}): Promise<Mobile> {
+  const backend = await openMobileBackend({
+    frame: "mobile",
+    url: opts.url,
+    recorder: opts.recorder,
+  });
+  // MobileBackend is a superset of Mobile (adds the low-level primitives).
+  return backend;
+}
+
+/**
+ * Acquire the persistent phone-emulated session for an app (one per app URL,
+ * created on first use). The daemon calls this from `ctx.mobile(app)` with a
+ * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
+ * the dashboard renders a phone bezel. `detach` is the test-end hook;
+ * `mobile.close()` destroys the session for real.
+ */
+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;
+  detach(): Promise<void>;
+  /** Safe-area insets emulated on the view (`null` when the CDP override
+   *  is unavailable) — the daemon stamps them onto the session record. */
+  safeAreaInsets: SafeAreaInsets | null;
+}> {
+  const { browser, attached, detach } = await acquirePersistentMobileBackend(
+    opts.url,
+    opts.recorder,
+    opts.initScript,
+  );
+  return {
+    mobile: browser,
+    attached,
+    detach,
+    safeAreaInsets: browser.safeAreaInsets,
+  };
+}

package/src/record-secrets.ts

@@ -0,0 +1,41 @@
+// Eval-scoped secret channel for record-mode fakes (see
+// `components/replayFake.ts`).
+//
+// The control plane resolves a platform secret (e.g. `STRIPE_API_KEY`)
+// server-side and pushes it into the daemon on the `/eval` request body
+// only — never on the `run_tests` path, never into the project tarball,
+// the config hash, or any cassette. The daemon stashes the resolved
+// values here for exactly the duration of one eval (set before the
+// snippet runs, cleared in the eval's `finally`) and the record-mode fake
+// forwarder reads them via {@link getRecordSecret}.
+//
+// Eval-scoped is load-bearing: daemon memory survives snapshot/fork, so a
+// long-lived secrets map could ride a warm/post-test snapshot into a
+// forkable state a hermetic `spectest test` could observe. Clearing per
+// eval means a secret never persists into anything a replay run can reach.
+// This module is shared (one instance per daemon process) so the daemon
+// writes and the component reads the same map.
+
+const SECRETS = new Map<string, string>();
+
+/** Replace the eval-scoped secret set. Called by the daemon at the start
+ *  of each `/eval` with the values the control plane resolved. */
+export function setRecordSecrets(secrets: Record<string, string> | undefined): void {
+  SECRETS.clear();
+  if (!secrets) return;
+  for (const [ref, value] of Object.entries(secrets)) {
+    if (typeof value === "string") SECRETS.set(ref, value);
+  }
+}
+
+/** Drop all secrets. Called from the eval's `finally` so nothing survives
+ *  past the eval that supplied them. */
+export function clearRecordSecrets(): void {
+  SECRETS.clear();
+}
+
+/** Resolve a secret by its platform `ref`. `undefined` if the control
+ *  plane didn't supply it (ref not configured, or not on the eval path). */
+export function getRecordSecret(ref: string): string | undefined {
+  return SECRETS.get(ref);
+}