@specific.dev/spectest 0.21.0 → 0.23.0

package/src/daemon.ts

@@ -3946,7 +3946,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     // An attached session starts mid-page (no navigate event will fire) —
     // stamp the inherited URL so the dashboard can still label the replay.
     if (attached && session.record.initialUrl === undefined) {
-      session.record.initialUrl = browser.url;
+      session.record.initialUrl = browser.url();
     }
     browserDetaches.push(async () => {
       await detach();
@@ -3976,7 +3976,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     });
     if (safeAreaInsets) session.record.safeAreaInsets = safeAreaInsets;
     if (attached && session.record.initialUrl === undefined) {
-      session.record.initialUrl = mobile.url;
+      session.record.initialUrl = mobile.url();
     }
     browserDetaches.push(async () => {
       await detach();
@@ -4268,7 +4268,7 @@ async function evalCode(
       session.record.safeAreaInsets = browser.safeAreaInsets;
     }
     if (attached && session.record.initialUrl === undefined) {
-      session.record.initialUrl = browser.url;
+      session.record.initialUrl = browser.url();
     }
     browserDetaches.push(async () => {
       await detach();
@@ -4298,7 +4298,7 @@ async function evalCode(
     });
     if (safeAreaInsets) session.record.safeAreaInsets = safeAreaInsets;
     if (attached && session.record.initialUrl === undefined) {
-      session.record.initialUrl = mobile.url;
+      session.record.initialUrl = mobile.url();
     }
     browserDetaches.push(async () => {
       await detach();

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";
@@ -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 +
@@ -1594,6 +1608,32 @@ export interface DefinedEnvironment<
   project(opts: ProjectOpts<S, F>): Project<S, F>;
 }
 
+/**
+ * The `ctx` type for an environment, for typing shared test helpers without
+ * `any`. Instantiate with the environment from `defineEnvironment`:
+ *
+ * ```ts
+ * const env = defineEnvironment({ ... });
+ * export type AppCtx = Ctx<typeof env>;
+ *
+ * // A helper reaching into ctx.svc / ctx.fakes stays fully typed:
+ * async function runJob(ctx: AppCtx) {
+ *   await ctx.svc.db.client`SELECT 1`;
+ * }
+ * ```
+ *
+ * This is the same `ctx` an `env.test(...)` callback receives. The parent
+ * return type is left as `unknown` (helpers rarely touch `ctx.parent` — read
+ * it in the test body and pass the value in). Prefer this over `ctx: any`:
+ * an `any`-typed ctx also defeats the `expect(...)` overloads, silently
+ * resolving `expect(value)` to the `expect(locator)` overload so value
+ * matchers like `.toBe(...)` disappear.
+ */
+export type Ctx<E> =
+  E extends DefinedEnvironment<infer S, infer F>
+    ? TestContext<unknown, S, F>
+    : never;
+
 /**
  * Define an environment and get back a builder you can hang tests off.
  * The builder's `.test(...)` returns test cases typed against the
@@ -1820,7 +1860,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 +1925,192 @@ 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 emit ONE settled browser step (the
+  // locator label + replay seek point) and record ONE assertion nested under
+  // it via `sourceSeq` — so a web-first `expect(locator)` assertion carries
+  // the same provenance a value assertion does (`expect(await loc.isVisible())`
+  // renders identically). Without the anchor step these assertions floated as
+  // disconnected top-level "value ✓" rows with no element and no replay seek.
+  // `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 started = Date.now();
+    const deadline = started + (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) {
+        const sourceSeq = await probe.settle(matcher, Date.now() - started);
+        recordAssertion({
+          matcher,
+          negated,
+          passed: true,
+          actual: safeSerialize(actual),
+          expected: expected === undefined ? undefined : safeSerialize(expected),
+          message,
+          sourceSeq,
+        });
+        return;
+      }
+      if (Date.now() >= deadline) {
+        const msg = describe(actual);
+        const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
+        recordAssertion({
+          matcher,
+          negated,
+          passed: false,
+          actual: safeSerialize(actual),
+          expected: expected === undefined ? undefined : safeSerialize(expected),
+          error: msg,
+          message,
+          sourceSeq,
+        });
+        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