@itmetsam/samurai-framework 0.18.0 → 0.20.0

package/dist/assert/expect.d.ts

@@ -1,10 +1,15 @@
+import Page from "../browser/page.js";
 import Locator from "../locator/locator.js";
 import { LocatorAssertions } from "./locator-assertions.js";
+import { PageAssertions } from "./page-assertions.js";
 import { ValueAssertions } from "./value-assertions.js";
 export { takePendingAssertions } from "./pending-assertions.js";
 export { LocatorAssertions } from "./locator-assertions.js";
+export { PageAssertions } from "./page-assertions.js";
 export { ValueAssertions } from "./value-assertions.js";
 /** Auto-retrying assertions on a page element */
 export declare function expect(locator: Locator): LocatorAssertions;
+/** Auto-retrying assertions on the page URL and title */
+export declare function expect(page: Page): PageAssertions;
 /** Synchronous assertions on a plain value */
 export declare function expect<T>(value: T): ValueAssertions<T>;

package/dist/assert/expect.js

@@ -1,11 +1,16 @@
+import Page from "../browser/page.js";
 import Locator from "../locator/locator.js";
 import { LocatorAssertions } from "./locator-assertions.js";
+import { PageAssertions } from "./page-assertions.js";
 import { ValueAssertions } from "./value-assertions.js";
 export { takePendingAssertions } from "./pending-assertions.js";
 export { LocatorAssertions } from "./locator-assertions.js";
+export { PageAssertions } from "./page-assertions.js";
 export { ValueAssertions } from "./value-assertions.js";
 export function expect(value) {
-    return value instanceof Locator
-        ? new LocatorAssertions(value)
-        : new ValueAssertions(value);
+    if (value instanceof Locator)
+        return new LocatorAssertions(value);
+    if (value instanceof Page)
+        return new PageAssertions(value);
+    return new ValueAssertions(value);
 }

package/dist/assert/locator-assertions.d.ts

@@ -9,8 +9,13 @@ export declare class LocatorAssertions {
     constructor(locator: Locator, negated?: boolean);
     /** Inverts the next matcher: it retries until the condition is false */
     get not(): LocatorAssertions;
-    /** Re-reads the element until `check` passes or the timeout expires */
+    /**
+     * Re-reads the element until `check` passes or the timeout expires. With `mustExist`, a read of `null`
+     * (no element) never passes, with or without `.not`, and fails as "could not read"
+     */
     private assertEventually;
+    /** For matchers that need an element: `read` answers null when there is none, which never passes */
+    private assertExisting;
     toBeVisible(options?: LocatorAssertionOptions): Promise<void>;
     /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
     toHaveText(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
@@ -19,4 +24,14 @@ export declare class LocatorAssertions {
     toHaveValue(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
     toHaveAttribute(name: string, expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
     toHaveCount(expected: number, options?: LocatorAssertionOptions): Promise<void>;
+    /** The element is missing, or has no box or is hidden by CSS (the opposite of `toBeVisible`) */
+    toBeHidden(options?: LocatorAssertionOptions): Promise<void>;
+    /** The element exists and is neither `:disabled` nor `aria-disabled="true"`; a missing element never passes, not even with `.not` */
+    toBeEnabled(options?: LocatorAssertionOptions): Promise<void>;
+    /** A checked checkbox or radio input, or an element with `aria-checked="true"`; a missing element never passes, not even with `.not` */
+    toBeChecked(options?: LocatorAssertionOptions): Promise<void>;
+    /** The class attribute equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested on the attribute as written) */
+    toHaveClass(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    /** The computed value of a CSS property equals `expected` (string) or matches it (RegExp); `name` may be camelCase (`backgroundColor`) or kebab-case, `--custom` is kept */
+    toHaveCSS(name: string, expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
 }

package/dist/assert/locator-assertions.js

@@ -2,7 +2,7 @@ import { resolveTimeout } from "../config/timeouts.js";
 import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
 import { AssertionError } from "./assertion-error.js";
 import { track } from "./pending-assertions.js";
-import { textCheck } from "./text-match.js";
+import { classCheck, matchesText, textCheck } from "./text-match.js";
 export class LocatorAssertions {
     constructor(locator, negated = false) {
         this.locator = locator;
@@ -12,21 +12,24 @@ export class LocatorAssertions {
     get not() {
         return new LocatorAssertions(this.locator, !this.negated);
     }
-    /** Re-reads the element until `check` passes or the timeout expires */
-    assertEventually(matcher, expected, read, check, options) {
+    /**
+     * Re-reads the element until `check` passes or the timeout expires. With `mustExist`, a read of `null`
+     * (no element) never passes, with or without `.not`, and fails as "could not read"
+     */
+    assertEventually(matcher, expected, read, check, options, mustExist = false) {
         const name = this.negated ? `not.${matcher}` : matcher;
         return track(name, (async () => {
             const timeout = await resolveTimeout(options?.timeout);
             try {
-                await waitUntil(read, (actual) => check(actual) !== this.negated, {
-                    timeout,
-                });
+                await waitUntil(read, (actual) => mustExist && actual === null
+                    ? false
+                    : check(actual) !== this.negated, { timeout });
             }
             catch (err) {
                 if (!(err instanceof WaitTimeoutError))
                     throw err;
                 // Reads never resolve to undefined, so an undefined `last` means no read completed
-                if (err.last === undefined) {
+                if (err.last === undefined || (mustExist && err.last === null)) {
                     throw new Error(`expect(locator).${name}: could not read ${this.locator.selector} within ${timeout}ms`);
                 }
                 throw new AssertionError({
@@ -38,6 +41,10 @@ export class LocatorAssertions {
             }
         })());
     }
+    /** For matchers that need an element: `read` answers null when there is none, which never passes */
+    assertExisting(matcher, expected, read, check, options) {
+        return this.assertEventually(matcher, expected, read, (actual) => actual !== null && check(actual), options, true);
+    }
     toBeVisible(options) {
         return this.assertEventually("toBeVisible", true, () => this.locator.isVisible(), (visible) => visible, options);
     }
@@ -58,4 +65,24 @@ export class LocatorAssertions {
     toHaveCount(expected, options) {
         return this.assertEventually("toHaveCount", expected, () => this.locator.count(), (count) => count === expected, options);
     }
+    /** The element is missing, or has no box or is hidden by CSS (the opposite of `toBeVisible`) */
+    toBeHidden(options) {
+        return this.assertEventually("toBeHidden", true, () => this.locator.isVisible(), (visible) => !visible, options);
+    }
+    /** The element exists and is neither `:disabled` nor `aria-disabled="true"`; a missing element never passes, not even with `.not` */
+    toBeEnabled(options) {
+        return this.assertExisting("toBeEnabled", true, () => this.locator.enabledState(), (enabled) => enabled, options);
+    }
+    /** A checked checkbox or radio input, or an element with `aria-checked="true"`; a missing element never passes, not even with `.not` */
+    toBeChecked(options) {
+        return this.assertExisting("toBeChecked", true, () => this.locator.isChecked(), (checked) => checked, options);
+    }
+    /** The class attribute equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested on the attribute as written) */
+    toHaveClass(expected, options) {
+        return this.assertExisting("toHaveClass", expected, () => this.locator.classAttribute(), classCheck(expected), options);
+    }
+    /** The computed value of a CSS property equals `expected` (string) or matches it (RegExp); `name` may be camelCase (`backgroundColor`) or kebab-case, `--custom` is kept */
+    toHaveCSS(name, expected, options) {
+        return this.assertExisting("toHaveCSS", expected, () => this.locator.cssValue(name), (actual) => matchesText(actual, expected, "exact"), options);
+    }
 }

package/dist/assert/page-assertions.d.ts

@@ -0,0 +1,25 @@
+import type Page from "../browser/page.js";
+export interface PageAssertionOptions {
+    /** Time (ms) to keep retrying. Defaults to config `expect.timeout`, then 5000 */
+    timeout?: number;
+}
+export declare class PageAssertions {
+    private readonly page;
+    private readonly negated;
+    constructor(page: Page, negated?: boolean);
+    /** Inverts the next matcher: it retries until the condition is false */
+    get not(): PageAssertions;
+    /**
+     * Re-reads the page until `check` passes or the timeout expires. A read that throws on an open page
+     * (a navigation in progress) counts as "no value yet" and never passes, with or without `.not`;
+     * a closed page fails at once with the page's error
+     */
+    private assertEventually;
+    /**
+     * The page URL equals `expected` (string) or matches it (RegExp, tested on the full URL). A string starting
+     * with "/", "./" or "../" resolves against the base URL like `page.goto`; any other string must equal the URL
+     */
+    toHaveURL(expected: string | RegExp, options?: PageAssertionOptions): Promise<void>;
+    /** The trimmed page title equals `expected` (string, trimmed too) or matches it (RegExp) */
+    toHaveTitle(expected: string | RegExp, options?: PageAssertionOptions): Promise<void>;
+}

package/dist/assert/page-assertions.js

@@ -0,0 +1,67 @@
+import { resolveTimeout } from "../config/timeouts.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { AssertionError } from "./assertion-error.js";
+import { track } from "./pending-assertions.js";
+import { matchesText } from "./text-match.js";
+export class PageAssertions {
+    constructor(page, negated = false) {
+        this.page = page;
+        this.negated = negated;
+    }
+    /** Inverts the next matcher: it retries until the condition is false */
+    get not() {
+        return new PageAssertions(this.page, !this.negated);
+    }
+    /**
+     * Re-reads the page until `check` passes or the timeout expires. A read that throws on an open page
+     * (a navigation in progress) counts as "no value yet" and never passes, with or without `.not`;
+     * a closed page fails at once with the page's error
+     */
+    assertEventually(matcher, what, expectedOf, read, check, options) {
+        const name = this.negated ? `not.${matcher}` : matcher;
+        return track(name, (async () => {
+            // Resolved inside the tracked body: a throw (no base URL) rejects the tracked promise
+            const expected = expectedOf();
+            const timeout = await resolveTimeout(options?.timeout);
+            const safeRead = async () => {
+                try {
+                    return await read();
+                }
+                catch (err) {
+                    if (this.page.closed)
+                        throw err;
+                    return null;
+                }
+            };
+            try {
+                await waitUntil(safeRead, (actual) => actual !== null && check(actual, expected) !== this.negated, { timeout });
+            }
+            catch (err) {
+                if (!(err instanceof WaitTimeoutError))
+                    throw err;
+                if (err.last === undefined || err.last === null) {
+                    throw new Error(`expect(page).${name}: could not read the page ${what} within ${timeout}ms`);
+                }
+                throw new AssertionError({
+                    matcher: name,
+                    expected,
+                    actual: err.last,
+                    locator: "page",
+                });
+            }
+        })());
+    }
+    /**
+     * The page URL equals `expected` (string) or matches it (RegExp, tested on the full URL). A string starting
+     * with "/", "./" or "../" resolves against the base URL like `page.goto`; any other string must equal the URL
+     */
+    toHaveURL(expected, options) {
+        return this.assertEventually("toHaveURL", "URL", () => typeof expected === "string"
+            ? this.page.resolveURL(expected, "toHaveURL")
+            : expected, () => this.page.url(), (url, target) => matchesText(url, target, "exact"), options);
+    }
+    /** The trimmed page title equals `expected` (string, trimmed too) or matches it (RegExp) */
+    toHaveTitle(expected, options) {
+        return this.assertEventually("toHaveTitle", "title", () => (typeof expected === "string" ? expected.trim() : expected), async () => (await this.page.title()).trim(), (title, target) => matchesText(title, target, "exact"), options);
+    }
+}

package/dist/assert/text-match.d.ts

@@ -2,3 +2,5 @@
 export declare function matchesText(actual: string, expected: string | RegExp, mode: "exact" | "contains"): boolean;
 /** A check for a read that may find nothing (`null`): true when the text is there and matches */
 export declare function textCheck(expected: string | RegExp, mode: "exact" | "contains"): (actual: string | null) => boolean;
+/** A check for a class attribute: a string equals it after collapsing whitespace and trimming both sides, a RegExp tests it as written */
+export declare function classCheck(expected: string | RegExp): (actual: string) => boolean;

package/dist/assert/text-match.js

@@ -9,3 +9,10 @@ export function matchesText(actual, expected, mode) {
 export function textCheck(expected, mode) {
     return (actual) => actual !== null && matchesText(actual, expected, mode);
 }
+/** A check for a class attribute: a string equals it after collapsing whitespace and trimming both sides, a RegExp tests it as written */
+export function classCheck(expected) {
+    if (expected instanceof RegExp)
+        return (actual) => matchesText(actual, expected, "exact");
+    const normalize = (value) => value.replace(/\s+/g, " ").trim();
+    return (actual) => normalize(actual) === normalize(expected);
+}

package/dist/browser/page-navigation.d.ts

@@ -28,6 +28,8 @@ export interface NavigationDeps {
         timeout: number;
     }): Promise<void>;
 }
+/** Resolves a slash-led `url` against `base`; any other URL is returned as given */
+export declare function resolveRelativeURL(url: string, base: string): string;
 /** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
 export declare class PageNavigation {
     private connector;
@@ -40,6 +42,8 @@ export declare class PageNavigation {
     constructor(connector: BiDiConnector, contextId: string, deps: NavigationDeps);
     /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
     setBaseURL(url: string | undefined): void;
+    /** The full URL `url` stands for: slash-led URLs resolve against the base URL, others stay as given */
+    resolveURL(url: string, method?: string): string;
     goto(url: string, options?: NavigateOptions): Promise<NavigationResult>;
     navigateTo(url: string, options?: NavigateOptions | ReadinessState, protocol?: "http" | "https"): Promise<NavigationResult>;
     reload(options?: {

package/dist/browser/page-navigation.js

@@ -3,6 +3,12 @@ import { BiDiError } from "../transport/bidi-error.js";
 import { UnsupportedOperationError } from "../transport/unsupported.js";
 import { WaitTimeoutError } from "../wait/wait-until.js";
 import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
+/** A URL starting with "/", "./" or "../" */
+const RELATIVE_URL = /^\.{0,2}\//;
+/** Resolves a slash-led `url` against `base`; any other URL is returned as given */
+export function resolveRelativeURL(url, base) {
+    return RELATIVE_URL.test(url) ? new URL(url, base).href : url;
+}
 /** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
 export class PageNavigation {
     constructor(connector, contextId, deps) {
@@ -14,14 +20,18 @@ export class PageNavigation {
     setBaseURL(url) {
         this.baseURL = url;
     }
-    async goto(url, options) {
-        if (!/^\.{0,2}\//.test(url))
-            return this.navigateTo(url, options);
+    /** The full URL `url` stands for: slash-led URLs resolve against the base URL, others stay as given */
+    resolveURL(url, method = "goto") {
+        if (!RELATIVE_URL.test(url))
+            return url;
         const base = this.baseURL ?? peekRunSettings()?.baseURL;
         if (!base) {
-            throw new Error(`goto(): "${url}" needs a baseURL; set one in samurai.config.ts or the environment`);
+            throw new Error(`${method}(): "${url}" needs a baseURL; set one in samurai.config.ts or the environment`);
         }
-        return this.navigateTo(new URL(url, base).href, options);
+        return resolveRelativeURL(url, base);
+    }
+    async goto(url, options) {
+        return this.navigateTo(this.resolveURL(url), options);
     }
     async navigateTo(url, options, protocol) {
         const given = typeof options === "string" ? { wait: options } : (options ?? {});

package/dist/browser/page.d.ts

@@ -83,6 +83,8 @@ export default class Page {
     dispose(): Promise<void>;
     /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
     setBaseURL(url: string | undefined): void;
+    /** @internal The full URL `goto` would navigate to: a URL starting with "/", "./" or "../" resolves against the base URL, others stay as given. `method` names the caller in the error */
+    resolveURL(url: string, method?: string): string;
     /**
      * Navigates like `navigateTo`, but a URL starting with "/", "./" or "../" resolves against the base URL
      * (`setBaseURL`, else the environment's `baseURL`).

package/dist/browser/page.js

@@ -162,6 +162,10 @@ export default class Page {
     setBaseURL(url) {
         this.nav.setBaseURL(url);
     }
+    /** @internal The full URL `goto` would navigate to: a URL starting with "/", "./" or "../" resolves against the base URL, others stay as given. `method` names the caller in the error */
+    resolveURL(url, method) {
+        return this.nav.resolveURL(url, method);
+    }
     /**
      * Navigates like `navigateTo`, but a URL starting with "/", "./" or "../" resolves against the base URL
      * (`setBaseURL`, else the environment's `baseURL`).

package/dist/capabilities.d.ts

@@ -33,6 +33,12 @@ export declare const CAPABILITIES: {
     readonly outputDir: true;
     /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
     readonly flowNodeFolders: true;
+    /** `nodeFolder(nodeId)` from `./flows/run`: a flow node's folder under `outputDir`, so an app need not rebuild it. */
+    readonly nodeFolder: true;
+    /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
+    readonly assertionMatchers: 2;
+    /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
+    readonly pageAssertions: true;
 };
 /** The shape of {@link CAPABILITIES}. */
 export type Capabilities = typeof CAPABILITIES;

package/dist/capabilities.js

@@ -33,4 +33,10 @@ export const CAPABILITIES = {
     outputDir: true,
     /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
     flowNodeFolders: true,
+    /** `nodeFolder(nodeId)` from `./flows/run`: a flow node's folder under `outputDir`, so an app need not rebuild it. */
+    nodeFolder: true,
+    /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
+    assertionMatchers: 2,
+    /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
+    pageAssertions: true,
 };

package/dist/flows/run/index.d.ts

@@ -2,6 +2,7 @@
 export * from "./events.js";
 export { HANDLERS } from "./handlers/index.js";
 export type { Handler, HandlerRun, Outcome } from "./handlers/index.js";
+export { nodeFolder } from "./node-folder.js";
 export { runFlow, type RunFlowOptions } from "./run.js";
 export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
 export * from "./report.js";

package/dist/flows/run/index.js

@@ -1,6 +1,7 @@
 /** Running flows: handlers, the walker, a project's flow files. Node only; see `flows/core` for the pure half. */
 export * from "./events.js";
 export { HANDLERS } from "./handlers/index.js";
+export { nodeFolder } from "./node-folder.js";
 export { runFlow } from "./run.js";
 export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
 export * from "./report.js";

package/dist/flows/run/node-folder.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The folder a flow node's screenshots go in, relative to `runFlowInProject`'s `outputDir`, with `/` separators:
+ * `nodes/` and the node id cleaned for a file name. A node's screenshot paths are relative to this folder.
+ */
+export declare function nodeFolder(nodeId: string): string;

package/dist/flows/run/node-folder.js

@@ -0,0 +1,8 @@
+import { cleanName } from "../../browser/evidence.js";
+/**
+ * The folder a flow node's screenshots go in, relative to `runFlowInProject`'s `outputDir`, with `/` separators:
+ * `nodes/` and the node id cleaned for a file name. A node's screenshot paths are relative to this folder.
+ */
+export function nodeFolder(nodeId) {
+    return `nodes/${cleanName(nodeId)}`;
+}

package/dist/flows/run/project.js

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { cleanName } from "../../browser/evidence.js";
 import { DEFAULT_SRC_DIR } from "../../config/defaults.js";
 import { projectConfig } from "../../config/config.js";
 import { checkFlow, withKeys, } from "../core/index.js";
@@ -15,6 +14,7 @@ import TestRunner from "../../runner/test-runner.js";
 import { WorkerPool } from "../../runner/worker-pool.js";
 import { processWorkerFactory } from "../../runner/worker-process.js";
 import { readFlow } from "./files.js";
+import { nodeFolder } from "./node-folder.js";
 import { itemsOf, runOnPool } from "./node-pool.js";
 import { FlowCheckError, } from "./project-options.js";
 import { projectSteps } from "../steps/set.js";
@@ -198,7 +198,7 @@ async function walkFlowInProject(options) {
             runTests: async ({ nodeId, tests, onEvent, signal, browsers }) => {
                 // Each node gets a folder of its own: the same test in two nodes would overwrite its screenshots
                 const outputDir = options.outputDir !== undefined
-                    ? path.join(options.outputDir, "nodes", cleanName(nodeId))
+                    ? path.join(options.outputDir, ...nodeFolder(nodeId).split("/"))
                     : undefined;
                 if (pool)
                     return runOnPool(pool, itemsOf(tests, browsers ?? browsersFor({ project: config.browsers }), outputDir), onEvent, signal);

package/dist/locator/element-reads.d.ts

@@ -0,0 +1,4 @@
+/** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
+export declare const IS_CHECKED_BODY = "\n  const type = (el.getAttribute(\"type\") || \"\").toLowerCase();\n  const input = el.tagName === \"INPUT\" && (type === \"checkbox\" || type === \"radio\");\n  return (input && el.checked) || el.getAttribute(\"aria-checked\") === \"true\";";
+/** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
+export declare function cssPropertyName(name: string): string;

package/dist/locator/element-reads.js

@@ -0,0 +1,11 @@
+/** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
+export const IS_CHECKED_BODY = `
+  const type = (el.getAttribute("type") || "").toLowerCase();
+  const input = el.tagName === "INPUT" && (type === "checkbox" || type === "radio");
+  return (input && el.checked) || el.getAttribute("aria-checked") === "true";`;
+/** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
+export function cssPropertyName(name) {
+    if (name.startsWith("--"))
+        return name;
+    return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}

package/dist/locator/locator.d.ts

@@ -148,6 +148,14 @@ export default class Locator {
     count(): Promise<number>;
     /** Whether the element exists and is not disabled; does not wait */
     isEnabled(): Promise<boolean>;
+    /** Like `isEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+    enabledState(): Promise<boolean | null>;
+    /** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+    isChecked(): Promise<boolean | null>;
+    /** The class attribute as written ("" when the element has none), or null when the element is missing */
+    classAttribute(): Promise<string | null>;
+    /** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+    cssValue(name: string): Promise<string | null>;
     /** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
     isEditable(): Promise<boolean>;
     /** Wait for certain time (ms). Default: 300ms  */

package/dist/locator/locator.js

@@ -6,6 +6,7 @@ import { probeState, waitForActionable, waitForState, } from "./actionability.js
 import { ChainResolver } from "./chain-resolver.js";
 import { dropFiles, setInputFiles, } from "./file-actions.js";
 import { describeType, } from "./element-state.js";
+import { cssPropertyName, IS_CHECKED_BODY } from "./element-reads.js";
 import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
 import { CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, ATTACHED_ONLY, } from "./page-scripts.js";
 import { cssSelector, describeChain, describeSelector, labelSelector, roleSelector, testIdSelector, textSelector, xpathSelector, } from "./selector.js";
@@ -302,6 +303,23 @@ export default class Locator {
         const state = await this.probeState({ scroll: false, hitTest: false });
         return state.attached && state.enabled;
     }
+    /** Like `isEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+    async enabledState() {
+        const state = await this.probeState({ scroll: false, hitTest: false });
+        return state.attached ? state.enabled : null;
+    }
+    /** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+    async isChecked() {
+        return booleanOrNull(await this.callOnElement(null, IS_CHECKED_BODY));
+    }
+    /** The class attribute as written ("" when the element has none), or null when the element is missing */
+    async classAttribute() {
+        return stringOrNull(await this.callOnElement(null, `return el.getAttribute("class") ?? "";`));
+    }
+    /** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+    async cssValue(name) {
+        return stringOrNull(await this.callOnElement(null, `return getComputedStyle(el).getPropertyValue(name);`, ["name"], [cssPropertyName(name)]));
+    }
     /** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
     async isEditable() {
         const state = await this.probeState({ scroll: false, hitTest: false });
@@ -339,6 +357,13 @@ export default class Locator {
         await typeText(this.biDiConnector, this.contextId, keys);
     }
 }
+function booleanOrNull(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (value === null)
+        return null;
+    throw new Error(`Expected a boolean or null but received "${describeType(value)}"`);
+}
 function stringOrNull(value) {
     if (typeof value === "string")
         return value;

package/dist/recorder/expectation.d.ts

@@ -3,3 +3,8 @@ import type { Expectation } from "../steps/model.js";
 export declare function secretNameFor(hint: string | undefined): string;
 /** The assertion an Alt+click or a pick starts with: the value of a field, else the text (cut when long), else visible */
 export declare function expectationFor(text: string, value: string | undefined): Expectation;
+/**
+ * The URL a `toHaveURL` step is written with: its path, query and hash when that resolves against `base` back to
+ * exactly `url` (as `toHaveURL` resolves it), else the full URL
+ */
+export declare function urlForAssertion(url: string, base: string | undefined): string;

package/dist/recorder/expectation.js

@@ -18,3 +18,21 @@ export function expectationFor(text, value) {
         ? { matcher: "toHaveText", expected: text }
         : { matcher: "toContainText", expected: text.slice(0, TEXT_LIMIT).trim() };
 }
+/**
+ * The URL a `toHaveURL` step is written with: its path, query and hash when that resolves against `base` back to
+ * exactly `url` (as `toHaveURL` resolves it), else the full URL
+ */
+export function urlForAssertion(url, base) {
+    if (base === undefined)
+        return url;
+    try {
+        const parsed = new URL(url);
+        if (parsed.origin !== new URL(base).origin)
+            return url;
+        const candidate = parsed.pathname + parsed.search + parsed.hash;
+        return new URL(candidate, base).href === parsed.href ? candidate : url;
+    }
+    catch {
+        return url;
+    }
+}

package/dist/recorder/normalise.d.ts

@@ -1,4 +1,4 @@
-import type { Expectation, FileEntry, LocatorSpec, Step } from "../steps/model.js";
+import type { Expectation, FileEntry, LocatorSpec, PageExpectation, Step } from "../steps/model.js";
 /** What the recorder does to the step list: a new step at `index`, a step rewritten in place, or one taken out */
 export type RecorderEvent = {
     op: "insert";
@@ -41,6 +41,12 @@ export type Observation = {
     locator: LocatorSpec;
     not: boolean;
     expectation: Expectation;
+}
+/** The toolbar's Page panel: the page's URL or title */
+ | {
+    type: "expectPage";
+    not: boolean;
+    expectation: PageExpectation;
 } | {
     type: "insert";
     locator: LocatorSpec;

package/dist/recorder/normalise.js

@@ -47,6 +47,12 @@ export class Normaliser {
                     not: observation.not,
                     expectation: observation.expectation,
                 };
+            case "expectPage":
+                return {
+                    kind: "expectPage",
+                    not: observation.not,
+                    expectation: observation.expectation,
+                };
             case "insert":
                 return {
                     kind: "fill",

package/dist/recorder/options.d.ts

@@ -49,7 +49,7 @@ export interface RecorderOptions {
     initialGoto?: boolean;
     /** URLs inside it are written relative to it, as `page.goto` resolves them */
     baseURL?: string;
-    /** Shows the recorder toolbar in the page (pause, assert, insert, wait, screenshot, stop). Without it, no toolbar */
+    /** Shows the recorder toolbar in the page (pause, assert, page, insert, wait, screenshot, stop). Without it, no toolbar */
     toolbar?: ToolbarOptions;
     /** Records uploads (file inputs and drops) into the project's files folder. Without it, uploads aren't recorded */
     files?: FileRecording;

package/dist/recorder/recorder.js

@@ -180,6 +180,9 @@ export class Recorder {
             page: this.page,
             connector: this.connector,
             context: this.context,
+            ...(this.options.baseURL !== undefined && {
+                baseURL: this.options.baseURL,
+            }),
             mute: () => this.mute(),
             unmute: () => this.unmute(),
             observe: (observation) => this.emit(this.normaliser.observe(observation, Date.now())),

package/dist/recorder/toolbar/action-guard.d.ts

@@ -1,13 +1,13 @@
 import type { ActionReply } from "./protocol.js";
 import type { Message, Of } from "./types.js";
 /** The messages that expect a reply, and that a double click sends twice */
-type Replying = Of<"assert" | "insert" | "add-insertable">;
+type Replying = Of<"assert" | "assert-page" | "insert" | "add-insertable">;
 /**
  * Drops the repeat of an action that is running or was answered `{ ok: true }` (a double click: its first copy
  * answers), and lets a retry after `{ ok: false }` through.
  */
 export declare class ActionGuard {
-    /** Ids of `assert`, `insert` and `add-insertable` being processed */
+    /** Ids of `assert`, `assert-page`, `insert` and `add-insertable` being processed */
     private readonly inFlight;
     /** Ids `accept` let through whose `run` hasn't started yet */
     private readonly claimed;

package/dist/recorder/toolbar/action-guard.js

@@ -4,7 +4,7 @@
  */
 export class ActionGuard {
     constructor() {
-        /** Ids of `assert`, `insert` and `add-insertable` being processed */
+        /** Ids of `assert`, `assert-page`, `insert` and `add-insertable` being processed */
         this.inFlight = new Set();
         /** Ids `accept` let through whose `run` hasn't started yet */
         this.claimed = new Set();
@@ -14,6 +14,7 @@ export class ActionGuard {
     /** Whether to process `message`; call it as the message arrives, before queueing it */
     accept(message) {
         if (message.action !== "assert" &&
+            message.action !== "assert-page" &&
             message.action !== "insert" &&
             message.action !== "add-insertable")
             return true;