@specific.dev/spectest 0.20.0 → 0.22.0

package/src/index.ts

@@ -44,15 +44,29 @@ export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 
-export type { Browser, BrowserOptions } from "./browser.js";
+export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
+// Playwright-native locators — the select-then-act surface shared by
+// `ctx.browser()` and `ctx.mobile()`. `Locator` mirrors playwright-core's
+// Locator (getBy*/filter/first/nth/click/fill/textContent/…, STRICT mode).
+export type {
+  Locator,
+  GetByRoleOptions,
+  GetByTextOptions,
+  FilterOptions,
+  ClickOptions,
+  BoundingBox,
+} from "./locator.js";
+import type { Locator } from "./locator.js";
+import { isLocator, getLocatorProbe, DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+
 // Mobile (Expo / React Native Web) surface: a phone-emulated session driven
-// with locators + touch gestures, replayed inside a phone bezel. Opened with
-// `ctx.mobile(ctx.svc.app)` where the app is registered via the `expo()`
-// component.
-export type { Mobile, MobileLocator, MobileApp } from "./mobile.js";
+// with the same locators + touch gestures, replayed inside a phone bezel.
+// Opened with `ctx.mobile(ctx.svc.app)` where the app is registered via the
+// `expo()` component.
+export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
@@ -121,14 +135,14 @@ export interface ServiceConfig {
    * postgres's `docker-entrypoint.sh` initialization. Mutually
    * exclusive with {@link command}.
    */
-  args?: string[];
+  args?: readonly string[];
   env?: Record<string, string>;
   /**
    * Ports the container listens on. Advisory only — surfaced in
    * `spectest list` output. Peer services reach each other by `<service>:<port>`
    * without any port declaration.
    */
-  ports?: number[];
+  ports?: readonly number[];
   /**
    * Extra DNS names this service answers to inside the environment.
    * Each entry must be a fully-qualified, multi-label hostname (e.g.
@@ -144,7 +158,7 @@ export interface ServiceConfig {
    * answers to `<name>.internal` in addition to its bare `<name>`, and
    * user-supplied hostnames may not end in `.internal`.
    */
-  hostnames?: string[];
+  hostnames?: readonly string[];
   /**
    * Expose this service over HTTPS via a TLS-terminating reverse proxy
    * hosted in the spectest-daemon. Each entry maps a fully-qualified
@@ -161,9 +175,9 @@ export interface ServiceConfig {
    * multi-label, lowercase, no `.internal` suffix, no collision with
    * services, other service TLS hostnames, or fakes.
    */
-  tls?: ServiceTls[];
+  tls?: readonly ServiceTls[];
   /** Bind-mounted volumes for state that survives snapshot/fork. */
-  volumes?: VolumeMount[];
+  volumes?: readonly VolumeMount[];
   /**
    * Files seeded into the container's filesystem **before it starts**.
    * Each entry's `content` is written to a VM-host staging path and
@@ -173,9 +187,9 @@ export interface ServiceConfig {
    * `/etc/rancher/k3s/registries.yaml`, which must exist before
    * `k3s server` starts.
    */
-  files?: FileMount[];
+  files?: readonly FileMount[];
   /** Other services (keys in the services map) that must be ready first. */
-  dependsOn?: string[];
+  dependsOn?: readonly string[];
   readyCheck?: ReadyCheck;
   /** Container workdir override. */
   workdir?: string;
@@ -191,7 +205,7 @@ export interface ServiceConfig {
    * non-persistent. Snapshots/forks preserve tmpfs contents along with
    * the rest of process memory.
    */
-  tmpfs?: string[];
+  tmpfs?: readonly string[];
   /**
    * Cgroup namespace mode — `"host"` or `"private"`. Omit for docker's
    * default. k3s needs `"host"` so its embedded containerd can manage
@@ -685,7 +699,7 @@ export type ServiceImage =
        */
       content: string;
       /** Extra glob patterns to exclude from the build context. */
-      exclude?: string[];
+      exclude?: readonly string[];
     };
 
 export interface VolumeMount {
@@ -1082,9 +1096,9 @@ export interface TestContext<
    * services: { app: expo() }
    * // in a test:
    * const m = await ctx.mobile(ctx.svc.app);
-   * await m.getByTestId("email").typeText("a@b.com");
-   * await m.getByText("Sign in").tap();
-   * await m.getByText(/Welcome/).assertVisible();
+   * await m.getByTestId("email").fill("a@b.com");
+   * await m.getByRole("button", { name: "Sign in" }).tap();
+   * await expect(m.getByText(/Welcome/)).toBeVisible();
    * ```
    *
    * The session emulates the latest iPhone (viewport + DPR + mobile UA +
@@ -1279,7 +1293,7 @@ export interface FakeDefinition<
    * lowercase, no `.internal` suffix, no collisions with services or
    * other fakes.
    */
-  hostnames: string[];
+  hostnames: readonly string[];
   /** TCP port the fake listens on. Default `80`. */
   port?: number;
   /**
@@ -1324,7 +1338,7 @@ export interface FakeDefinition<
    * files, the config hash, or a cassette. Not part of the authoring
    * surface; `JSON.stringify` ignores it (fakes never serialize to config).
    */
-  secretRefs?: string[];
+  secretRefs?: readonly string[];
 }
 
 /**
@@ -1820,7 +1834,49 @@ export interface Expectation extends Matchers {
   not: Matchers;
 }
 
-export function expect(actual: Provenanced, message?: string): Expectation {
+/**
+ * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
+ * `expect(locator)` matchers. Each polls the element until it passes or a
+ * deadline elapses (default 5 s, `{ timeout }` overrides) and records an
+ * assertion event just like a value `expect`. `await` them — they are async.
+ */
+export interface LocatorMatchers {
+  /** The element is present and visible. */
+  toBeVisible(opts?: { timeout?: number }): Promise<void>;
+  /** The element is absent or hidden. */
+  toBeHidden(opts?: { timeout?: number }): Promise<void>;
+  /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
+  toHaveText(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
+  /** The element's text contains `expected`. */
+  toContainText(expected: string, opts?: { timeout?: number }): Promise<void>;
+  /** The input's value equals `expected` (or matches a RegExp). */
+  toHaveValue(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
+  /** The locator resolves to exactly `expected` elements. */
+  toHaveCount(expected: number, opts?: { timeout?: number }): Promise<void>;
+  toBeEnabled(opts?: { timeout?: number }): Promise<void>;
+  toBeDisabled(opts?: { timeout?: number }): Promise<void>;
+  toBeChecked(opts?: { timeout?: number }): Promise<void>;
+}
+
+export interface LocatorAssertion extends LocatorMatchers {
+  /** Negate every matcher (retries until the negated condition holds). */
+  not: LocatorMatchers;
+}
+
+// `expect(locator)` returns the async web-first matchers; `expect(value)` the
+// synchronous value matchers. The Locator overload is listed first so a
+// locator (an object with no `unwrap`, hence not `Provenanced`) resolves to it.
+export function expect(actual: Locator, message?: string): LocatorAssertion;
+export function expect(actual: Provenanced, message?: string): Expectation;
+export function expect(
+  actual: Provenanced | Locator,
+  message?: string,
+): Expectation | LocatorAssertion {
+  if (isLocator(actual)) return buildLocatorAssertion(actual, message);
+  return expectValue(actual, message);
+}
+
+function expectValue(actual: Provenanced, message?: string): Expectation {
   // The first parameter is typed to the {@link Provenanced} family so a raw
   // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —
   // every assertion that reaches the timeline this way carries a provenance link
@@ -1843,6 +1899,182 @@ export function expect(actual: Provenanced, message?: string): Expectation {
   return buildMatchers(adoptNullishTag(actual), false, message);
 }
 
+// ── expect(locator): auto-retrying web-first matchers ─────────────────────
+
+/** Poll interval for locator matchers. */
+const LOCATOR_POLL_MS = 50;
+
+function buildLocatorAssertion(loc: Locator, message?: string): LocatorAssertion {
+  return Object.assign(buildLocatorMatchers(loc, false, message), {
+    not: buildLocatorMatchers(loc, true, message),
+  });
+}
+
+function buildLocatorMatchers(
+  loc: Locator,
+  negated: boolean,
+  message?: string,
+): LocatorMatchers {
+  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.
+  const run = async (
+    matcher: string,
+    timeout: number | undefined,
+    check: () => Promise<{ satisfied: boolean; actual: unknown }>,
+    describe: (actual: unknown) => string,
+    expected?: unknown,
+  ): Promise<void> => {
+    const deadline = Date.now() + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+    let actual: unknown;
+    for (;;) {
+      let satisfied: boolean;
+      try {
+        const r = await check();
+        satisfied = r.satisfied;
+        actual = r.actual;
+      } catch (err) {
+        if (Date.now() < deadline) {
+          await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+          continue;
+        }
+        satisfied = false;
+        actual = `<error: ${(err as Error)?.message ?? String(err)}>`;
+      }
+      const passed = satisfied !== negated;
+      if (passed) {
+        recordAssertion({
+          matcher,
+          negated,
+          passed: true,
+          actual: safeSerialize(actual),
+          expected: expected === undefined ? undefined : safeSerialize(expected),
+          message,
+        });
+        return;
+      }
+      if (Date.now() >= deadline) {
+        const msg = describe(actual);
+        recordAssertion({
+          matcher,
+          negated,
+          passed: false,
+          actual: safeSerialize(actual),
+          expected: expected === undefined ? undefined : safeSerialize(expected),
+          error: msg,
+          message,
+        });
+        throw new ExpectationError(msg);
+      }
+      await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+    }
+  };
+
+  const not = negated ? " not" : "";
+  const matchesText = (v: string, expected: string | RegExp): boolean =>
+    expected instanceof RegExp ? expected.test(v) : v === expected;
+
+  return {
+    toBeVisible: (opts) =>
+      run(
+        "toBeVisible",
+        opts?.timeout,
+        async () => {
+          const v = await probe.isVisible();
+          return { satisfied: v, actual: v };
+        },
+        () => `expected ${probe.label}${not} to be visible`,
+      ),
+    toBeHidden: (opts) =>
+      run(
+        "toBeHidden",
+        opts?.timeout,
+        async () => {
+          const v = await probe.isVisible();
+          return { satisfied: !v, actual: v };
+        },
+        () => `expected ${probe.label}${not} to be hidden`,
+      ),
+    toHaveText: (expected, opts) =>
+      run(
+        "toHaveText",
+        opts?.timeout,
+        async () => {
+          const t = (await probe.textContent(opts?.timeout)) ?? "";
+          return { satisfied: matchesText(t.trim(), expected), actual: t };
+        },
+        (a) => `expected ${probe.label}${not} to have text ${fmt(expected)}, got ${fmt(a)}`,
+        expected instanceof RegExp ? String(expected) : expected,
+      ),
+    toContainText: (expected, opts) =>
+      run(
+        "toContainText",
+        opts?.timeout,
+        async () => {
+          const t = (await probe.textContent(opts?.timeout)) ?? "";
+          return { satisfied: t.includes(expected), actual: t };
+        },
+        (a) => `expected ${probe.label}${not} to contain text ${fmt(expected)}, got ${fmt(a)}`,
+        expected,
+      ),
+    toHaveValue: (expected, opts) =>
+      run(
+        "toHaveValue",
+        opts?.timeout,
+        async () => {
+          const v = await probe.inputValue(opts?.timeout);
+          return { satisfied: matchesText(v, expected), actual: v };
+        },
+        (a) => `expected ${probe.label}${not} to have value ${fmt(expected)}, got ${fmt(a)}`,
+        expected instanceof RegExp ? String(expected) : expected,
+      ),
+    toHaveCount: (expected, opts) =>
+      run(
+        "toHaveCount",
+        opts?.timeout,
+        async () => {
+          const c = await probe.count();
+          return { satisfied: c === expected, actual: c };
+        },
+        (a) => `expected ${probe.label}${not} to have count ${expected}, got ${fmt(a)}`,
+        expected,
+      ),
+    toBeEnabled: (opts) =>
+      run(
+        "toBeEnabled",
+        opts?.timeout,
+        async () => {
+          const v = await probe.isEnabled(opts?.timeout);
+          return { satisfied: v, actual: v };
+        },
+        () => `expected ${probe.label}${not} to be enabled`,
+      ),
+    toBeDisabled: (opts) =>
+      run(
+        "toBeDisabled",
+        opts?.timeout,
+        async () => {
+          const v = await probe.isEnabled(opts?.timeout);
+          return { satisfied: !v, actual: v };
+        },
+        () => `expected ${probe.label}${not} to be disabled`,
+      ),
+    toBeChecked: (opts) =>
+      run(
+        "toBeChecked",
+        opts?.timeout,
+        async () => {
+          const v = await probe.isChecked(opts?.timeout);
+          return { satisfied: v, actual: v };
+        },
+        () => `expected ${probe.label}${not} to be checked`,
+      ),
+  };
+}
+
 /**
  * Assert on a value with **no provenance** — a computed number, a raw
  * WebSocket frame, anything that didn't flow from a recorded op. `message` is