@specific.dev/spectest 0.26.0 → 0.27.0

package/src/mobile.ts

@@ -1,133 +0,0 @@
-// 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,
-  };
-}