@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/runner/test-runner.js

@@ -0,0 +1,205 @@
+import assert from "assert";
+import { glob } from "node:fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+import { Browser } from "../browser/browser.js";
+import { projectDir, readConfig } from "../config/config.js";
+import logger from "../logger/index.js";
+import { assertModuleProject } from "./module-type.js";
+import { clearRegistry, registeredTests } from "./registry.js";
+import { createEnvFixture } from "../config/variables.js";
+import { createSecretsFixture } from "../config/secrets.js";
+import TestReporter, {} from "./reporter.js";
+import Page from "../browser/page.js";
+import { takePendingAssertions } from "../assert/expect.js";
+import { toTestError } from "./test-error.js";
+import { judgePageLogs } from "./page-logs-report.js";
+/** Whether a test with this full name is selected by the options */
+export function isSelected(name, { grep, testNames }) {
+    if (testNames && !testNames.includes(name))
+        return false;
+    if (grep === undefined)
+        return true;
+    if (typeof grep === "string")
+        return name.includes(grep);
+    grep.lastIndex = 0;
+    return grep.test(name);
+}
+export default class TestRunner {
+    constructor(testFiles, run, group, options = {}) {
+        this.testFiles = testFiles;
+        this.run = run;
+        this.group = group;
+        this.options = options;
+    }
+    static async init(run, group, options = {}) {
+        logger.verbose("Initializing test runner");
+        let srcDir = "";
+        if (group && group.src) {
+            srcDir = group.src;
+        }
+        else {
+            srcDir = (await readConfig("srcDir")) ?? "./src";
+        }
+        assert(srcDir, "No srcDir declared!");
+        const cwd = path.resolve(projectDir(), srcDir);
+        if (options.files) {
+            return new TestRunner(options.files.map((file) => path.resolve(projectDir(), file)), run, group, options);
+        }
+        logger.verbose("Reading test files from: %s", cwd);
+        const testFiles = [];
+        for await (const entry of glob("**/*.spec.ts", {
+            cwd,
+        })) {
+            testFiles.push(entry);
+        }
+        logger.debug("Found %d tests in srcDir", testFiles.length);
+        return new TestRunner(testFiles.map((file) => path.join(cwd, file)), run, group, options);
+    }
+    /** Runs the selected tests and returns the summary that was also written to the report */
+    /**
+     * Imports the spec files and returns the tests the options select. A fresh registry and a fresh import of each
+     * file, so a second run in this process registers its tests again (and sees edited specs, for files loaded as
+     * ES modules; CommonJS files stay cached until the process ends)
+     */
+    async register() {
+        clearRegistry();
+        const stamp = `?run=${Date.now().toString(36)}`;
+        for (const file of this.testFiles)
+            assertModuleProject(file);
+        for (const file of this.testFiles) {
+            logger.verbose("Trying to register file: %s", file);
+            await import(pathToFileURL(file).href + stamp);
+        }
+        // TODO: Implement test grouping
+        return registeredTests().filter((test) => isSelected(test.name, this.options));
+    }
+    /** Runs the selected tests and returns the summary that was also written to the report */
+    async start() {
+        const { reportPath, onEvent, signal } = this.options;
+        const reporter = new TestReporter({
+            environment: this.run.settings.environment,
+            ...(reportPath !== undefined && { output: reportPath }),
+            ...(onEvent && { onEvent }),
+        });
+        const selected = await this.register();
+        reporter.onStart(selected.length);
+        for (const test of selected) {
+            if (signal?.aborted) {
+                reporter.onTestStart(test);
+                reporter.onTestEnd(test, { message: "Run aborted", type: "error" });
+                continue;
+            }
+            await this.executeTestCase(test, reporter);
+        }
+        return reporter.onEnd();
+    }
+    async executeTestCase(test, reporter) {
+        logger.verbose("Starting test: %s", test.name);
+        reporter.onTestStart(test);
+        const selectedBrowser = (await readConfig("browser")) ?? "firefox";
+        const { settings, secrets } = this.run;
+        const timeout = settings.timeout;
+        let browser;
+        let page;
+        let timeoutTimer;
+        let onRunAborted;
+        const timeoutController = new AbortController();
+        await Promise.race([
+            new Promise((resolve) => {
+                timeoutTimer = setTimeout(() => {
+                    reporter.onTestEnd(test, {
+                        message: `Test timed out after ${timeout / 1000} seconds`,
+                        type: "timeout",
+                    });
+                    timeoutController.abort(new Error("Test timed out"));
+                    resolve();
+                }, timeout);
+                onRunAborted = () => {
+                    if (timeoutController.signal.aborted)
+                        return;
+                    reporter.onTestEnd(test, { message: "Run aborted", type: "error" });
+                    timeoutController.abort(new Error("Run aborted"));
+                    resolve();
+                };
+                this.options.signal?.addEventListener("abort", onRunAborted, {
+                    once: true,
+                });
+            }),
+            new Promise(async (resolve, reject) => {
+                try {
+                    const launched = await Browser.launch(selectedBrowser, {
+                        port: this.options.port ?? 9223,
+                        headless: this.options.headless ?? false,
+                    }, timeoutController.signal);
+                    browser = launched.browser;
+                    page = launched.page;
+                    const fixtures = {
+                        page: launched.page,
+                        browser: launched.browser,
+                        env: createEnvFixture(settings.environment, settings.variables),
+                        secrets: createSecretsFixture(settings.environment, secrets),
+                    };
+                    await test.function(fixtures);
+                    // Already reported as timed out
+                    if (timeoutController.signal.aborted)
+                        return resolve();
+                    const unawaited = takePendingAssertions();
+                    if (unawaited.length > 0) {
+                        reporter.onTestEnd(test, {
+                            message: unawaited
+                                .map((matcher) => `expect(locator).${matcher}() was not awaited`)
+                                .join("\n"),
+                            type: "assertion",
+                        }, await judgeLogs(page, true));
+                        return resolve();
+                    }
+                    const verdict = await judgeLogs(page, false);
+                    reporter.onTestEnd(test, verdict.error, verdict);
+                    resolve();
+                }
+                catch (err) {
+                    if (timeoutController.signal.aborted)
+                        return resolve();
+                    reporter.onTestEnd(test, toTestError(err), await judgeLogs(page, true));
+                    resolve();
+                }
+            }),
+        ]);
+        clearTimeout(timeoutTimer);
+        if (onRunAborted)
+            this.options.signal?.removeEventListener("abort", onRunAborted);
+        takePendingAssertions();
+        logger.verbose("Closing browser for test: %s", test.name);
+        await browser?.close();
+    }
+}
+/** Reads the page's log once the test body is done and applies config `logs` (see judgePageLogs) */
+async function judgeLogs(page, testFailed) {
+    if (!page)
+        return {};
+    try {
+        // Events and command replies share one ordered connection: after this, everything logged so far is in
+        await page.syncLogs();
+    }
+    catch (err) {
+        logger.debug("Could not sync the page's logs", { err });
+    }
+    let config;
+    try {
+        config = await readConfig("logs");
+    }
+    catch (err) {
+        logger.debug("Could not read logs config, using defaults", { err });
+    }
+    return judgePageLogs({
+        config,
+        entries: page.getLogs(),
+        errors: page.pageErrors(),
+        dropped: page.logsDropped,
+        testFailed,
+        allowPageErrors: page.pageErrorsAllowed,
+        routeErrors: page.routeErrors(),
+    });
+}
+export { describe, test } from "./registry.js";

package/dist/script/call-function.d.ts

@@ -0,0 +1,34 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { StackTrace } from "../types/bidi-modules/script.js";
+import { type Arg } from "./serialize.js";
+export interface CallOptions {
+    /** @default true. The auto-wait probes pass false */
+    awaitPromise?: boolean;
+    /**
+     * "root" keeps a handle alive in the browser; the result then comes back as a `RemoteObject`
+     * carrying it, and the caller must `disown` it. @default "none"
+     */
+    ownership?: "none" | "root";
+    /** Named sandbox realm to run in (see the preload-scripts spec) */
+    sandbox?: string;
+    thisArg?: Arg;
+}
+/** The page function threw */
+export declare class ScriptError extends Error {
+    /** The browser's description, e.g. "TypeError: el is null" */
+    readonly text: string;
+    readonly stackTrace: StackTrace | undefined;
+    /** Start of the function that threw */
+    readonly functionSource: string;
+    constructor(text: string, functionSource: string, stackTrace?: StackTrace);
+}
+/** A function cannot be sent as source */
+export declare class ScriptSerializationError extends Error {
+    constructor(message: string);
+}
+/** The source to send for `fn`; a function object must not depend on transpiler helpers */
+export declare function toFunctionDeclaration(fn: string | ((...args: any[]) => unknown)): string;
+/** Calls `fn` in the page with serialized arguments and returns its deserialized result */
+export declare function callFunction<T = unknown>(connector: BiDiConnector, context: string, fn: string | ((...args: any[]) => unknown), args?: Arg[], options?: CallOptions): Promise<T>;
+/** Releases handles obtained with `ownership: "root"`; a handle that is already gone is fine */
+export declare function disown(connector: BiDiConnector, context: string, handles: string[]): Promise<void>;

package/dist/script/call-function.js

@@ -0,0 +1,71 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { fromRemoteValue, toLocalValue } from "./serialize.js";
+/** How much of a function's source `ScriptError` keeps */
+const SOURCE_PREVIEW = 200;
+/** The page function threw */
+export class ScriptError extends Error {
+    constructor(text, functionSource, stackTrace) {
+        super(`Script threw: ${text}`);
+        this.name = "ScriptError";
+        this.text = text;
+        this.stackTrace = stackTrace;
+        this.functionSource =
+            functionSource.length > SOURCE_PREVIEW
+                ? functionSource.slice(0, SOURCE_PREVIEW) + "…"
+                : functionSource;
+    }
+}
+/** A function cannot be sent as source */
+export class ScriptSerializationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScriptSerializationError";
+    }
+}
+/** The source to send for `fn`; a function object must not depend on transpiler helpers */
+export function toFunctionDeclaration(fn) {
+    if (typeof fn === "string")
+        return fn;
+    const source = fn.toString();
+    // tsx/esbuild wrap named functions in a __name() helper that does not exist in the page
+    if (source.includes("__name(")) {
+        throw new ScriptSerializationError("The function's source uses the transpiler's __name helper, which does not exist in the page. " +
+            "Use an arrow function without inner named functions, or pass the function as a string.");
+    }
+    return source;
+}
+/** Calls `fn` in the page with serialized arguments and returns its deserialized result */
+export async function callFunction(connector, context, fn, args = [], options = {}) {
+    const functionDeclaration = toFunctionDeclaration(fn);
+    const ownership = options.ownership ?? "none";
+    // Serialize first: a bad argument must fail before anything is sent
+    const serialized = args.map(toLocalValue);
+    const thisValue = "thisArg" in options ? toLocalValue(options.thisArg) : undefined;
+    const result = await connector.send("script.callFunction", {
+        functionDeclaration,
+        awaitPromise: options.awaitPromise ?? true,
+        target: options.sandbox === undefined
+            ? { context }
+            : { context, sandbox: options.sandbox },
+        ...(serialized.length > 0 && { arguments: serialized }),
+        resultOwnership: ownership,
+        ...(thisValue !== undefined && { this: thisValue }),
+    });
+    if (result.type === "exception") {
+        throw new ScriptError(result.exceptionDetails.text, functionDeclaration, result.exceptionDetails.stackTrace);
+    }
+    return fromRemoteValue(result.result, { keepHandles: ownership === "root" });
+}
+/** Releases handles obtained with `ownership: "root"`; a handle that is already gone is fine */
+export async function disown(connector, context, handles) {
+    if (handles.length === 0)
+        return;
+    try {
+        await connector.send("script.disown", { handles, target: { context } });
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "no such handle")
+            return;
+        throw err;
+    }
+}

package/dist/script/element-handle.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A reference to a DOM node in the browser. The `sharedId` stays valid across scripts in the
+ * same document; after navigation or removal the browser answers `no such node`.
+ * Internal: user code keeps using `Locator`.
+ */
+export declare class ElementHandle {
+    readonly sharedId: string;
+    readonly handle?: string | undefined;
+    constructor(sharedId: string, handle?: string | undefined);
+}

package/{src/script/element-handle.ts → dist/script/element-handle.js}

@@ -4,8 +4,8 @@
  * Internal: user code keeps using `Locator`.
  */
 export class ElementHandle {
-  constructor(
-    public readonly sharedId: string,
-    public readonly handle?: string,
-  ) {}
+    constructor(sharedId, handle) {
+        this.sharedId = sharedId;
+        this.handle = handle;
+    }
 }

package/dist/script/helpers.d.ts

@@ -0,0 +1,28 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** Sandbox realm holding the framework's helpers: same DOM as the page, separate JS globals */
+export declare const HELPER_SANDBOX = "samurai";
+/** What `CALL_PROBE` answers with when the helpers are not installed in the document */
+export declare const HELPERS_MISSING = "samurai:helpers-missing";
+/** Installs `globalThis.__samurai` in the sandbox realm of a document */
+export declare const HELPERS_SOURCE: string;
+/** Calls the installed probe, or reports that the helpers are missing instead of throwing */
+export declare const CALL_PROBE: string;
+/** What the locator needs from the helper realm */
+export interface HelperInstaller {
+    /** Resolves once the helpers are registered for the page; installs on first use */
+    ensureInstalled(): Promise<void>;
+    /** Runs the helpers again in the loaded documents; used when a call found them missing */
+    reinstall(): Promise<void>;
+}
+/** The framework's helper library for one page: registered once, applied to every document */
+export declare class HelperRealm implements HelperInstaller {
+    private connector;
+    private contextId;
+    private installed;
+    constructor(connector: BiDiConnector, contextId: string);
+    ensureInstalled(): Promise<void>;
+    reinstall(): Promise<void>;
+    /** Removes the registration; nothing is sent when the helpers were never installed */
+    dispose(): Promise<void>;
+    private options;
+}

package/dist/script/helpers.js

@@ -0,0 +1,50 @@
+import { PROBE_ELEMENT } from "../locator/element-state.js";
+import { addPreload, runInLoadedContexts } from "./preload.js";
+/** Sandbox realm holding the framework's helpers: same DOM as the page, separate JS globals */
+export const HELPER_SANDBOX = "samurai";
+/** What `CALL_PROBE` answers with when the helpers are not installed in the document */
+export const HELPERS_MISSING = "samurai:helpers-missing";
+/** Installs `globalThis.__samurai` in the sandbox realm of a document */
+export const HELPERS_SOURCE = `() => {
+  globalThis.__samurai = { probeElement: ${PROBE_ELEMENT} };
+}`;
+/** Calls the installed probe, or reports that the helpers are missing instead of throwing */
+export const CALL_PROBE = `(...args) => {
+  const helpers = globalThis.__samurai;
+  return helpers ? helpers.probeElement(...args) : ${JSON.stringify(HELPERS_MISSING)};
+}`;
+/** The framework's helper library for one page: registered once, applied to every document */
+export class HelperRealm {
+    constructor(connector, contextId) {
+        this.connector = connector;
+        this.contextId = contextId;
+    }
+    ensureInstalled() {
+        this.installed ??= addPreload(this.connector, this.options()).catch((err) => {
+            this.installed = undefined;
+            throw err;
+        });
+        return this.installed.then(() => undefined);
+    }
+    async reinstall() {
+        if (!this.installed)
+            return this.ensureInstalled();
+        await this.installed;
+        await runInLoadedContexts(this.connector, this.options());
+    }
+    /** Removes the registration; nothing is sent when the helpers were never installed */
+    async dispose() {
+        const installed = this.installed;
+        this.installed = undefined;
+        if (!installed)
+            return;
+        await (await installed).dispose();
+    }
+    options() {
+        return {
+            source: HELPERS_SOURCE,
+            contexts: [this.contextId],
+            sandbox: HELPER_SANDBOX,
+        };
+    }
+}

package/dist/script/preload.d.ts

@@ -0,0 +1,31 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type ChannelArg } from "./serialize.js";
+export interface PreloadHandle {
+    readonly id: string;
+    /** Idempotent. Documents that are already loaded keep the effect until they navigate */
+    dispose(): Promise<void>;
+}
+export interface RunOptions {
+    /** A function declaration, e.g. `() => { … }` */
+    source: string;
+    /** Top-level contexts to cover, including their iframes. Default: every top-level context */
+    contexts?: string[];
+    /** Named sandbox realm; without it the script runs in the page's own realm */
+    sandbox?: string;
+    /** Channels the function receives as arguments, in the preload registration and in the immediate run */
+    arguments?: ChannelArg[];
+    /**
+     * What to do when the immediate run in an already-loaded document throws.
+     * "log" suits user init scripts (the browser reports such errors for later documents itself)
+     * @default "throw"
+     */
+    onRunError?: "throw" | "log";
+}
+/**
+ * Registers `source` to run before any page script in every future document of `contexts`, and
+ * also runs it once in the documents that are loaded now: preload scripts only affect documents
+ * created after registration, and callers should not have to care about that ordering.
+ */
+export declare function addPreload(connector: BiDiConnector, options: RunOptions): Promise<PreloadHandle>;
+/** Runs `source` once in every loaded context (iframes included) under `contexts` */
+export declare function runInLoadedContexts(connector: BiDiConnector, { source, contexts, sandbox, onRunError, arguments: args, }: RunOptions): Promise<void>;

package/dist/script/preload.js

@@ -0,0 +1,71 @@
+import logger from "../logger/index.js";
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction, ScriptError } from "./call-function.js";
+import { toLocalValue } from "./serialize.js";
+/**
+ * Registers `source` to run before any page script in every future document of `contexts`, and
+ * also runs it once in the documents that are loaded now: preload scripts only affect documents
+ * created after registration, and callers should not have to care about that ordering.
+ */
+export async function addPreload(connector, options) {
+    const { script } = await connector.send("script.addPreloadScript", {
+        functionDeclaration: options.source,
+        ...(options.contexts && { contexts: options.contexts }),
+        ...(options.sandbox !== undefined && { sandbox: options.sandbox }),
+        ...(options.arguments && {
+            arguments: options.arguments.map((arg) => toLocalValue(arg)),
+        }),
+    });
+    let removed = false;
+    const dispose = async () => {
+        if (removed)
+            return;
+        removed = true;
+        try {
+            await connector.send("script.removePreloadScript", { script });
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "no such script")
+                return;
+            throw err;
+        }
+    };
+    try {
+        // Registered first, so a document created while this runs is covered by the registration
+        await runInLoadedContexts(connector, options);
+    }
+    catch (err) {
+        await dispose().catch((disposeErr) => logger.debug("Could not remove preload script after a failed run", {
+            disposeErr,
+        }));
+        throw err;
+    }
+    return { id: script, dispose };
+}
+/** Runs `source` once in every loaded context (iframes included) under `contexts` */
+export async function runInLoadedContexts(connector, { source, contexts, sandbox, onRunError = "throw", arguments: args = [], }) {
+    const trees = contexts
+        ? await Promise.all(contexts.map((root) => connector.send("browsingContext.getTree", { root })))
+        : [await connector.send("browsingContext.getTree", {})];
+    const loaded = trees.flatMap((tree) => tree.contexts.flatMap(flatten));
+    const outcomes = await Promise.allSettled(loaded.map((context) => callFunction(connector, context, source, args, {
+        awaitPromise: false,
+        ...(sandbox !== undefined && { sandbox }),
+    })));
+    for (const outcome of outcomes) {
+        if (outcome.status === "fulfilled")
+            continue;
+        const err = outcome.reason;
+        // The context closed between listing and running: nothing left to cover
+        if (err instanceof BiDiError && err.code === "no such frame")
+            continue;
+        if (err instanceof ScriptError && onRunError === "log") {
+            logger.warn("Script threw while running in a loaded document: %s", err.text);
+            continue;
+        }
+        throw err;
+    }
+}
+function flatten(info) {
+    return [info.context, ...(info.children ?? []).flatMap(flatten)];
+}

package/dist/script/serialize.d.ts

@@ -0,0 +1,29 @@
+import type { ArgumentValue, RemoteValue } from "../types/bidi-modules/script.js";
+/** A value passed to a page function */
+export type Arg = unknown;
+/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by type and handle */
+export declare class RemoteObject {
+    readonly type: string;
+    readonly handle?: string | undefined;
+    /** The deserialized value, when the browser sent one and handles were kept */
+    readonly value?: unknown | undefined;
+    constructor(type: string, handle?: string | undefined, 
+    /** The deserialized value, when the browser sent one and handles were kept */
+    value?: unknown | undefined);
+}
+/**
+ * A channel the page function can call as `send(value)`; the browser delivers each value as a
+ * `script.message` event. Only meaningful as a preload script or function argument.
+ */
+export declare class ChannelArg {
+    readonly channel: string;
+    constructor(channel: string);
+}
+/** Serializes `value` for `script.callFunction` arguments; throws TypeError for what cannot cross the wire */
+export declare function toLocalValue(value: Arg): ArgumentValue;
+export interface DeserializeOptions {
+    /** Return objects that carry a handle as `RemoteObject`s (with `.value`), so the caller can disown them later */
+    keepHandles?: boolean;
+}
+/** Converts a remote value to plain JS; what cannot be copied becomes a `RemoteObject` */
+export declare function fromRemoteValue(value: RemoteValue, options?: DeserializeOptions): unknown;