@itmetsam/samurai-framework 0.9.0 → 0.12.0

package/dist/steps/parse.js

@@ -1,327 +1,6 @@
 import ts from "typescript";
-import { parseSize } from "./files.js";
-const TEXT_MATCHERS = ["toHaveText", "toContainText", "toHaveValue"];
-function stringOf(node) {
-    return node &&
-        (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
-        ? node.text
-        : undefined;
-}
-/** `{ key: literal, … }` with only the allowed keys, or undefined when it has anything else */
-function readObject(node, allowed) {
-    if (!node || !ts.isObjectLiteralExpression(node))
-        return undefined;
-    const result = {};
-    for (const property of node.properties) {
-        if (!ts.isPropertyAssignment(property) ||
-            !allowed.includes(property.name.getText()))
-            return undefined;
-        const value = stringOf(property.initializer);
-        if (value !== undefined)
-            result[property.name.getText()] = value;
-        else if (property.initializer.kind === ts.SyntaxKind.TrueKeyword)
-            result[property.name.getText()] = true;
-        else if (property.initializer.kind === ts.SyntaxKind.FalseKeyword)
-            result[property.name.getText()] = false;
-        else
-            return undefined;
-    }
-    return result;
-}
-function readCall(method, args) {
-    const first = stringOf(args[0]);
-    if (first === undefined)
-        return undefined;
-    switch (method) {
-        case "locator":
-            return args.length === 1 ? { method, xpath: first } : undefined;
-        case "getByCss":
-            return args.length === 1 ? { method, css: first } : undefined;
-        case "getByTestId":
-            return args.length === 1 ? { method, testId: first } : undefined;
-        case "getByText":
-        case "getByLabel": {
-            if (args.length > 2)
-                return undefined;
-            const options = args.length === 2 ? readObject(args[1], ["match", "ignoreCase"]) : {};
-            if (!options)
-                return undefined;
-            const { match, ignoreCase } = options;
-            if ((match !== undefined && match !== "full" && match !== "partial") ||
-                (ignoreCase !== undefined && typeof ignoreCase !== "boolean")) {
-                return undefined;
-            }
-            return {
-                method,
-                text: first,
-                ...(match !== undefined && { match: match }),
-                ...(ignoreCase !== undefined && { ignoreCase: ignoreCase }),
-            };
-        }
-        case "getByRole": {
-            if (args.length > 2)
-                return undefined;
-            const options = args.length === 2 ? readObject(args[1], ["name"]) : {};
-            if (!options ||
-                (options.name !== undefined && typeof options.name !== "string"))
-                return undefined;
-            return {
-                method,
-                role: first,
-                ...(options.name !== undefined && { name: options.name }),
-            };
-        }
-        default:
-            return undefined;
-    }
-}
-/** `page.a(…).b(…)` as calls in order; undefined when it is anything else */
-function readChain(node) {
-    const calls = [];
-    let current = node;
-    while (ts.isCallExpression(current)) {
-        if (!ts.isPropertyAccessExpression(current.expression))
-            return undefined;
-        const call = readCall(current.expression.name.text, current.arguments);
-        if (!call)
-            return undefined;
-        calls.unshift(call);
-        current = current.expression.expression;
-    }
-    return ts.isIdentifier(current) && current.text === "page" && calls.length > 0
-        ? calls
-        : undefined;
-}
-function readLocator(node) {
-    if (ts.isCallExpression(node) &&
-        ts.isPropertyAccessExpression(node.expression) &&
-        node.expression.name.text === "withFallbacks") {
-        const chain = readChain(node.expression.expression);
-        const fallbacks = node.arguments.map(readChain);
-        if (!chain ||
-            node.arguments.length === 0 ||
-            fallbacks.some((fallback) => !fallback))
-            return undefined;
-        return { chain, fallbacks: fallbacks };
-    }
-    const chain = readChain(node);
-    return chain && { chain, fallbacks: [] };
-}
-/** `env.NAME`, `env["NAME"]`, `secrets.NAME`, `secrets["NAME"]` or a string literal */
-function readValue(node) {
-    if (!node)
-        return undefined;
-    const literal = stringOf(node);
-    if (literal !== undefined)
-        return { kind: "literal", value: literal };
-    let object;
-    let name;
-    if (ts.isPropertyAccessExpression(node)) {
-        object = node.expression;
-        name = node.name.text;
-    }
-    else if (ts.isElementAccessExpression(node)) {
-        object = node.expression;
-        name = stringOf(node.argumentExpression);
-    }
-    else
-        return undefined;
-    if (name === undefined || !ts.isIdentifier(object))
-        return undefined;
-    if (object.text === "env")
-        return { kind: "env", name };
-    if (object.text === "secrets")
-        return { kind: "secret", name };
-    return undefined;
-}
-function readTextMatcher(node) {
-    if (!node)
-        return undefined;
-    const literal = stringOf(node);
-    if (literal !== undefined)
-        return literal;
-    if (ts.isRegularExpressionLiteral(node)) {
-        const end = node.text.lastIndexOf("/");
-        return {
-            regex: {
-                source: node.text.slice(1, end),
-                flags: node.text.slice(end + 1),
-            },
-        };
-    }
-    return undefined;
-}
-function readExpectation(matcher, args) {
-    if (matcher === "toBeVisible")
-        return args.length === 0 ? { matcher } : undefined;
-    if (matcher === "toHaveCount") {
-        const [count] = args;
-        return args.length === 1 && count && ts.isNumericLiteral(count)
-            ? { matcher, expected: Number(count.text) }
-            : undefined;
-    }
-    if (matcher === "toHaveAttribute") {
-        const name = stringOf(args[0]);
-        const expected = readTextMatcher(args[1]);
-        return args.length === 2 && name !== undefined && expected !== undefined
-            ? { matcher, name, expected }
-            : undefined;
-    }
-    if (TEXT_MATCHERS.includes(matcher)) {
-        const expected = readTextMatcher(args[0]);
-        return args.length === 1 && expected !== undefined
-            ? { matcher: matcher, expected }
-            : undefined;
-    }
-    return undefined;
-}
-/** `"path"` or `generatedFile({ name, size, type? })`; undefined for anything else */
-function readFileEntry(node) {
-    const path = stringOf(node);
-    if (path !== undefined)
-        return { path };
-    if (!ts.isCallExpression(node) ||
-        !ts.isIdentifier(node.expression) ||
-        node.expression.text !== "generatedFile" ||
-        node.arguments.length !== 1 ||
-        !ts.isObjectLiteralExpression(node.arguments[0]))
-        return undefined;
-    let name;
-    let type;
-    let size;
-    let sizeSource;
-    for (const property of node.arguments[0].properties) {
-        if (!ts.isPropertyAssignment(property))
-            return undefined;
-        const value = property.initializer;
-        switch (property.name.getText()) {
-            case "name":
-                name = stringOf(value);
-                if (name === undefined)
-                    return undefined;
-                break;
-            case "type":
-                type = stringOf(value);
-                if (type === undefined)
-                    return undefined;
-                break;
-            case "size": {
-                const text = stringOf(value);
-                size =
-                    text !== undefined
-                        ? parseSize(text)
-                        : ts.isNumericLiteral(value)
-                            ? parseSize(Number(value.text))
-                            : undefined;
-                if (size === undefined)
-                    return undefined;
-                sizeSource = value.getText();
-                break;
-            }
-            default:
-                return undefined;
-        }
-    }
-    if (name === undefined || size === undefined)
-        return undefined;
-    return {
-        generate: {
-            name,
-            size,
-            ...(type !== undefined && { type }),
-            ...(sizeSource !== undefined && { sizeSource }),
-        },
-    };
-}
-/** One file entry, or an array of them */
-function readFiles(node) {
-    if (!node)
-        return undefined;
-    if (ts.isArrayLiteralExpression(node)) {
-        const entries = node.elements.map(readFileEntry);
-        return entries.every((entry) => entry !== undefined)
-            ? entries
-            : undefined;
-    }
-    const entry = readFileEntry(node);
-    return entry && [entry];
-}
-/** The step a statement stands for, or undefined when it is outside the recorder's set */
-function readStep(statement) {
-    if (!ts.isExpressionStatement(statement) ||
-        !ts.isAwaitExpression(statement.expression))
-        return undefined;
-    const call = statement.expression.expression;
-    if (!ts.isCallExpression(call) ||
-        !ts.isPropertyAccessExpression(call.expression))
-        return undefined;
-    const { expression: target, name } = call.expression;
-    const args = call.arguments;
-    if (ts.isIdentifier(target) && target.text === "page") {
-        if (name.text === "goto" && args.length === 1) {
-            const url = stringOf(args[0]);
-            return url === undefined ? undefined : { kind: "goto", url };
-        }
-        if (name.text === "waitForNetworkIdle" && args.length === 0)
-            return { kind: "waitForNetworkIdle" };
-        if (name.text === "waitForTimeout" &&
-            args.length === 1 &&
-            ts.isNumericLiteral(args[0])) {
-            const ms = Number(args[0].text);
-            return Number.isInteger(ms) ? { kind: "waitForTimeout", ms } : undefined;
-        }
-        if (name.text === "screenshot" && args.length === 1) {
-            const options = readObject(args[0], ["name", "fullPage"]);
-            if (!options || typeof options.name !== "string")
-                return undefined;
-            if (options.fullPage !== undefined &&
-                typeof options.fullPage !== "boolean")
-                return undefined;
-            return {
-                kind: "screenshot",
-                name: options.name,
-                fullPage: options.fullPage === true,
-            };
-        }
-        return undefined;
-    }
-    // expect(locator).matcher(…) and expect(locator).not.matcher(…)
-    const negated = ts.isPropertyAccessExpression(target) && target.name.text === "not";
-    const subject = negated
-        ? target.expression
-        : target;
-    if (ts.isCallExpression(subject) &&
-        ts.isIdentifier(subject.expression) &&
-        subject.expression.text === "expect" &&
-        subject.arguments.length === 1) {
-        const locator = readLocator(subject.arguments[0]);
-        const expectation = readExpectation(name.text, args);
-        return locator && expectation
-            ? { kind: "expect", locator, not: negated, expectation }
-            : undefined;
-    }
-    const locator = readLocator(target);
-    if (!locator)
-        return undefined;
-    if (name.text === "click" && args.length === 0)
-        return { kind: "click", locator };
-    if (name.text === "press" && args.length === 1) {
-        const key = stringOf(args[0]);
-        return key === undefined ? undefined : { kind: "press", locator, key };
-    }
-    if (name.text === "fill" && args.length === 1) {
-        const value = readValue(args[0]);
-        return value ? { kind: "fill", locator, value } : undefined;
-    }
-    if ((name.text === "setInputFiles" || name.text === "dropFiles") &&
-        args.length === 1) {
-        const files = readFiles(args[0]);
-        return files
-            ? { kind: name.text, locator, files }
-            : undefined;
-    }
-    return undefined;
-}
+import { stringOf } from "./parse/literals.js";
+import { readStep } from "./parse/step.js";
 function parseStatement(source, statement, sourceFile) {
     const start = statement.getStart(sourceFile);
     const end = statement.end;

package/dist/transport/bidi-connection.d.ts

@@ -3,7 +3,7 @@ import { type EventName, type Subscription, type SubscribeOptions } from "./subs
 /** Time (ms) a command may wait for its reply before it fails with code "timeout" */
 export declare const DEFAULT_COMMAND_TIMEOUT = 30000;
 export interface ConnectorOptions {
-    /** @default 30000 */
+    /** @default DEFAULT_COMMAND_TIMEOUT */
     commandTimeout?: number;
 }
 export interface SendOptions {
@@ -28,6 +28,7 @@ export declare class BiDiConnector {
     /** Which browser is on the other end, when the launcher says; code that must treat browsers apart asks this */
     browserName?: "firefox" | "chrome";
     private webSocket;
+    private closeListeners;
     private eventEmitter;
     private commandTimeout;
     private subscriptions;
@@ -35,10 +36,11 @@ export declare class BiDiConnector {
     static connect(url: string, options?: ConnectorOptions): Promise<BiDiConnector>;
     /** Calls `listener` once when the socket closes or fails (not when `kill()` ends it) */
     onClosed(listener: () => void): void;
-    private closeListeners;
     private notifyClosed;
     private onWebsocketClose;
     private onWebsocketError;
+    /** The socket is gone: tell the listeners and fail what is waiting for an answer */
+    private lose;
     private get isClosed();
     /** Rejects every pending command; `reason` gets the pending method names for its message */
     private rejectAll;

package/dist/transport/bidi-connection.js

@@ -2,6 +2,7 @@ import EventEmitter from "node:events";
 import logger from "../logger/index.js";
 import { WaitTimeoutError } from "../wait/wait-until.js";
 import { BiDiError } from "./bidi-error.js";
+import { forLog } from "./log-redaction.js";
 import { SubscriptionManager, } from "./subscriptions.js";
 /** Time (ms) a command may wait for its reply before it fails with code "timeout" */
 export const DEFAULT_COMMAND_TIMEOUT = 30000;
@@ -23,18 +24,8 @@ export class BiDiConnector {
         /** Set once the socket closed or failed: nothing sent after that gets an answer */
         this.closed = false;
         this.closeListeners = new Set();
-        this.onWebsocketClose = () => {
-            this.closed = true;
-            this.notifyClosed();
-            this.rejectAll((pending) => new ConnectionClosedError(`Websocket closed${pendingSuffix(pending)}`));
-        };
-        this.onWebsocketError = (ev) => {
-            this.closed = true;
-            this.notifyClosed();
-            this.rejectAll((pending) => new ConnectionClosedError(`Websocket error${pendingSuffix(pending)}`, {
-                cause: ev,
-            }));
-        };
+        this.onWebsocketClose = () => this.lose("Websocket closed");
+        this.onWebsocketError = (ev) => this.lose("Websocket error", ev);
         this.messageListener = (ev) => {
             const message = JSON.parse(ev.data);
             logger.debug("Received message from BiDi Websocket: ", forLog(message));
@@ -97,6 +88,12 @@ export class BiDiConnector {
         for (const listener of listeners)
             listener();
     }
+    /** The socket is gone: tell the listeners and fail what is waiting for an answer */
+    lose(what, cause) {
+        this.closed = true;
+        this.notifyClosed();
+        this.rejectAll((pending) => new ConnectionClosedError(`${what}${pendingSuffix(pending)}`, cause === undefined ? undefined : { cause }));
+    }
     get isClosed() {
         // A socket that is closing or closed (readyState 2 or 3) has already lost the browser
         const state = this.webSocket.readyState;
@@ -209,37 +206,6 @@ export class BiDiConnector {
         this.webSocket.close();
     }
 }
-/** Channels whose messages carry what the tester typed (the recorder's) or adds as a secret (its toolbar's) */
-const PRIVATE_CHANNEL = /^samurai-(recorder|toolbar)-/;
-/**
- * The message as the debug log gets it: a `script.message` on a private channel is logged by channel and
- * action only, so a value the tester types or a secret added from the recorder toolbar never reaches the log
- * (an added secret is only registered for masking after it is saved).
- */
-function forLog(message) {
-    const channel = message.params?.channel;
-    if (message.type !== "event" ||
-        message.method !== "script.message" ||
-        typeof channel !== "string" ||
-        !PRIVATE_CHANNEL.test(channel))
-        return message;
-    const entries = message.params?.data
-        ?.value;
-    const field = (key) => {
-        if (!Array.isArray(entries))
-            return undefined;
-        const entry = entries.find((pair) => Array.isArray(pair) && pair[0] === key);
-        const value = entry?.[1]?.value;
-        return typeof value === "string" ? value : undefined;
-    };
-    return {
-        ...message,
-        params: {
-            ...message.params,
-            data: { type: field("type"), action: field("action"), redacted: true },
-        },
-    };
-}
 function pendingSuffix(pending) {
     return pending.length > 0 ? ` (pending: ${pending.join(", ")})` : "";
 }

package/dist/transport/log-redaction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The message as the debug log gets it: a `script.message` on a private channel is logged by channel and
+ * action only, so a value the tester types or a secret added from the recorder toolbar never reaches the log
+ * (an added secret is only registered for masking after it is saved).
+ */
+export declare function forLog(message: {
+    type?: string;
+    method?: string;
+    params?: {
+        channel?: unknown;
+        data?: unknown;
+    };
+}): unknown;

package/dist/transport/log-redaction.js

@@ -0,0 +1,51 @@
+/** Channels whose messages carry what the tester typed (the recorder's) or adds as a secret (its toolbar's) */
+const PRIVATE_CHANNEL = /^samurai-(recorder|toolbar)-/;
+/**
+ * The message as the debug log gets it: a `script.message` on a private channel is logged by channel and
+ * action only, so a value the tester types or a secret added from the recorder toolbar never reaches the log
+ * (an added secret is only registered for masking after it is saved).
+ */
+export function forLog(message) {
+    return shortened(redacted(message));
+}
+/** A string longer than this is cut in the log: a file's bytes travel in 1 MB chunks, 50 MB makes 70 MB of debug log */
+const LOG_STRING_LIMIT = 1000;
+/** A copy of `value` with every long string cut to its start and its length; short values come back as they are */
+function shortened(value, depth = 0) {
+    if (typeof value === "string")
+        return value.length > LOG_STRING_LIMIT
+            ? `${value.slice(0, 200)}… (${value.length} characters)`
+            : value;
+    if (value === null || typeof value !== "object" || depth > 30)
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => shortened(item, depth + 1));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        shortened(item, depth + 1),
+    ]));
+}
+function redacted(message) {
+    const channel = message.params?.channel;
+    if (message.type !== "event" ||
+        message.method !== "script.message" ||
+        typeof channel !== "string" ||
+        !PRIVATE_CHANNEL.test(channel))
+        return message;
+    const entries = message.params?.data
+        ?.value;
+    const field = (key) => {
+        if (!Array.isArray(entries))
+            return undefined;
+        const entry = entries.find((pair) => Array.isArray(pair) && pair[0] === key);
+        const value = entry?.[1]?.value;
+        return typeof value === "string" ? value : undefined;
+    };
+    return {
+        ...message,
+        params: {
+            ...message.params,
+            data: { type: field("type"), action: field("action"), redacted: true },
+        },
+    };
+}

package/dist/transport/subscriptions.js

@@ -21,26 +21,21 @@ export class SubscriptionManager {
             await Promise.allSettled(acquired.map((event) => this.release(event)));
             throw err;
         }
-        let released = false;
         return {
-            unsubscribe: async () => {
-                if (released)
-                    return;
-                released = true;
+            unsubscribe: once(async () => {
                 await Promise.all(acquired.map((event) => this.release(event)));
-            },
+            }),
         };
     }
     async subscribeScoped(events, contexts) {
-        const { subscription } = await this.commands.subscribe({ events, contexts });
-        let released = false;
+        const { subscription } = await this.commands.subscribe({
+            events,
+            contexts,
+        });
         return {
-            unsubscribe: async () => {
-                if (released)
-                    return;
-                released = true;
+            unsubscribe: once(async () => {
                 await this.commands.unsubscribe({ subscriptions: [subscription] });
-            },
+            }),
         };
     }
     state(event) {
@@ -79,3 +74,13 @@ export class SubscriptionManager {
         return step;
     }
 }
+/** `fn` runs on the first call only; later calls resolve at once */
+function once(fn) {
+    let called = false;
+    return async () => {
+        if (called)
+            return;
+        called = true;
+        await fn();
+    };
+}

package/dist/transport/unsupported.d.ts

@@ -0,0 +1,7 @@
+import { BiDiError } from "./bidi-error.js";
+/** The browser does not implement a command, a locator type or an option */
+export declare class UnsupportedOperationError extends Error {
+    constructor(message: string);
+}
+/** Whether the browser answered that it does not know the command: Firefox says "unknown command", others "unsupported operation" */
+export declare function isUnsupported(err: unknown): err is BiDiError;

package/dist/transport/unsupported.js

@@ -0,0 +1,13 @@
+import { BiDiError } from "./bidi-error.js";
+/** The browser does not implement a command, a locator type or an option */
+export class UnsupportedOperationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedOperationError";
+    }
+}
+/** Whether the browser answered that it does not know the command: Firefox says "unknown command", others "unsupported operation" */
+export function isUnsupported(err) {
+    return (err instanceof BiDiError &&
+        (err.code === "unknown command" || err.code === "unsupported operation"));
+}

package/dist/types/bidi-modules/browser.d.ts

@@ -44,18 +44,7 @@ export interface BrowserCommands {
 
 /** How downloads are handled. */
 export type DownloadBehavior =
-  | { type: "allowed"; destinationFolder: string }
-  | { type: "denied" };
-
-/** Union of all possible result types returned by browser module commands. */
-export type BrowserResult =
-  | CloseResult
-  | CreateUserContextResult
-  | GetClientWindowsResult
-  | GetUserContextsResult
-  | RemoveUserContextResult
-  | SetClientWindowStateResult
-  | SetDownloadBehaviorResult;
+  { type: "allowed"; destinationFolder: string } | { type: "denied" };
 
 /** Result of `browser.close`. */
 export type CloseResult = EmptyResult;

package/dist/types/bidi-modules/browsing-context.d.ts

@@ -55,7 +55,11 @@ export interface BrowsingContextModule {
   };
   /** Accepts or dismisses the open user prompt. */
   "browsingContext.handleUserPrompt": {
-    params: { context: BrowsingContext; accept?: boolean | undefined; userText?: string | undefined };
+    params: {
+      context: BrowsingContext;
+      accept?: boolean | undefined;
+      userText?: string | undefined;
+    };
     result: {};
   };
   /** Sets or resets (null) the viewport size and device pixel ratio. */
@@ -92,7 +96,9 @@ export interface BrowsingContextModule {
     params: {
       context: BrowsingContext;
       background?: boolean | undefined;
-      margin?: { top?: number; bottom?: number; left?: number; right?: number } | undefined;
+      margin?:
+        | { top?: number; bottom?: number; left?: number; right?: number }
+        | undefined;
       orientation?: "portrait" | "landscape" | undefined;
       page?: { width?: number; height?: number } | undefined;
       pageRanges?: (number | string)[] | undefined;
@@ -360,22 +366,6 @@ export type BrowsingContextEvent =
   | UserPromptClosed
   | UserPromptOpened;
 
-/** Union of all possible result types returned by browsingContext module commands. */
-export type BrowsingContextResult =
-  | ActivateResult
-  | CaptureScreenshotResult
-  | CloseResult
-  | CreateResult
-  | GetTreeResult
-  | HandleUserPromptResult
-  | LocateNodesResult
-  | NavigateResult
-  | PrintResult
-  | ReloadResult
-  | SetBypassCSPResult
-  | SetViewportResult
-  | TraverseHistoryResult;
-
 /** Result of `browsingContext.activate`. */
 export type ActivateResult = EmptyResult;