@specific.dev/spectest 0.21.0 → 0.22.0

package/src/mobile.ts

@@ -2,30 +2,27 @@
 // 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, so
-// there's no `navigate`. The surface is mobile-native (tap/typeText/swipe,
-// select-then-act locators that lean on testID) rather than the desktop
-// `Browser` verbs — see DESIGN. Under the hood it's a thin facade over a
-// `MobileBackend` (browser.ts): the heavy lifting (CDP device emulation, the
-// recorder, rrweb capture/drain) is shared with the desktop browser; this
-// file only adds the locator/gesture ergonomics.
+// `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()`).
 //
-// React Native Web renders `testID="x"` to `data-testid="x"` and
-// `accessibilityLabel` to `aria-label`, so `getByTestId`/`getByLabel` map
-// straight onto playwright's built-in locators (its `testIdAttribute`
-// default is `data-testid`). Locator resolution, waiting, and actionability
-// are playwright's; this file adds the descriptor plumbing, the recorder
-// events, and the CDP touch dispatch (playwright's `tap()` has no press
-// dwell, which RN Pressables need — see `rawTap` in browser.ts).
+// 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,
-  MobileBackend,
   SafeAreaInsets,
+  Touchscreen,
 } from "./browser.js";
-import type { Locator, Page } from "playwright-core";
-import type { Wrapped } from "./inspect.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`
@@ -56,347 +53,25 @@ export function mobileApp(url: string): MobileApp {
   return { [MOBILE_APP]: true, url };
 }
 
-// ────────────────────────────────────────────────────────────────────────
-// Locators
-// ────────────────────────────────────────────────────────────────────────
-
-interface LocatorDesc {
-  kind: "testid" | "text" | "role" | "label" | "css";
-  value: string;
-  exact?: boolean;
-  regex?: { source: string; flags: string };
-  name?: string;
-  nameExact?: boolean;
-  /** Narrowing applied after resolution (`.first()`/`.last()`/`.nth(i)`) —
-   *  the explicit escape hatch from strict mode. */
-  nth?: number | "first" | "last";
-}
-
-/** A lazy reference to a single element, resolved (with auto-wait) at the
- *  moment an action runs. Mirrors the select-then-act idiom shared by
- *  Playwright, Detox, and RN Testing Library — including Playwright's
- *  STRICT mode: a locator matching multiple elements throws an
- *  element-listing error rather than acting on one of them. Narrow with
- *  `exact: true`, a testID, or {@link first}/{@link nth}. */
-export interface MobileLocator {
-  /** 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, opts?: { timeoutMs?: number }): Promise<void>;
-  /** Clear a text input's current value (RN-Web controlled input safe). */
-  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). */
-  waitFor(opts?: { timeoutMs?: number }): Promise<void>;
-  /** Assert the element becomes visible within the timeout (throws otherwise). */
-  assertVisible(opts?: { timeoutMs?: number }): Promise<void>;
-  /** Whether the element is currently present and visible (no waiting).
-   *  Wrapped so an `expect(...)` on it nests under the read in the
-   *  timeline. */
-  isVisible(): Promise<Wrapped<boolean>>;
-  /** The element's text content, wrapped. Waits (default 5s) for the
-   *  element to become visible; throws if it never does. */
-  textContent(): Promise<Wrapped<string | null>>;
-  /** Narrow to the first resolved element — the explicit opt-out from
-   *  strict mode when multiple matches are intentional. */
-  first(): MobileLocator;
-  /** Narrow to the last resolved element. */
-  last(): MobileLocator;
-  /** Narrow to the i-th resolved element (0-based). */
-  nth(index: number): MobileLocator;
-}
-
-/** Map a locator descriptor onto a playwright Locator — STRICT, exactly
- *  like stock Playwright: a locator that resolves to multiple elements
- *  throws an element-listing "strict mode violation" at action time
- *  instead of silently picking one. (An earlier `.filter({visible})
- *  .first()` auto-pick deterministically tapped the WRONG element when
- *  case-insensitive substring matching made two leaves qualify —
- *  `getByText("Men")` also matches "Wo**men**". Loud beats lucky.)
- *  Disambiguate with `exact: true`, a testID, or `.first()`/`.nth(i)`. */
-function pwLocator(page: Page, desc: LocatorDesc): Locator {
-  let base: Locator;
-  switch (desc.kind) {
-    case "css":
-      base = page.locator(desc.value);
-      break;
-    case "testid":
-      base = page.getByTestId(desc.value);
-      break;
-    case "label":
-      base = page.getByLabel(desc.value);
-      break;
-    case "role":
-      base = page.getByRole(
-        desc.value as Parameters<Page["getByRole"]>[0],
-        desc.name !== undefined ? { name: desc.name, exact: desc.nameExact } : {},
-      );
-      break;
-    default:
-      base = page.getByText(
-        desc.regex ? new RegExp(desc.regex.source, desc.regex.flags) : desc.value,
-        { exact: desc.exact },
-      );
-      break;
-  }
-  if (desc.nth === "first") return base.first();
-  if (desc.nth === "last") return base.last();
-  if (typeof desc.nth === "number") return base.nth(desc.nth);
-  return base;
-}
-
-/** Short human label for a descriptor, used in event descriptions. */
-function descLabel(desc: LocatorDesc): string {
-  let base: string;
-  if (desc.kind === "text") {
-    base = desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
-  } else if (desc.kind === "role") {
-    base = desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
-  } else {
-    base = `${desc.kind} ${JSON.stringify(desc.value)}`;
-  }
-  if (desc.nth === "first" || desc.nth === "last") return `${base} .${desc.nth}()`;
-  if (typeof desc.nth === "number") return `${base} .nth(${desc.nth})`;
-  return base;
-}
-
-/** 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);
-
-  // Wait for the element to be visible (playwright auto-wait), center it,
-  // and return its tap coordinates.
-  async function centerOf(page: Page, timeout: number): Promise<{ x: number; y: number }> {
-    const loc = pwLocator(page, desc);
-    await loc.waitFor({ state: "visible", timeout });
-    await loc.scrollIntoViewIfNeeded({ timeout });
-    const box = await loc.boundingBox();
-    if (!box) throw new Error(`mobile: ${label} vanished before it could be tapped`);
-    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
-  }
-
-  async function tap(opts?: { timeoutMs?: number; durationMs?: number }): Promise<void> {
-    await backend.pageOp("click", { selector: label }, async (page) => {
-      const { x, y } = await centerOf(page, opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
-      // Manual CDP touch (not playwright's tap()): RN Pressables need the
-      // press dwell — see rawTap in browser.ts.
-      await backend.rawTap(x, y, opts?.durationMs);
-    });
-  }
-
-  async function waitForVisible(opts?: { timeoutMs?: number }): Promise<void> {
-    await backend.pageOp("waitFor", { description: `${label} visible` }, async (page) => {
-      await pwLocator(page, desc).waitFor({
-        state: "visible",
-        timeout: opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS,
-      });
-    });
-  }
-
-  return {
-    tap,
-    async typeText(text, opts) {
-      // Two recorded events (click + type), same as a human: tap to focus,
-      // then insert the text.
-      await tap(opts);
-      await backend.type(text);
-    },
-    async clearText(opts) {
-      await backend.pageOp("evaluate", { description: `clear ${label}` }, async (page) => {
-        // playwright fill("") is the canonical React-safe clear (native
-        // value setter + input event, so RN-Web's controlled TextInput
-        // sees the change).
-        await pwLocator(page, desc).fill("", {
-          timeout: opts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS,
-        });
-      });
-    },
-    async scrollIntoView() {
-      await backend.pageOp("scrollTo", { selector: label }, async (page) => {
-        const loc = pwLocator(page, desc);
-        await loc.waitFor({ state: "visible", timeout: DEFAULT_ACTION_TIMEOUT_MS });
-        await loc.scrollIntoViewIfNeeded({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
-      });
-    },
-    waitFor: waitForVisible,
-    async assertVisible(opts) {
-      try {
-        await waitForVisible(opts);
-      } catch (e) {
-        const detail = e instanceof Error ? ` — ${e.message}` : "";
-        throw new Error(`expected ${label} to be visible${detail}`);
-      }
-    },
-    isVisible() {
-      // pageOp("evaluate", …) provenance-wraps the value at runtime; the
-      // cast matches (same pattern as browser.ts's evaluate).
-      return backend.pageOp("evaluate", { description: `${label} visible?` }, (page) =>
-        pwLocator(page, desc).isVisible(),
-      ) as unknown as Promise<Wrapped<boolean>>;
-    },
-    textContent() {
-      return backend.pageOp("evaluate", { description: `${label} text` }, (page) =>
-        pwLocator(page, desc).textContent({ timeout: DEFAULT_ACTION_TIMEOUT_MS }),
-      ) as Promise<Wrapped<string | null>>;
-    },
-    first() {
-      return makeLocator(backend, { ...desc, nth: "first" });
-    },
-    last() {
-      return makeLocator(backend, { ...desc, nth: "last" });
-    },
-    nth(index: number) {
-      return makeLocator(backend, { ...desc, nth: index });
-    },
-  };
-}
-
 // ────────────────────────────────────────────────────────────────────────
 // Mobile session
 // ────────────────────────────────────────────────────────────────────────
 
-/** A phone-emulated app session. Opened via `ctx.mobile(app)` already on the
- *  app, so there is no `navigate`; interactions are mobile-native. */
-export interface Mobile {
-  /** Current page URL. */
-  readonly url: string;
-  /** Current page `<title>`. */
-  readonly title: string;
-  /** Select by `testID` (RN-Web `data-testid`). The primary mobile selector. */
-  getByTestId(testId: string): MobileLocator;
-  /** Select by visible text (case-insensitive substring by default —
-   *  playwright semantics; `exact: true` for a case-sensitive whole-string
-   *  match, or pass a RegExp). */
-  getByText(text: string | RegExp, opts?: { exact?: boolean }): MobileLocator;
-  /** Select by ARIA role, optionally narrowed by accessible name. */
-  getByRole(role: string, opts?: { name?: string; exact?: boolean }): MobileLocator;
-  /** Select by `accessibilityLabel` (RN-Web `aria-label`). */
-  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>;
+/**
+ * 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>;
-  /** Wheel-scroll the viewport by a pixel delta. */
-  scroll(dx: number, dy: number): Promise<void>;
-  /** Press a named key (`"Enter"`, `"Backspace"`, …) on the focused element. */
-  pressKey(key: string): Promise<void>;
-  /** Navigate back in history (the device back gesture). */
-  back(): Promise<void>;
-  /** Low-level escape hatch: evaluate JS in the page (recorded, wrapped). */
-  evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
-  /**
-   * Install a script that runs before every *subsequent* document's own
-   * scripts (the Playwright `addInitScript` equivalent) — the deterministic
-   * way to plant shims/instrumentation that must win the race against the
-   * app bundle. Takes effect on the next navigation (e.g. a
-   * `location.assign` deep link), not the current document.
-   */
-  addInitScript(description: string, source: string): Promise<void>;
-  /** Low-level escape hatch: poll a JS expression until truthy (recorded). */
-  waitFor<T = unknown>(
-    description: string,
-    expression: string,
-    options?: { timeoutMs?: number; intervalMs?: number },
-  ): Promise<Wrapped<T>>;
-  /**
-   * Capture a PNG screenshot of the viewport and upload it as a
-   * downloadable artifact. Resolves to the artifact's `art_…` id
-   * (`spectest artifact download <id>`). Eval-only for now — throws with a
-   * clear message during test runs.
-   */
-  screenshot(): Promise<string>;
-  /** Close the session. Idempotent; drains pending rrweb events. */
-  close(): Promise<void>;
-}
-
-function wrapMobile(backend: MobileBackend): Mobile {
-  return {
-    get url() {
-      return backend.url;
-    },
-    get title() {
-      return backend.title;
-    },
-    getByTestId(testId) {
-      return makeLocator(backend, { kind: "testid", value: testId });
-    },
-    getByText(text, opts) {
-      if (text instanceof RegExp) {
-        return makeLocator(backend, {
-          kind: "text",
-          value: text.source,
-          regex: { source: text.source, flags: text.flags },
-        });
-      }
-      return makeLocator(backend, { kind: "text", value: text, exact: opts?.exact });
-    },
-    getByRole(role, opts) {
-      return makeLocator(backend, {
-        kind: "role",
-        value: role,
-        name: opts?.name,
-        nameExact: opts?.exact,
-      });
-    },
-    getByLabel(text) {
-      return makeLocator(backend, { kind: "label", value: text });
-    },
-    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 })",
-      );
-      const cx = vp.w / 2;
-      const cy = vp.h / 2;
-      const horiz = direction === "left" || direction === "right";
-      const dist = opts?.distance ?? Math.round((horiz ? vp.w : vp.h) * 0.5);
-      const dx = direction === "left" ? -dist : direction === "right" ? dist : 0;
-      const dy = direction === "up" ? -dist : direction === "down" ? dist : 0;
-      await backend.swipeBy(cx, cy, dx, dy);
-    },
-    scroll(dx, dy) {
-      return backend.scroll(dx, dy);
-    },
-    pressKey(key) {
-      return backend.press(key);
-    },
-    back() {
-      return backend.back();
-    },
-    evaluate(description, script) {
-      return backend.evaluate(description, script);
-    },
-    addInitScript(description, source) {
-      return backend.addInitScript(description, source);
-    },
-    waitFor(description, expression, options) {
-      return backend.waitFor(description, expression, options);
-    },
-    screenshot() {
-      return backend.screenshot();
-    },
-    close() {
-      return backend.close();
-    },
-  };
 }
 
 /**
@@ -413,15 +88,15 @@ export async function openMobile(opts: {
     url: opts.url,
     recorder: opts.recorder,
   });
-  return wrapMobile(backend);
+  // 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 — see the "Persistent sessions" section in
- * browser.ts). 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;
+ * 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: {
@@ -440,7 +115,7 @@ export async function openPersistentMobile(opts: {
     opts.recorder,
   );
   return {
-    mobile: wrapMobile(browser),
+    mobile: browser,
     attached,
     detach,
     safeAreaInsets: browser.safeAreaInsets,

package/src/recorder.ts

@@ -368,20 +368,17 @@ export interface EnvEvent extends BaseEvent {
   error?: string;
 }
 
-export type BrowserAction =
-  | "navigate"
-  | "evaluate"
-  | "addInitScript"
-  | "waitFor"
-  | "click"
-  | "type"
-  | "press"
-  | "scroll"
-  | "scrollTo"
-  | "back"
-  | "forward"
-  | "reload"
-  | "screenshot";
+// A browser step's action label. Since the Playwright-native surface exposes
+// the full locator method vocabulary (click/fill/press/getAttribute/…) plus
+// the session verbs (goto/goBack/evaluate/waitForFunction/screenshot/…), this
+// is an open string rather than a closed union — the value is the Playwright
+// 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",
+// "click", "dblclick", "tap", "fill", "clear", "press", "type", "scroll",
+// "check", "hover", "textContent", "inputValue", "count", "screenshot".
+export type BrowserAction = string;
 
 export interface BrowserEvent extends BaseEvent {
   kind: "browser";