@itmetsam/samurai-framework 0.17.0 → 0.19.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

@@ -31,6 +31,12 @@ export declare const CAPABILITIES: {
     readonly recorderStartStatus: true;
     /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
     readonly outputDir: true;
+    /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
+    readonly flowNodeFolders: 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

@@ -31,4 +31,10 @@ export const CAPABILITIES = {
     recorderStartStatus: true,
     /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
     outputDir: true,
+    /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
+    flowNodeFolders: 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/handlers/support.js

@@ -7,7 +7,7 @@ export const fail = (e) => ({
 export async function runNodeTests(node, run, list) {
     let result;
     try {
-        result = await run.runTests(list, (e) => run.onTestEvent(node.id, e), run.nodeBrowsers?.[node.id]);
+        result = await run.runTests(node.id, list, (e) => run.onTestEvent(node.id, e), run.nodeBrowsers?.[node.id]);
     }
     catch (e) {
         return fail(e);

package/dist/flows/run/handlers/types.d.ts

@@ -14,7 +14,7 @@ export interface HandlerRun {
     /** The browsers of the nodes that have their own (a Group node's group); the others use the project's */
     nodeBrowsers?: Record<string, SupportedBrowser[]>;
     signal: AbortSignal;
-    runTests: (tests: NodeTest[], onEvent: (e: RunEvent) => void, browsers?: SupportedBrowser[]) => Promise<"passed" | "failed" | "cancelled">;
+    runTests: (nodeId: string, tests: NodeTest[], onEvent: (e: RunEvent) => void, browsers?: SupportedBrowser[]) => Promise<"passed" | "failed" | "cancelled">;
     sleep: (ms: number, signal: AbortSignal) => Promise<void>;
     onTestEvent: (nodeId: string, e: RunEvent) => void;
     /** Definitions of kinds core doesn't have (steps), for expression scopes */

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

@@ -4,6 +4,6 @@ import type { WorkItem } from "../../runner/worker-protocol.js";
 import type { SupportedBrowser } from "../../types/browser.js";
 import type { NodeTest } from "./events.js";
 /** The work items of a node: each test in each browser, the browsers one after the other */
-export declare function itemsOf(tests: NodeTest[], browsers: readonly SupportedBrowser[]): WorkItem[];
+export declare function itemsOf(tests: NodeTest[], browsers: readonly SupportedBrowser[], outputDir?: string): WorkItem[];
 /** Runs the tests of a node on the pool and reports them as a run would */
 export declare function runOnPool(pool: Pick<WorkerPool, "run">, items: WorkItem[], onEvent: (event: RunEvent) => void, signal: AbortSignal): Promise<"passed" | "failed" | "cancelled">;

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

@@ -1,7 +1,12 @@
 /** The work items of a node: each test in each browser, the browsers one after the other */
-export function itemsOf(tests, browsers) {
+export function itemsOf(tests, browsers, outputDir) {
     return browsers
-        .flatMap((browser) => tests.map((t) => ({ file: t.file, testName: t.name, browser })))
+        .flatMap((browser) => tests.map((t) => ({
+        file: t.file,
+        testName: t.name,
+        browser,
+        ...(outputDir !== undefined && { outputDir }),
+    })))
         .map((item, index) => ({ ...item, index }));
 }
 /** Runs the tests of a node on the pool and reports them as a run would */

package/dist/flows/run/project-options.d.ts

@@ -20,7 +20,11 @@ export interface RunFlowInProjectOptions extends ProjectOptions {
     /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
     unsupported?: "fail" | "skip";
     port?: number;
-    /** The folder the tests' named screenshots go in, instead of `<project>/result` (see `runTests`). Relative to the project folder */
+    /**
+     * The folder for the tests' named screenshots, instead of `<project>/result` (see `runTests`). Each node writes to
+     * `nodes/<node id>/` inside it, so a test that runs in two nodes keeps both sets; screenshot paths in a node's
+     * results are relative to that folder. Relative to the project folder
+     */
     outputDir?: string;
     /**
      * How many worker processes the tests of the whole run share: a number, or a percentage like `"50%"`. Unset

package/dist/flows/run/project.js

@@ -1,4 +1,5 @@
 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";
@@ -176,9 +177,6 @@ async function walkFlowInProject(options) {
                 ...(options.headless !== undefined && {
                     headless: options.headless,
                 }),
-                ...(options.outputDir !== undefined && {
-                    outputDir: options.outputDir,
-                }),
                 files,
                 basePort: options.port ?? DEFAULT_PORT,
                 ...(retries > 0 && { retries }),
@@ -197,9 +195,13 @@ async function walkFlowInProject(options) {
             unsupported,
             handlers: { ...HANDLERS, ...steps.handlers },
             nodes: steps.nodes,
-            runTests: async ({ tests, onEvent, signal, browsers }) => {
+            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))
+                    : undefined;
                 if (pool)
-                    return runOnPool(pool, itemsOf(tests, browsers ?? browsersFor({ project: config.browsers })), onEvent, signal);
+                    return runOnPool(pool, itemsOf(tests, browsers ?? browsersFor({ project: config.browsers }), outputDir), onEvent, signal);
                 const summary = await run({
                     projectDir,
                     config,
@@ -217,9 +219,7 @@ async function walkFlowInProject(options) {
                     files: [...new Set(tests.map((t) => t.file))],
                     testNames: tests.map((t) => t.name),
                     reportPath: false,
-                    ...(options.outputDir !== undefined && {
-                        outputDir: options.outputDir,
-                    }),
+                    ...(outputDir !== undefined && { outputDir }),
                     signal,
                     onEvent,
                 });

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

@@ -20,6 +20,8 @@ export interface RunFlowOptions {
     signal?: AbortSignal;
     onEvent?: (event: FlowEvent) => void;
     runTests: (input: {
+        /** The node the tests are for: a node runs at most once in a run */
+        nodeId: string;
         tests: NodeTest[];
         onEvent: (e: RunEvent) => void;
         signal: AbortSignal;

package/dist/flows/run/run.js

@@ -34,7 +34,8 @@ export async function runFlow(options) {
         ...(options.nodeBrowsers && { nodeBrowsers: options.nodeBrowsers }),
         signal,
         sleep: options.sleep ?? defaultSleep,
-        runTests: (tests, onTestEvent, browsers) => options.runTests({
+        runTests: (nodeId, tests, onTestEvent, browsers) => options.runTests({
+            nodeId,
             tests,
             onEvent: onTestEvent,
             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;