@specific.dev/spectest 0.122.0 → 0.123.0

package/dist/locator.d.ts

@@ -1,3 +1,4 @@
+import type { LocatorAssertionRequest } from "./playwright-assertions.js";
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
@@ -140,7 +141,7 @@ export declare function chainLabel(chain: Chain): string;
 /** The slice of the browser backend a locator needs. `pageOp` records one
  *  browser event and (when `wrap`) provenance-wraps the result so a later
  *  `expect(...)` nests under the step. `silentRead` runs a lowered read with
- *  NO recording/drain — the poll path for `expect(locator)` matchers, which
+ *  NO recording/drain — the assertion path for `expect(locator)` matchers, which
  *  must not emit one browser event per retry. */
 export interface LocatorBackend {
     pageOp<T>(action: string, fields: Partial<RecordableFields>, fn: (page: Page) => Promise<T>, opts?: {
@@ -154,30 +155,18 @@ export interface LocatorBackend {
      *  See {@link "./browser".MobileBackend.recordSettled}. */
     recordSettled(action: string, fields: Partial<RecordableFields>, waitedMs: number, error?: string): Promise<number | undefined>;
 }
-/** Silent (non-recorded) reads a locator exposes for `expect(...)` matchers to
- *  poll. See {@link getLocatorProbe}. */
+/** Native assertions and recording for a lazy Spectest locator. */
 export interface LocatorProbe {
-    /** Human label of the locator (for failure messages). */
     readonly label: string;
-    isVisible(): Promise<boolean>;
-    textContent(timeout?: number): Promise<string | null>;
-    innerText(timeout?: number): Promise<string>;
-    /** Every match's text — the array forms of `toHaveText`/`toContainText`,
-     *  which are about a list of elements and so must not go through the
-     *  single-element (strict) reads above. */
-    allTextContents(): Promise<string[]>;
-    allInnerTexts(): Promise<string[]>;
-    inputValue(timeout?: number): Promise<string>;
-    count(): Promise<number>;
-    /** The "did you mean…" block for a locator that matched nothing, or `""`.
-     *  See locator-hints.ts. */
+    /** Resolve the current page once per assertion; Playwright re-resolves the
+     * selector on that page throughout the assertion, including navigation. */
+    assert(request: LocatorAssertionRequest): Promise<void>;
+    /** Supplemental diagnostics, never part of deciding the assertion result. */
     nearMiss(): Promise<string>;
-    isEnabled(timeout?: number): Promise<boolean>;
-    isChecked(timeout?: number): Promise<boolean>;
-    /** After the silent poll settles, emit the single settled browser step this
+    /** After the native assertion settles, emit the single settled browser step this
      *  locator's `expect(...)` matcher assertion nests under, and return its seq
      *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
-     *  poll time, `error` marks the step failed on a timed-out matcher. Returns
+     *  assertion time, `error` marks the step failed on a failed matcher. Returns
      *  `undefined` when nothing is recording.
      *
      *  `opts.reveal` additionally stamps the element's rrweb node id for the
@@ -189,14 +178,13 @@ export interface LocatorProbe {
         reveal?: boolean;
     }): Promise<number | undefined>;
 }
-/** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
- *  session twin of {@link LocatorProbe}. Lives here, next to it, so `index.ts`
- *  can reach both seams without importing `browser.ts` (and with it
- *  playwright) at runtime. */
+/** Native page assertions, kept behind a seam so index.ts does not load
+ * Playwright when a project only imports configuration or value assertions. */
 export interface BrowserProbe {
-    /** Current main-frame URL. Synchronous, unrecorded, no rrweb drain. */
-    url(): string;
-    /** After the silent poll settles, emit the single settled browser step the
+    assertURL(negated: boolean, expected: import("./url-match.js").UrlPattern, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** After the native assertion settles, emit the single settled browser step the
      *  matcher's assertion nests under, and return its seq. Same contract as
      *  {@link LocatorProbe.settle}. */
     settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
@@ -207,9 +195,7 @@ export declare function attachBrowserProbe<T extends object>(session: T, probe:
 export declare function isBrowserSession(x: unknown): boolean;
 /** The probe branded onto a browser/mobile session by `buildBackend`. */
 export declare function getBrowserProbe(session: unknown): BrowserProbe;
-/** The silent-read probe for a locator — the seam `expect(locator)` matchers
- *  poll (in index.ts) without pulling playwright types or the backend into
- *  that module. */
+/** The assertion/recording seam used by index.ts without loading Playwright. */
 export declare function getLocatorProbe(loc: Locator): LocatorProbe;
 /** Per-session flavor of the `tap()` gesture. Desktop and mobile differ only
  *  here; every other locator method is platform-agnostic. */
@@ -233,9 +219,9 @@ export declare const mobileStrategy: ActionStrategy;
  * A lazy reference to element(s), resolved with auto-waiting at the moment an
  * action runs. Mirrors playwright-core's `Locator`: STRICT by default — a
  * locator resolving to multiple elements throws a strict-mode violation at
- * action time rather than silently acting on one. Narrow with `exact: true`,
- * a testid, `filter(...)`, or the explicit `first()`/`last()`/`nth(i)`
- * opt-outs.
+ * action time rather than silently acting on one. Scope to the intended
+ * container, an exact role/name, or a stable test ID. Use positional selection
+ * only when order is part of what the test verifies.
  */
 export interface Locator {
     /** Descendant CSS query, scoped to this locator's subtree. */
@@ -251,13 +237,15 @@ export interface Locator {
     filter(opts: FilterOptions): Locator;
     /** Intersect with another locator (both must match the same element). */
     and(other: Locator): Locator;
-    /** Union with another locator (either may match). */
+    /** Union with another locator (either may match). If both match, a
+     * single-element operation still fails strictness. */
     or(other: Locator): Locator;
-    /** Explicit strict-mode opt-out: the first resolved element. */
+    /** First resolved element. Use only when position is the intended contract;
+     * does not establish identity or relate this match to another locator. */
     first(): Locator;
-    /** Explicit strict-mode opt-out: the last resolved element. */
+    /** Last resolved element. Prefer a unique identity unless testing order. */
     last(): Locator;
-    /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
+    /** i-th resolved element (0-based). Prefer a unique identity unless testing order. */
     nth(index: number): Locator;
     click(opts?: ClickOptions): Promise<void>;
     dblclick(opts?: ClickOptions): Promise<void>;
@@ -312,11 +300,15 @@ export interface Locator {
     blur(opts?: TimeoutOption): Promise<void>;
     scrollIntoViewIfNeeded(opts?: TimeoutOption): Promise<void>;
     dragTo(target: Locator, opts?: TimeoutOption): Promise<void>;
+    /** One observed value; use `await expect(locator).toHaveText(...)` to
+     * retry until expected text appears. Wrapping preserves provenance, not retries. */
     textContent(opts?: TimeoutOption): Promise<Wrapped<string | null>>;
     innerText(opts?: TimeoutOption): Promise<Wrapped<string>>;
     innerHTML(opts?: TimeoutOption): Promise<Wrapped<string>>;
     inputValue(opts?: TimeoutOption): Promise<Wrapped<string>>;
     getAttribute(name: string, opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+    /** Immediate visibility observation. Use `await expect(locator).toBeVisible()`
+     * for readiness; use `.unwrap()` if branching on this observation. */
     isVisible(): Promise<Wrapped<boolean>>;
     isHidden(): Promise<Wrapped<boolean>>;
     isEnabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
@@ -324,8 +316,9 @@ export interface Locator {
     isChecked(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
     isEditable(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
     count(): Promise<Wrapped<number>>;
-    /** Resolve to one locator per current match (handle-free — each is pinned
-     *  with `nth(i)`). One recorded event. */
+    /** One locator per current match, using `nth(i)` (positions, not pinned
+     * identities). Does not wait for a list to finish loading; assert its ready
+     * state first, and prefer stable IDs if items can move during iteration. */
     all(): Promise<Locator[]>;
     allTextContents(): Promise<Wrapped<string[]>>;
     allInnerTexts(): Promise<Wrapped<string[]>>;

package/dist/locator.js

@@ -244,9 +244,7 @@ export function isBrowserSession(x) {
 export function getBrowserProbe(session) {
     return session[BROWSER_PROBE];
 }
-/** The silent-read probe for a locator — the seam `expect(locator)` matchers
- *  poll (in index.ts) without pulling playwright types or the backend into
- *  that module. */
+/** The assertion/recording seam used by index.ts without loading Playwright. */
 export function getLocatorProbe(loc) {
     return loc[PROBE];
 }
@@ -476,23 +474,23 @@ export function makeLocator(backend, strategy, chain) {
         const rec = { selector: label, target, ...fields };
         return backend.pageOp(action, rec, (page) => readable(page, () => withTarget(page, action, rec, fn)), { wrap: true });
     };
-    // Silent, non-recorded reads for expect(locator) matchers to poll.
+    // Native assertion and recording seam for expect(locator).
     const probe = {
         label,
-        isVisible: () => backend.silentRead((page) => lower(page, chain).isVisible()),
-        textContent: (timeout) => backend.silentRead((page) => lower(page, chain).textContent({ timeout })),
-        innerText: (timeout) => backend.silentRead((page) => lower(page, chain).innerText({ timeout })),
-        allTextContents: () => backend.silentRead((page) => lower(page, chain).allTextContents()),
-        allInnerTexts: () => backend.silentRead((page) => lower(page, chain).allInnerTexts()),
-        inputValue: (timeout) => backend.silentRead((page) => lower(page, chain).inputValue({ timeout })),
-        count: () => backend.silentRead((page) => lower(page, chain).count()),
+        assert: async (request) => {
+            const { assertLocator } = await import("./playwright-assertions.js");
+            return backend.silentRead((page) => assertLocator(lower(page, chain), request));
+        },
         nearMiss: () => backend.silentRead((page) => hintBlock(page)),
-        isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
-        isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
         settle: async (action, waitedMs, error, opts) => {
             const fields = { selector: label, target };
             if (opts && opts.reveal) {
-                await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+                try {
+                    await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+                }
+                catch {
+                    // A page closing after evaluation must not replace the assertion result.
+                }
             }
             return backend.recordSettled(action, fields, waitedMs, error);
         },

package/dist/playwright-assertions.d.ts

@@ -0,0 +1,11 @@
+import type { Locator, Page } from "playwright-core";
+import type { BrowserMatchers, LocatorMatchers } from "./index.js";
+export type LocatorAssertionRequest = {
+    [K in keyof LocatorMatchers]: {
+        matcher: K;
+        args: Parameters<LocatorMatchers[K]>;
+        negated: boolean;
+    };
+}[keyof LocatorMatchers];
+export declare function assertLocator(locator: Locator, request: LocatorAssertionRequest): Promise<void>;
+export declare function assertURL(page: Page, negated: boolean, ...[expected, options]: Parameters<BrowserMatchers["toHaveURL"]>): Promise<void>;

package/dist/playwright-assertions.js

@@ -0,0 +1,32 @@
+// Loaded only when a browser assertion runs. Use the public matcher API;
+// Playwright owns selector resolution, retries, deadlines and negation.
+import { expect } from "@playwright/test";
+import { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+import { globToRegExp } from "./url-match.js";
+const browserExpect = expect.configure({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
+export async function assertLocator(locator, request) {
+    const positive = browserExpect(locator);
+    const assertion = request.negated ? positive.not : positive;
+    switch (request.matcher) {
+        case "toBeVisible": return assertion.toBeVisible(...request.args);
+        case "toBeHidden": return assertion.toBeHidden(...request.args);
+        case "toHaveText": return assertion.toHaveText(...request.args);
+        case "toContainText": return assertion.toContainText(...request.args);
+        case "toHaveValue": return assertion.toHaveValue(...request.args);
+        case "toHaveCount": return assertion.toHaveCount(...request.args);
+        case "toBeEnabled": return assertion.toBeEnabled(...request.args);
+        case "toBeDisabled": return assertion.toBeDisabled(...request.args);
+        case "toBeChecked": return assertion.toBeChecked(...request.args);
+        default: {
+            const unsupported = request;
+            throw new Error(`Unsupported locator assertion: ${String(unsupported)}`);
+        }
+    }
+}
+export async function assertURL(page, negated, ...[expected, options]) {
+    const positive = browserExpect(page);
+    // Spectest has always accepted URL globs. Convert just that syntax; use
+    // native URL assertions for evaluation (including predicates and .not).
+    const pattern = typeof expected === "string" ? globToRegExp(expected) : expected;
+    await (negated ? positive.not : positive).toHaveURL(pattern, options);
+}

package/dist/text-match.d.ts

@@ -7,16 +7,9 @@
  */
 export declare function normalizeWhiteSpace(text: string): string;
 export interface TextMatchOptions {
-    /** Compare without regard to letter case. On a RegExp this adds the `i`
-     *  flag, as playwright's own `ignoreCase` does. */
+    /** Override case sensitivity, including a RegExp's `i` flag. */
     ignoreCase?: boolean;
 }
-/** The element's text equals `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export declare function matchesText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
-/** The element's text contains `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export declare function containsText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
 /** `" "` for an invisible character, the character itself otherwise.
  *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
  *  valid JSON string literal. */
@@ -31,9 +24,3 @@ export declare function escapeInvisible(s: string): string;
  * `"contains"` for the substring ones.
  */
 export declare function textDifferenceNote(actual: unknown, expected: unknown, mode: "equal" | "contains"): string;
-/** Every element's text equals the item at its position, and there are
- *  exactly as many elements as items. */
-export declare function matchesTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;
-/** The elements' texts contain every item, in order. Extra elements between
- *  the matches are allowed. */
-export declare function containsTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;

package/dist/text-match.js

@@ -1,25 +1,4 @@
-// Text comparison for the web-first matchers, and readable notes for the
-// failures that invisible characters cause.
-//
-// Two rules, and they are deliberately different:
-//
-//   * **Matching is Playwright's.** `expect(locator).toHaveText(...)` and
-//     `toContainText(...)` normalize whitespace on BOTH sides exactly as
-//     playwright's own text engine does (`normalizeWhiteSpace` in
-//     playwright-core). Without this the SDK disagreed with itself: the same
-//     string matched through `getByText("15 000 kr")` (playwright's engine,
-//     which normalizes) and failed through `toContainText("15 000 kr")`
-//     (ours, which did a raw `includes`). The case that reported it is
-//     Swedish number formatting — `Intl.NumberFormat("sv-SE")` groups
-//     thousands with U+00A0 NO-BREAK SPACE, and JavaScript's `\s` covers
-//     U+00A0, so normalization makes a typed space match it.
-//
-//   * **Diagnostics are wider.** A value the author compares themselves
-//     (`expect(body).toContain(...)`, `toHaveValue`) is still exact, as it
-//     must be — so when such a comparison fails on characters that print the
-//     same, the message has to say so. `textDifferenceNote` reports the
-//     invisible or look-alike characters that are the whole difference, and
-//     `escapeInvisible` makes the two printed strings differ on screen.
+// Text diagnostics only. Browser comparisons are delegated to Playwright.
 /** Characters that are invisible on screen (or print as an ordinary space)
  *  and their Unicode names, for a message a reader can act on. */
 const INVISIBLE_NAMES = {
@@ -82,30 +61,6 @@ const LOOKALIKES = {
 export function normalizeWhiteSpace(text) {
     return text.replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ");
 }
-function caseFold(s, opts) {
-    return opts?.ignoreCase ? s.toLowerCase() : s;
-}
-function withIgnoreCase(re, opts) {
-    if (!opts?.ignoreCase || re.flags.includes("i"))
-        return re;
-    return new RegExp(re.source, `${re.flags}i`);
-}
-/** The element's text equals `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export function matchesText(actual, expected, opts) {
-    const a = normalizeWhiteSpace(actual);
-    if (expected instanceof RegExp)
-        return withIgnoreCase(expected, opts).test(a);
-    return caseFold(a, opts) === caseFold(normalizeWhiteSpace(expected), opts);
-}
-/** The element's text contains `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export function containsText(actual, expected, opts) {
-    const a = normalizeWhiteSpace(actual);
-    if (expected instanceof RegExp)
-        return withIgnoreCase(expected, opts).test(a);
-    return caseFold(a, opts).includes(caseFold(normalizeWhiteSpace(expected), opts));
-}
 // ── Diagnostics ───────────────────────────────────────────────────────────
 /** `" "` for an invisible character, the character itself otherwise.
  *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
@@ -210,30 +165,3 @@ export function textDifferenceNote(actual, expected, mode) {
     }
     return "";
 }
-// ── Array forms (`toHaveText([...])` / `toContainText([...])`) ────────────
-//
-// Playwright's own rule, from its injected script: the expected items are
-// matched against the received texts **greedily, in order**, and the lengths
-// must agree for `toHaveText` but not for `toContainText`. So
-// `toContainText(["Two", "Four"])` passes against a four-row list, while
-// `toHaveText(["Two", "Four"])` does not.
-function matchesInOrder(actual, expected, item) {
-    let want = 0;
-    for (let i = 0; i < actual.length && want < expected.length; i++) {
-        if (item(actual[i], expected[want]))
-            want++;
-    }
-    return want === expected.length;
-}
-/** Every element's text equals the item at its position, and there are
- *  exactly as many elements as items. */
-export function matchesTextArray(actual, expected, opts) {
-    if (actual.length !== expected.length)
-        return false;
-    return matchesInOrder(actual, expected, (a, e) => matchesText(a, e, opts));
-}
-/** The elements' texts contain every item, in order. Extra elements between
- *  the matches are allowed. */
-export function containsTextArray(actual, expected, opts) {
-    return matchesInOrder(actual, expected, (a, e) => containsText(a, e, opts));
-}

package/dist/url-match.d.ts

@@ -9,3 +9,4 @@ export type UrlPattern = string | RegExp | ((url: URL) => boolean);
 export declare function matchesUrl(current: string, pattern: UrlPattern): boolean;
 /** Human display of a pattern, for timeline labels and failure messages. */
 export declare function describeUrlPattern(pattern: UrlPattern): string;
+export declare function globToRegExp(glob: string): RegExp;

package/dist/url-match.js

@@ -1,13 +1,9 @@
 // URL pattern matching — shared by `browser.waitForURL(...)` and
 // `expect(browser).toHaveURL(...)`.
 //
-// Both take the same pattern forms as Playwright (glob string | RegExp |
-// predicate over a `URL`), and both lower to `matchesUrl` here so the two
-// can never disagree: `waitForURL` hands playwright a predicate that calls
-// this rather than letting playwright apply its own glob dialect, and the
-// matcher polls it directly. Deliberately dependency-free so `index.ts` (the
-// module a project imports on the host, where playwright isn't installed) can
-// use it without pulling in `browser.ts`.
+// Both accept glob strings, RegExp, or predicates over a URL. waitForURL
+// uses matchesUrl; the assertion adapter passes regexes/predicates directly
+// to Playwright and compiles string globs with the same globToRegExp helper.
 /** Whether `current` (a full URL string) matches `pattern`. */
 export function matchesUrl(current, pattern) {
     if (typeof pattern === "function") {
@@ -34,9 +30,9 @@ export function describeUrlPattern(pattern) {
         return String(pattern);
     return JSON.stringify(pattern);
 }
-// Compiled globs are cached: a matcher polls the same pattern every 50ms.
+// Reuse compiled globs across waits and assertions.
 const GLOB_CACHE = new Map();
-function globToRegExp(glob) {
+export function globToRegExp(glob) {
     const hit = GLOB_CACHE.get(glob);
     if (hit)
         return hit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,10 +54,11 @@
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
+    "@playwright/test": "1.61.1",
     "@xterm/headless": "^5.5.0",
     "acorn": "8.18.0",
     "dns-packet": "^5.6.1",
-    "playwright-core": "^1.61.1",
+    "playwright-core": "1.61.1",
     "ws": "^8.20.1"
   },
   "devDependencies": {

package/src/browser.ts

@@ -2082,9 +2082,8 @@ function buildBackend(
         fields,
         async () => {
           try {
-            // Always a predicate, never playwright's own glob: `matchesUrl`
-            // is then the single matching implementation shared with
-            // `expect(browser).toHaveURL`.
+            // Preserve Spectest's glob dialect. URL assertions use the same
+            // glob compiler through their native matcher adapter.
             await holder.page.waitForURL((u: URL) => matchesUrl(u.href, pattern), {
               timeout: timeoutMs,
               waitUntil: options.waitUntil ?? "commit",
@@ -2310,12 +2309,15 @@ function buildBackend(
       return instrumented(action, fields, () => fn(holder.page), opts);
     },
   };
-  // The seam `expect(browser).toHaveURL(...)` polls: a silent URL read plus
+  // The seam `expect(browser).toHaveURL(...)` uses: a native assertion plus
   // the single settled step its assertion nests under — the session twin of
   // the locator probe, and what brands this object as a browser session for
   // `expect`'s overload dispatch.
   attachBrowserProbe(backend, {
-    url: () => holder.page.url(),
+    assertURL: async (negated, expected, opts) => {
+      const { assertURL } = await import("./playwright-assertions.js");
+      await assertURL(holder.page, negated, expected, opts);
+    },
     settle: (action, waitedMs, error) =>
       backend.recordSettled(action, { url: holder.page.url() }, waitedMs, error),
   });