@itmetsam/samurai-framework 0.17.0 → 0.19.0

package/dist/recorder/toolbar/source/views-panels.d.ts

@@ -1,2 +1,2 @@
-/** Views: the Assert, Insert, New, Wait and Screenshot panels. A slice of the toolbar function: it shares one closure with its neighbours, see `../source.ts`. */
+/** Views: the Assert, Page, Insert, New, Wait and Screenshot panels. A slice of the toolbar function: it shares one closure with its neighbours, see `../source.ts`. */
 export declare const VIEWS_PANELS_JS: string;

package/dist/recorder/toolbar/source/views-panels.js

@@ -1,8 +1,18 @@
-/** Views: the Assert, Insert, New, Wait and Screenshot panels. A slice of the toolbar function: it shares one closure with its neighbours, see `../source.ts`. */
+/** Views: the Assert, Page, Insert, New, Wait and Screenshot panels. A slice of the toolbar function: it shares one closure with its neighbours, see `../source.ts`. */
 export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher) =>
     (matcher === "toHaveValue" && info.value === undefined) ||
     (matcher === "toHaveAttribute" && info.attributes.length === 0) ||
-    (matcher === "toHaveCount" && info.counts.length === 0);
+    (matcher === "toHaveCount" && info.counts.length === 0) ||
+    (matcher === "toBeChecked" && !info.checkable) ||
+    (matcher === "toBeEnabled" && !info.disableable) ||
+    (matcher === "toHaveClass" && !info.className);
+  // The computed value, as toHaveCSS reads it: camelCase names become kebab-case, --custom is kept
+  const cssValueOf = (el, name) => {
+    const trimmed = name.trim();
+    if (!trimmed) return "";
+    const property = trimmed.startsWith("--") ? trimmed : trimmed.replace(/[A-Z]/g, (letter) => "-" + letter.toLowerCase());
+    try { return getComputedStyle(el).getPropertyValue(property); } catch (err) { return ""; }
+  };
   const prefill = (a, matcher) => {
     const info = a.info;
     if (matcher === "toHaveAttribute") {
@@ -13,6 +23,8 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
       const found = info.counts[a.countIndex];
       return found ? String(found.count) : "";
     }
+    if (matcher === "toHaveClass") return info.className || "";
+    if (matcher === "toHaveCSS") return a.cssValue;
     if (matcher === info.first.matcher && info.first.expected !== undefined) return info.first.expected;
     if (matcher === "toHaveText" || matcher === "toContainText") return info.text;
     if (matcher === "toHaveValue") return info.value || "";
@@ -21,7 +33,12 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
   const assertValue = (a) => {
     const info = a.info;
     const expected = (type) => h("input", { type, class: "in", "data-field": "expected", value: a.expected, "data-enter": "assert-add", autocomplete: "off" });
-    if (a.matcher === "toHaveText" || a.matcher === "toContainText" || a.matcher === "toHaveValue") return h("div", { class: "val" }, expected("text"));
+    if (a.matcher === "toHaveText" || a.matcher === "toContainText" || a.matcher === "toHaveValue" || a.matcher === "toHaveClass") return h("div", { class: "val" }, expected("text"));
+    if (a.matcher === "toHaveCSS") {
+      return h("div", { class: "val" },
+        h("input", { type: "text", class: "in code", "data-field": "cssName", value: a.cssName, placeholder: "Property", "data-enter": "assert-add", autocomplete: "off", spellcheck: "false" }),
+        expected("text"));
+    }
     if (a.matcher === "toHaveAttribute") {
       return h("div", { class: "val" },
         h("select", { class: "in", "data-field": "attribute" }, info.attributes.map((at) => {
@@ -56,6 +73,24 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
     ];
   };
 
+  const pagePanel = () => {
+    const p = ui.page;
+    const head = h("div", { class: "h" }, "Page");
+    if (!p.info) return [head, h("div", { class: "msg" }, "…")];
+    if (!p.info.ok) return [head, h("div", { class: "err" }, p.info.error)];
+    return [
+      head,
+      h("div", { class: "opts" }, PAGE_MATCHERS.map(([matcher, label]) =>
+        h("button", { class: p.matcher === matcher ? "o sel" : "o", "data-action": "page-matcher", "data-matcher": matcher }, label))),
+      h("div", { class: "val" },
+        h("input", { type: "text", class: "in", "data-field": "pageExpected", value: p.expected, "data-enter": "page-add", autocomplete: "off", spellcheck: "false" })),
+      p.error && h("div", { class: "err" }, p.error),
+      h("div", { class: "row" },
+        h("label", { class: "neg" }, h("input", { type: "checkbox", "data-action": "page-not", checked: p.not }), "Not"),
+        h("button", { class: "add", "data-action": "page-add", disabled: ui.busy }, "Add")),
+    ];
+  };
+
   const matches = () => {
     const filter = ui.insert.filter.trim().toLowerCase();
     const hit = (item) => !filter || item.name.toLowerCase().indexOf(filter) >= 0;
@@ -146,5 +181,5 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
     radio("fullPage", "true", ui.shot.fullPage, "Whole page"),
     h("div", { class: "foot" }, h("button", { class: "add", "data-action": "screenshot-add", disabled: ui.busy }, "Add")),
   ];
-  const PANELS = { assert: assertPanel, insert: insertPanel, new: newPanel, wait: waitPanel, screenshot: screenshotPanel };
+  const PANELS = { assert: assertPanel, page: pagePanel, insert: insertPanel, new: newPanel, wait: waitPanel, screenshot: screenshotPanel };
 `;

package/dist/recorder/toolbar/source/views-rail.js

@@ -31,6 +31,7 @@ export const VIEWS_RAIL_JS = String.raw `  // ---- Views ----
         : h("button", { class: "b", "data-action": "pause" }, ico("❚❚"), "Pause"),
       tool("assert", "✓", "Assert"),
       ui.picking && h("div", { class: "note" }, "Click an element · Esc cancels"),
+      tool("page", "⌂", "Page"),
       tool("insert", "{x}", "Insert"),
       tool("wait", "⏱", "Wait"),
       tool("screenshot", "◉", "Screenshot"),

package/dist/recorder/toolbar/source.d.ts

@@ -8,19 +8,20 @@
  *
  * `globalThis[Symbol.for("samurai.toolbar")]` in the sandbox holds the hook:
  * - `update(state)`: the recorder's state, after every change and every page load.
- * - `reply(id, result)`: the answer to `pick` (a `PickInfo`) or to `assert`, `insert` and `add-insertable`
- *   (an `ActionReply`).
+ * - `reply(id, result)`: the answer to `pick` (a `PickInfo`), to `page-info` (a `PageInfo`) or to `assert`,
+ *   `assert-page`, `insert` and `add-insertable` (an `ActionReply`).
  * - `root`: the shadow root, for tests.
  * - `press(action, detail?)`: runs the handler a click on that control runs (for tests). Actions:
  *   `pause`, `resume`, `stop`, `collapse`, `expand`, `resume-yes`, `resume-no` (rail);
- *   `assert`, `insert`, `wait`, `screenshot` (open or close the tool);
+ *   `assert`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
  *   `pick { target }` (the element a picking click hit);
  *   `matcher { matcher }`, `not`, `assert-add` (Assert panel);
+ *   `page-matcher { matcher }`, `page-not`, `page-add` (Page panel);
  *   `insert-item { kind, name }`, `insert-first`, `insert-new { kind }` (Insert list);
  *   `new-kind { kind }`, `new-save`, `new-cancel` (New variable or secret);
  *   `wait-add`, `screenshot-add`; `escape` (the Esc key); `dismiss { id }` (a warning's Dismiss button).
- *   Form inputs carry `data-field` (`expected`, `attribute`, `countIndex`, `filter`, `name`, `value`,
- *   `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
+ *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `pageExpected`, `filter`,
+ *   `name`, `value`, `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
  * - `rebind(send)`: used by a second run in the same document (a new recording), which keeps the host and
  *   swaps in that recording's toolbar channel.
  * - `state()`, `picking()`: the last state from `update` and whether the Assert picker is on (for tests).

package/dist/recorder/toolbar/source.js

@@ -23,19 +23,20 @@ import { ATTACH_JS } from "./source/attach.js";
  *
  * `globalThis[Symbol.for("samurai.toolbar")]` in the sandbox holds the hook:
  * - `update(state)`: the recorder's state, after every change and every page load.
- * - `reply(id, result)`: the answer to `pick` (a `PickInfo`) or to `assert`, `insert` and `add-insertable`
- *   (an `ActionReply`).
+ * - `reply(id, result)`: the answer to `pick` (a `PickInfo`), to `page-info` (a `PageInfo`) or to `assert`,
+ *   `assert-page`, `insert` and `add-insertable` (an `ActionReply`).
  * - `root`: the shadow root, for tests.
  * - `press(action, detail?)`: runs the handler a click on that control runs (for tests). Actions:
  *   `pause`, `resume`, `stop`, `collapse`, `expand`, `resume-yes`, `resume-no` (rail);
- *   `assert`, `insert`, `wait`, `screenshot` (open or close the tool);
+ *   `assert`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
  *   `pick { target }` (the element a picking click hit);
  *   `matcher { matcher }`, `not`, `assert-add` (Assert panel);
+ *   `page-matcher { matcher }`, `page-not`, `page-add` (Page panel);
  *   `insert-item { kind, name }`, `insert-first`, `insert-new { kind }` (Insert list);
  *   `new-kind { kind }`, `new-save`, `new-cancel` (New variable or secret);
  *   `wait-add`, `screenshot-add`; `escape` (the Esc key); `dismiss { id }` (a warning's Dismiss button).
- *   Form inputs carry `data-field` (`expected`, `attribute`, `countIndex`, `filter`, `name`, `value`,
- *   `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
+ *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `pageExpected`, `filter`,
+ *   `name`, `value`, `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
  * - `rebind(send)`: used by a second run in the same document (a new recording), which keeps the host and
  *   swaps in that recording's toolbar channel.
  * - `state()`, `picking()`: the last state from `update` and whether the Assert picker is on (for tests).

package/dist/recorder/toolbar/types.d.ts

@@ -1,7 +1,7 @@
 import type { ElementHandle } from "../../script/element-handle.js";
 import type { LocatorCall, LocatorSpec } from "../../steps/model.js";
 import type { Observation } from "../normalise.js";
-import type { ActionReply, PickInfo, ToolbarMessage, ToolbarState } from "./protocol.js";
+import type { ActionReply, PageInfo, PickInfo, ToolbarMessage, ToolbarState } from "./protocol.js";
 /** What `inspect` found for a picked element: the reply, and the locator behind each Count choice */
 export interface Inspection {
     info: PickInfo & {
@@ -14,8 +14,15 @@ export interface Inspection {
 export interface ControllerDeps {
     /** Sends the state to every loaded top-level document's toolbar */
     push(state: ToolbarState): void;
-    reply(id: number, result: PickInfo | ActionReply): void;
+    reply(id: number, result: PickInfo | PageInfo | ActionReply): void;
     currentUrl(): Promise<string>;
+    /** The recorded page's URL and title */
+    pageInfo(): Promise<{
+        url: string;
+        title: string;
+    }>;
+    /** The recording's base URL: the Page panel writes URLs inside it relative to it */
+    readonly baseURL?: string;
     rank(target: ElementHandle, candidates: LocatorCall[]): Promise<LocatorSpec | undefined>;
     inspect(target: ElementHandle, locator: LocatorSpec, candidates: LocatorCall[]): Promise<Inspection>;
     /** Types into the field with capture muted */

package/dist/recorder/toolbar-bridge.d.ts

@@ -10,6 +10,8 @@ export interface BridgeHost {
     page: Page;
     connector: BiDiConnector;
     context: string;
+    /** The recording's base URL: the Page panel writes URLs inside it relative to it */
+    baseURL?: string;
     mute(): Promise<void>;
     unmute(): Promise<void>;
     /** A step the toolbar made (wait, screenshot, insert, assertion) */

package/dist/recorder/toolbar-bridge.js

@@ -65,12 +65,17 @@ export class ToolbarBridge {
         }
     }
     createController(toolbar) {
-        const { page, connector, context } = this.host;
+        const { page, connector, context, baseURL } = this.host;
         const { projectDir, environment, onStatus, onStop, onSecretAdded } = toolbar;
         return new ToolbarController({
             push: (state) => this.call("update", [state]),
             reply: (id, result) => this.call("reply", [id, result]),
             currentUrl: () => page.url(),
+            pageInfo: async () => {
+                const [url, title] = await Promise.all([page.url(), page.title()]);
+                return { url, title };
+            },
+            ...(baseURL !== undefined && { baseURL }),
             rank: (target, candidates) => rankLocator(page, target, candidates),
             inspect: (target, locator, candidates) => inspectElement(page, connector, context, target, locator, candidates),
             type: async (locator, value) => {

package/dist/runner/worker-protocol.d.ts

@@ -11,6 +11,8 @@ export interface WorkItem {
     browser: SupportedBrowser;
     /** Items with the same key never run at the same time */
     serialKey?: string;
+    /** Where this test's screenshots go, instead of the run's `outputDir` (a flow gives each node its own) */
+    outputDir?: string;
 }
 /** What a worker needs to start: the project and the settings that are the same for every test */
 export interface WorkerInit {

package/dist/runner/worker-session.js

@@ -36,7 +36,7 @@ export function openSession(init) {
             });
             resolve({
                 tests: loaded.all,
-                async runTest(test, browser, signal, onEvent) {
+                async runTest(test, browser, signal, onEvent, perTest = {}) {
                     const reporter = new TestReporter({
                         environment: run.settings.environment,
                         browsers: [browser],
@@ -48,8 +48,8 @@ export function openSession(init) {
                         ...(init.reportPath !== undefined && {
                             reportPath: init.reportPath,
                         }),
-                        ...(init.outputDir !== undefined && {
-                            outputDir: init.outputDir,
+                        ...((perTest.outputDir ?? init.outputDir) !== undefined && {
+                            outputDir: perTest.outputDir ?? init.outputDir,
                         }),
                         port,
                         signal,

package/dist/runner/worker.d.ts

@@ -6,7 +6,9 @@ import type { FromWorker, ToWorker, WorkerInit } from "./worker-protocol.js";
 export interface WorkerSession {
     tests: readonly RegisteredTestCase[];
     /** Runs one test; `onEvent` gets the reporter's events for it. Aborting `signal` ends the test as aborted */
-    runTest(test: RegisteredTestCase, browser: SupportedBrowser, signal: AbortSignal, onEvent: (event: RunEvent) => void): Promise<void>;
+    runTest(test: RegisteredTestCase, browser: SupportedBrowser, signal: AbortSignal, onEvent: (event: RunEvent) => void, options?: {
+        outputDir?: string;
+    }): Promise<void>;
     /** Ends the project's session */
     close(): Promise<void>;
 }

package/dist/runner/worker.js

@@ -54,7 +54,7 @@ export function handleMessages(channel, { open, exit }) {
                     id,
                     result: { ...event.result, worker: workerIndex },
                 });
-            });
+            }, item.outputDir !== undefined ? { outputDir: item.outputDir } : {});
         }
         finally {
             current = undefined;

package/dist/steps/emit.js

@@ -61,9 +61,14 @@ function matcherToSource(expected) {
 function expectationToSource(expectation) {
     switch (expectation.matcher) {
         case "toBeVisible":
-            return "toBeVisible()";
+        case "toBeHidden":
+        case "toBeEnabled":
+        case "toBeChecked":
+            return `${expectation.matcher}()`;
         case "toHaveAttribute":
             return `toHaveAttribute(${str(expectation.name)}, ${matcherToSource(expectation.expected)})`;
+        case "toHaveCSS":
+            return `toHaveCSS(${str(expectation.name)}, ${matcherToSource(expectation.expected)})`;
         case "toHaveCount":
             return `toHaveCount(${expectation.expected})`;
         default:
@@ -83,6 +88,8 @@ export function stepToSource(step) {
             return `await ${locatorToSource(step.locator)}.press(${str(step.key)});`;
         case "expect":
             return `await expect(${locatorToSource(step.locator)})${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
+        case "expectPage":
+            return `await expect(page)${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
         case "waitForNetworkIdle":
             return "await page.waitForNetworkIdle();";
         case "waitForTimeout":

package/dist/steps/index.d.ts

@@ -3,4 +3,4 @@ export { applyEdit, type StepEdit } from "./edit.js";
 export { stepToSource, locatorToSource, callToSource, filesToSource, valueToSource, } from "./emit.js";
 export { formatSize, humanSize, parseSize, sizeFromSource } from "./files.js";
 export { locatorFromSpec } from "./build.js";
-export type { Expectation, FileEntry, GeneratedFileSpec, LocatorCall, LocatorSpec, ParsedStep, ParsedTest, Step, TextMatcher, TextValue, UnparsedTest, } from "./model.js";
+export type { Expectation, FileEntry, GeneratedFileSpec, LocatorCall, LocatorSpec, PageExpectation, ParsedStep, ParsedTest, Step, TextMatcher, TextValue, UnparsedTest, } from "./model.js";

package/dist/steps/model.d.ts

@@ -48,7 +48,14 @@ export type TextMatcher = string | {
     };
 };
 export type Expectation = {
-    matcher: "toBeVisible";
+    matcher: "toBeVisible" | "toBeHidden" | "toBeEnabled" | "toBeChecked";
+} | {
+    matcher: "toHaveClass";
+    expected: TextMatcher;
+} | {
+    matcher: "toHaveCSS";
+    name: string;
+    expected: TextMatcher;
 } | {
     matcher: "toHaveText" | "toContainText" | "toHaveValue";
     expected: TextMatcher;
@@ -60,6 +67,11 @@ export type Expectation = {
     matcher: "toHaveCount";
     expected: number;
 };
+/** What an assertion expects of the page itself: its URL or title */
+export interface PageExpectation {
+    matcher: "toHaveURL" | "toHaveTitle";
+    expected: TextMatcher;
+}
 /** A file generated when the step runs: seeded random bytes of `size`, never stored in the project */
 export interface GeneratedFileSpec {
     name: string;
@@ -93,6 +105,12 @@ export type Step = {
     not: boolean;
     expectation: Expectation;
 }
+/** An assertion on the page, `expect(page).toHaveURL(…)` */
+ | {
+    kind: "expectPage";
+    not: boolean;
+    expectation: PageExpectation;
+}
 /** A key pressed while the element has focus, e.g. `Enter` to submit a field. Named as Playwright names keys */
  | {
     kind: "press";

package/dist/steps/parse/expectation.d.ts

@@ -1,5 +1,6 @@
 import ts from "typescript";
-import type { Expectation, TextValue } from "../model.js";
+import type { Expectation, PageExpectation, TextValue } from "../model.js";
 /** `env.NAME`, `env["NAME"]`, `secrets.NAME`, `secrets["NAME"]` or a string literal */
 export declare function readValue(node: ts.Expression | undefined): TextValue | undefined;
 export declare function readExpectation(matcher: string, args: readonly ts.Expression[]): Expectation | undefined;
+export declare function readPageExpectation(matcher: string, args: readonly ts.Expression[]): PageExpectation | undefined;

package/dist/steps/parse/expectation.js

@@ -46,8 +46,24 @@ function readTextMatcher(node) {
     return undefined;
 }
 export function readExpectation(matcher, args) {
-    if (matcher === "toBeVisible")
+    if (matcher === "toBeVisible" ||
+        matcher === "toBeHidden" ||
+        matcher === "toBeEnabled" ||
+        matcher === "toBeChecked")
         return args.length === 0 ? { matcher } : undefined;
+    if (matcher === "toHaveClass") {
+        const expected = readTextMatcher(args[0]);
+        return args.length === 1 && expected !== undefined
+            ? { matcher, expected }
+            : undefined;
+    }
+    if (matcher === "toHaveCSS") {
+        const name = stringOf(args[0]);
+        const expected = readTextMatcher(args[1]);
+        return args.length === 2 && name !== undefined && expected !== undefined
+            ? { matcher, name, expected }
+            : undefined;
+    }
     if (matcher === "toHaveCount") {
         const [count] = args;
         return args.length === 1 && count && ts.isNumericLiteral(count)
@@ -69,3 +85,11 @@ export function readExpectation(matcher, args) {
     }
     return undefined;
 }
+export function readPageExpectation(matcher, args) {
+    if (matcher !== "toHaveURL" && matcher !== "toHaveTitle")
+        return undefined;
+    const expected = readTextMatcher(args[0]);
+    return args.length === 1 && expected !== undefined
+        ? { matcher, expected }
+        : undefined;
+}

package/dist/steps/parse/step.js

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { readLocator } from "./call.js";
-import { readExpectation, readValue } from "./expectation.js";
+import { readExpectation, readPageExpectation, readValue, } from "./expectation.js";
 import { readFiles } from "./file-entry.js";
 import { readObject, stringOf } from "./literals.js";
 /** The step a statement stands for, or undefined when it is outside the recorder's set */
@@ -51,7 +51,14 @@ export function readStep(statement) {
         ts.isIdentifier(subject.expression) &&
         subject.expression.text === "expect" &&
         subject.arguments.length === 1) {
-        const locator = readLocator(subject.arguments[0]);
+        const arg = subject.arguments[0];
+        if (ts.isIdentifier(arg) && arg.text === "page") {
+            const expectation = readPageExpectation(name.text, args);
+            return expectation
+                ? { kind: "expectPage", not: negated, expectation }
+                : undefined;
+        }
+        const locator = readLocator(arg);
         const expectation = readExpectation(name.text, args);
         return locator && expectation
             ? { kind: "expect", locator, not: negated, expectation }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {