@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/steps/parse.js

@@ -0,0 +1,272 @@
+import ts from "typescript";
+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;
+}
+/** 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 };
+        }
+        return name.text === "waitForNetworkIdle" && args.length === 0
+            ? { kind: "waitForNetworkIdle" }
+            : 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 === "fill" && args.length === 1) {
+        const value = readValue(args[0]);
+        return value ? { kind: "fill", locator, value } : undefined;
+    }
+    return undefined;
+}
+function parseStatement(source, statement, sourceFile) {
+    const start = statement.getStart(sourceFile);
+    const end = statement.end;
+    const comments = ts.getLeadingCommentRanges(source, statement.getFullStart());
+    return {
+        step: readStep(statement) ?? {
+            kind: "custom",
+            code: source.slice(start, end),
+        },
+        start,
+        end,
+        anchor: comments?.[0]?.pos ?? start,
+    };
+}
+function callbackBody(node) {
+    return node &&
+        (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+        ts.isBlock(node.body)
+        ? node.body
+        : undefined;
+}
+/** The tests in a spec file, with their steps and where each statement sits */
+export function parseSpec(source) {
+    const sourceFile = ts.createSourceFile("spec.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const tests = [];
+    const visit = (node, titles) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const title = stringOf(node.arguments[0]);
+            const body = callbackBody(node.arguments[1]);
+            if (title !== undefined && body && node.expression.text === "test") {
+                const titlePath = [...titles, title];
+                tests.push({
+                    titlePath,
+                    name: titlePath.join(" > "),
+                    steps: body.statements.map((statement) => parseStatement(source, statement, sourceFile)),
+                    bodyStart: body.getStart(sourceFile) + 1,
+                    bodyEnd: body.end - 1,
+                });
+                return;
+            }
+            if (title !== undefined && body && node.expression.text === "describe") {
+                ts.forEachChild(body, (child) => visit(child, [...titles, title]));
+                return;
+            }
+        }
+        ts.forEachChild(node, (child) => visit(child, titles));
+    };
+    visit(sourceFile, []);
+    return tests;
+}

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

@@ -0,0 +1,46 @@
+import type { BiDiCommands, BiDiEvents } from "../types/bidi.js";
+import { type EventName, type Subscription, type SubscribeOptions } from "./subscriptions.js";
+export interface ConnectorOptions {
+    /** @default 30000 */
+    commandTimeout?: number;
+}
+export interface SendOptions {
+    /** Overrides the connector's commandTimeout for this command */
+    timeout?: number;
+}
+export declare class BiDiConnector {
+    private resolveMap;
+    private currentId;
+    private webSocket;
+    private eventEmitter;
+    private commandTimeout;
+    private subscriptions;
+    constructor(ws: WebSocket, options?: ConnectorOptions);
+    static connect(url: string, options?: ConnectorOptions): Promise<BiDiConnector>;
+    private onWebsocketClose;
+    private onWebsocketError;
+    /** Rejects every pending command; `reason` gets the pending method names for its message */
+    private rejectAll;
+    private getId;
+    send<M extends keyof BiDiCommands>(method: M, params?: BiDiCommands[M]["params"], options?: SendOptions): Promise<BiDiCommands[M]["result"]>;
+    /**
+     * Subscribes to events. Unscoped subscriptions are refcounted per event, so features can
+     * subscribe independently; scoped ones (`contexts`) always send their own command.
+     */
+    subscribe(events: EventName[], options?: SubscribeOptions): Promise<Subscription>;
+    /**
+     * Resolves with the params of the first `event` for which `predicate` is true.
+     * The listener is registered before this returns, so start the triggering command afterwards.
+     * Rejects with WaitTimeoutError after `timeout` ms, or with the abort reason.
+     */
+    waitForEvent<E extends keyof BiDiEvents>(event: E, predicate: (params: BiDiEvents[E]["params"]) => boolean, options: {
+        timeout: number;
+        signal?: AbortSignal;
+    }): Promise<BiDiEvents[E]["params"]>;
+    /** Register an event listener */
+    onEvent<E extends keyof BiDiEvents>(event: E, listener: (params: BiDiEvents[E]["params"]) => void): void;
+    /** Remove an event listener */
+    offEvent<E extends keyof BiDiEvents>(event: E, listener: (params: BiDiEvents[E]["params"]) => void): void;
+    private messageListener;
+    kill(): void;
+}

package/dist/transport/bidi-connection.js

@@ -0,0 +1,176 @@
+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 { SubscriptionManager, } from "./subscriptions.js";
+/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
+const DEFAULT_COMMAND_TIMEOUT = 30000;
+export class BiDiConnector {
+    constructor(ws, options = {}) {
+        this.resolveMap = new Map();
+        this.currentId = 0;
+        this.onWebsocketClose = () => {
+            this.rejectAll((pending) => new Error(`Websocket closed${pendingSuffix(pending)}`));
+        };
+        this.onWebsocketError = (ev) => {
+            this.rejectAll((pending) => Object.assign(new Error(`Websocket error${pendingSuffix(pending)}`), {
+                cause: ev,
+            }));
+        };
+        this.messageListener = (ev) => {
+            const message = JSON.parse(ev.data);
+            logger.debug("Received message from BiDi Websocket: ", message);
+            if (message.type === "success" && message.id !== undefined) {
+                const targetToResolve = this.resolveMap.get(message.id);
+                if (targetToResolve) {
+                    this.resolveMap.delete(message.id);
+                    targetToResolve.resolve(message.result);
+                }
+            }
+            else if (message.type === "error") {
+                const target = message.id === null || message.id === undefined
+                    ? undefined
+                    : this.resolveMap.get(message.id);
+                if (!target) {
+                    logger.debug("BiDi error reply without a pending command", message);
+                    return;
+                }
+                this.resolveMap.delete(message.id);
+                target.reject(new BiDiError(target.method, message.error, message.message, message.stacktrace));
+            }
+            else if (message.type === "event") {
+                this.eventEmitter.emit(message.method, message.params);
+            }
+        };
+        this.commandTimeout = options.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT;
+        this.subscriptions = new SubscriptionManager({
+            subscribe: (params) => this.send("session.subscribe", params),
+            unsubscribe: (params) => this.send("session.unsubscribe", params),
+        });
+        this.webSocket = ws;
+        this.webSocket.addEventListener("message", this.messageListener);
+        this.webSocket.addEventListener("close", this.onWebsocketClose);
+        this.webSocket.addEventListener("error", this.onWebsocketError);
+        this.eventEmitter = new EventEmitter();
+        logger.debug("BiDiConnector: Websocket handshake finished");
+    }
+    static async connect(url, options) {
+        logger.debug("Connecting to WebSocket");
+        const ws = new WebSocket(url);
+        return new Promise((resolve, reject) => {
+            logger.debug("Waiting for WebSocket handshake");
+            ws.addEventListener("open", () => {
+                logger.debug("WebSocket handshake finished");
+                resolve(new BiDiConnector(ws, options));
+            });
+            ws.addEventListener("error", (err) => {
+                logger.debug("WebSocket error", { err });
+                reject(new Error("WebSocket connection failed"));
+            });
+        });
+    }
+    /** Rejects every pending command; `reason` gets the pending method names for its message */
+    rejectAll(reason) {
+        const entries = [...this.resolveMap.values()];
+        const error = reason(entries.map((entry) => entry.method));
+        this.resolveMap.clear();
+        entries.forEach(({ reject }) => reject(error));
+    }
+    getId() {
+        return this.currentId++;
+    }
+    send(method, params, options = {}) {
+        return new Promise((resolve, reject) => {
+            try {
+                const id = this.getId();
+                const timeout = options.timeout ?? this.commandTimeout;
+                const timer = setTimeout(() => {
+                    this.resolveMap.delete(id);
+                    reject(new BiDiError(method, "timeout", `no reply within ${timeout}ms`));
+                }, timeout);
+                this.resolveMap.set(id, {
+                    method,
+                    resolve: (value) => {
+                        clearTimeout(timer);
+                        resolve(value);
+                    },
+                    reject: (reason) => {
+                        clearTimeout(timer);
+                        reject(reason);
+                    },
+                });
+                const commandBody = {
+                    id,
+                    method,
+                    params,
+                };
+                logger.debug("Sending message to BiDi Websocket", commandBody);
+                this.webSocket.send(JSON.stringify(commandBody));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Subscribes to events. Unscoped subscriptions are refcounted per event, so features can
+     * subscribe independently; scoped ones (`contexts`) always send their own command.
+     */
+    subscribe(events, options) {
+        return this.subscriptions.subscribe(events, options);
+    }
+    /**
+     * Resolves with the params of the first `event` for which `predicate` is true.
+     * The listener is registered before this returns, so start the triggering command afterwards.
+     * Rejects with WaitTimeoutError after `timeout` ms, or with the abort reason.
+     */
+    waitForEvent(event, predicate, options) {
+        const { timeout, signal } = options;
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.offEvent(event, listener);
+                signal?.removeEventListener("abort", onAbort);
+            };
+            const listener = (params) => {
+                if (!predicate(params))
+                    return;
+                cleanup();
+                resolve(params);
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(signal?.reason);
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new WaitTimeoutError(timeout, undefined));
+            }, timeout);
+            this.onEvent(event, listener);
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /** Register an event listener */
+    onEvent(event, listener) {
+        this.eventEmitter.on(event, listener);
+    }
+    /** Remove an event listener */
+    offEvent(event, listener) {
+        this.eventEmitter.off(event, listener);
+    }
+    kill() {
+        this.webSocket.removeEventListener("message", this.messageListener);
+        this.webSocket.removeEventListener("close", this.onWebsocketClose);
+        this.webSocket.removeEventListener("error", this.onWebsocketError);
+        this.rejectAll((pending) => new Error(`BiDiConnector killed${pendingSuffix(pending)}`));
+        this.eventEmitter.removeAllListeners();
+        this.webSocket.close();
+    }
+}
+function pendingSuffix(pending) {
+    return pending.length > 0 ? ` (pending: ${pending.join(", ")})` : "";
+}

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

@@ -0,0 +1,10 @@
+import type { ErrorCode } from "../types/bidi-protocols/error.js";
+/** A failed BiDi command: an error reply from the browser, or `"timeout"` when none came in time */
+export declare class BiDiError extends Error {
+    /** BiDi error code such as "no such node", or "timeout" */
+    readonly code: ErrorCode | "timeout";
+    /** The command that failed, e.g. "script.callFunction" */
+    readonly command: string;
+    readonly remoteStack?: string | undefined;
+    constructor(command: string, code: ErrorCode | "timeout", message: string, remoteStack?: string);
+}

package/dist/transport/bidi-error.js

@@ -0,0 +1,10 @@
+/** A failed BiDi command: an error reply from the browser, or `"timeout"` when none came in time */
+export class BiDiError extends Error {
+    constructor(command, code, message, remoteStack) {
+        super(`${command} failed (${code}): ${message}`);
+        this.name = "BiDiError";
+        this.command = command;
+        this.code = code;
+        this.remoteStack = remoteStack;
+    }
+}

package/dist/transport/subscriptions.d.ts

@@ -0,0 +1,36 @@
+import type { BiDiEvents } from "../types/bidi.js";
+export type EventName = keyof BiDiEvents;
+export interface Subscription {
+    /** Idempotent */
+    unsubscribe(): Promise<void>;
+}
+export interface SubscribeOptions {
+    /** Scope to these browsing contexts. Scoped subscriptions are never shared */
+    contexts?: string[];
+}
+/** Sends the two session commands; the connector provides it */
+export interface SessionCommands {
+    subscribe(params: {
+        events: string[];
+        contexts?: string[];
+    }): Promise<{
+        subscription: string;
+    }>;
+    unsubscribe(params: {
+        subscriptions: string[];
+    }): Promise<unknown>;
+}
+/**
+ * Global (unscoped) subscriptions are refcounted per event name: the first subscriber sends
+ * `session.subscribe`, the last one leaving sends `session.unsubscribe`.
+ */
+export declare class SubscriptionManager {
+    private commands;
+    private shared;
+    constructor(commands: SessionCommands);
+    subscribe(events: EventName[], options?: SubscribeOptions): Promise<Subscription>;
+    private subscribeScoped;
+    private state;
+    private acquire;
+    private release;
+}

package/dist/transport/subscriptions.js

@@ -0,0 +1,81 @@
+/**
+ * Global (unscoped) subscriptions are refcounted per event name: the first subscriber sends
+ * `session.subscribe`, the last one leaving sends `session.unsubscribe`.
+ */
+export class SubscriptionManager {
+    constructor(commands) {
+        this.commands = commands;
+        this.shared = new Map();
+    }
+    async subscribe(events, options = {}) {
+        if (options.contexts)
+            return this.subscribeScoped(events, options.contexts);
+        const acquired = [];
+        try {
+            for (const event of events) {
+                await this.acquire(event);
+                acquired.push(event);
+            }
+        }
+        catch (err) {
+            await Promise.allSettled(acquired.map((event) => this.release(event)));
+            throw err;
+        }
+        let released = false;
+        return {
+            unsubscribe: async () => {
+                if (released)
+                    return;
+                released = true;
+                await Promise.all(acquired.map((event) => this.release(event)));
+            },
+        };
+    }
+    async subscribeScoped(events, contexts) {
+        const { subscription } = await this.commands.subscribe({ events, contexts });
+        let released = false;
+        return {
+            unsubscribe: async () => {
+                if (released)
+                    return;
+                released = true;
+                await this.commands.unsubscribe({ subscriptions: [subscription] });
+            },
+        };
+    }
+    state(event) {
+        let state = this.shared.get(event);
+        if (!state) {
+            state = { count: 0, id: undefined, chain: Promise.resolve() };
+            this.shared.set(event, state);
+        }
+        return state;
+    }
+    acquire(event) {
+        const state = this.state(event);
+        state.count++;
+        const step = state.chain.then(async () => {
+            if (state.count > 0 && state.id === undefined) {
+                state.id = (await this.commands.subscribe({ events: [event] })).subscription;
+            }
+        });
+        state.chain = step.catch(() => { });
+        return step.catch((err) => {
+            state.count--;
+            throw err;
+        });
+    }
+    release(event) {
+        const state = this.state(event);
+        state.count--;
+        const step = state.chain.then(async () => {
+            if (state.count === 0 && state.id !== undefined) {
+                const id = state.id;
+                state.id = undefined;
+                await this.commands.unsubscribe({ subscriptions: [id] });
+            }
+        });
+        state.chain = step.catch(() => { });
+        return step;
+    }
+}

package/{src → dist}/types/test.d.ts

@@ -33,7 +33,7 @@ export interface PartialTestResult extends TestResultBase {
 
 export type TestResult = TestResultSuccess | TestResultFailed | TestResultBase;
 
-interface TestResultSuccess {
+interface TestResultSuccess extends TestResultIdentity {
   status: "success";
   duration: number;
   logs?: TestLogEntry[];
@@ -41,9 +41,9 @@ interface TestResultSuccess {
   logsDropped?: number;
 }
 
-interface TestResultFailed {
+/** The error sits flat on the entry, as in the report: `message`, `type`, `stack`, and for assertions `expected` and `actual` */
+interface TestResultFailed extends TestResultIdentity, TestError {
   status: "failed";
-  error: TestError;
   duration: number;
   logs?: TestLogEntry[];
   logsDropped?: number;
@@ -59,6 +59,12 @@ export interface TestLogEntry {
   timestamp: number;
 }
 
+interface TestResultIdentity {
+  name: string;
+  file: string;
+  startTime: number;
+}
+
 interface TestResultBase {
   name: string;
   file: string;
@@ -66,7 +72,7 @@ interface TestResultBase {
   status: "started";
 }
 
-interface TestError {
+export interface TestError {
   message: string;
   type: "timeout" | "error" | "assertion";
   stack?: string | undefined;