@itmetsam/samurai-framework 0.1.0 → 0.2.1

package/dist/browser/browser-context.js

@@ -0,0 +1,146 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { applyEmulation } from "./emulation.js";
+/**
+ * An isolated browsing session inside one browser: its own cookies, storage and cache. Pages opened in it
+ * share them; pages of other contexts see none of it.
+ */
+export class BrowserContext {
+    constructor(host, 
+    /** The BiDi user context id; "default" for the browser's own */
+    id, isDefault) {
+        this.host = host;
+        this.id = id;
+        this.isDefault = isDefault;
+        this.opened = [];
+        this.isClosed = false;
+    }
+    /** True once `close()` has run */
+    get closed() {
+        return this.isClosed;
+    }
+    /** Opens a tab in this context */
+    async newPage() {
+        this.assertOpen();
+        return this.host.newPage({ type: "tab", ...(!this.isDefault && { userContext: this.id }) });
+    }
+    /** The pages opened in this context that are still open */
+    pages() {
+        this.opened = this.opened.filter((page) => !page.closed);
+        return [...this.opened];
+    }
+    /** @internal Called when a page is opened in this context */
+    register(page) {
+        this.opened.push(page);
+        page.setContext(this);
+    }
+    /** Adds cookies to this context's storage. Every cookie is checked before any is stored */
+    async addCookies(cookies) {
+        this.assertOpen();
+        const prepared = cookies.map(toBiDiCookie);
+        for (const cookie of prepared) {
+            await this.host.connector.send("storage.setCookie", { cookie, partition: this.partition() });
+        }
+    }
+    /** The cookies of this context, optionally only those matching `filter` */
+    async cookies(filter) {
+        this.assertOpen();
+        const { cookies } = await this.host.connector.send("storage.getCookies", {
+            ...(filter && { filter }),
+            partition: this.partition(),
+        });
+        return cookies.map(toCookie);
+    }
+    /** Deletes all cookies of this context, or those matching `filter` */
+    async clearCookies(filter) {
+        this.assertOpen();
+        await this.host.connector.send("storage.deleteCookies", {
+            ...(filter && { filter }),
+            partition: this.partition(),
+        });
+    }
+    /**
+     * Pretends things about every page of this context, including pages opened later: locale, timezone, user agent,
+     * geolocation, offline, orientation, screen size. A page's own `emulate()` wins over the context's.
+     * @example
+     *  await context.emulate({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
+     */
+    async emulate(options) {
+        this.assertOpen();
+        await applyEmulation(this.host.connector, { userContexts: [this.id] }, options);
+    }
+    /**
+     * Grants, denies or resets a browser permission ("geolocation", "notifications", "camera", …) for `origin`
+     * in this context. Geolocation emulation only answers once the permission is granted.
+     */
+    async setPermission(name, state, origin) {
+        this.assertOpen();
+        await this.host.connector.send("permissions.setPermission", {
+            descriptor: { name },
+            state,
+            origin,
+            ...(!this.isDefault && { userContext: this.id }),
+        });
+    }
+    /** Removes the context; the browser closes its pages. The default context cannot be closed */
+    async close() {
+        if (this.isDefault)
+            throw new Error("cannot close the default context");
+        if (this.isClosed)
+            return;
+        try {
+            await this.host.connector.send("browser.removeUserContext", { userContext: this.id });
+        }
+        catch (err) {
+            // Already gone: the goal is met
+            if (!(err instanceof BiDiError && err.code === "no such user context"))
+                throw err;
+        }
+        this.isClosed = true;
+        const pages = this.opened;
+        this.opened = [];
+        await Promise.all(pages.map((page) => page.detach()));
+        this.host.forget(this);
+    }
+    partition() {
+        return { type: "storageKey", userContext: this.id };
+    }
+    assertOpen() {
+        if (this.isClosed)
+            throw new Error("context closed");
+    }
+}
+function toBiDiCookie(input) {
+    let { domain, path, secure } = input;
+    if (input.url !== undefined) {
+        const url = new URL(input.url);
+        domain ??= url.hostname;
+        path ??= url.pathname;
+        secure ??= url.protocol === "https:";
+    }
+    if (domain === undefined)
+        throw new TypeError(`cookie "${input.name}" needs a domain or a url`);
+    return {
+        name: input.name,
+        value: { type: "string", value: input.value },
+        domain,
+        path: path ?? "/",
+        ...(secure !== undefined && { secure }),
+        ...(input.httpOnly !== undefined && { httpOnly: input.httpOnly }),
+        ...(input.sameSite !== undefined && { sameSite: input.sameSite }),
+        ...(input.expiry !== undefined && { expiry: input.expiry }),
+    };
+}
+function toCookie(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value.type === "base64"
+            ? Buffer.from(cookie.value.value, "base64").toString("utf8")
+            : cookie.value.value,
+        domain: cookie.domain,
+        path: cookie.path,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite,
+        ...(cookie.expiry !== undefined && { expiry: cookie.expiry }),
+    };
+}

package/dist/browser/browser-finder.d.ts

@@ -0,0 +1,2 @@
+import type { SupportedBrowser } from "../types/browser.js";
+export declare function findBrowser(browserName: SupportedBrowser): string;

package/dist/browser/browser-finder.js

@@ -0,0 +1,95 @@
+import assert from "node:assert";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import logger from "../logger/index.js";
+const supportedBrowsers = ["firefox"];
+const macBrowserPaths = {
+    // chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    firefox: "/Applications/Firefox.app/Contents/MacOS/Firefox",
+};
+export function findBrowser(browserName) {
+    logger.verbose("Checking install location for %s", browserName);
+    if (!supportedBrowsers.includes(browserName)) {
+        throw new Error("This browser is not supported. Supported browsers include: " +
+            supportedBrowsers.join(", "));
+    }
+    let browserLocation = "";
+    const notFoundMsg = `Cannot find browser ${browserName} on this machine! Is it installed?`;
+    try {
+        browserLocation = tryFindBrowser(browserName);
+    }
+    catch (err) {
+        throw new Error(notFoundMsg);
+    }
+    assert(browserLocation, notFoundMsg);
+    logger.verbose("Browser found at: %s", browserLocation);
+    return browserLocation;
+}
+function tryFindBrowser(browserName) {
+    logger.debug("Current platform: %s", process.platform);
+    switch (process.platform) {
+        case "win32":
+            return findBrowserWindows(browserName);
+        case "darwin":
+            return findBrowserMac(browserName);
+        case "linux":
+            return findBrowserLinux(browserName);
+        default:
+            throw new Error("This platform is not supported");
+    }
+}
+function findBrowserWindows(browserName) {
+    // Function to prevent search the entire file system
+    // We'll only try the most common paths
+    const possibleDirs = ["Program\ Files", "Program\ Files (x86)"];
+    const where = (dirPath) => {
+        const command = `where /r ${dirPath} ${browserName}.exe`;
+        try {
+            logger.verbose("Running command: %s", command);
+            const whereResults = execSync(command, {
+                encoding: "utf8",
+            });
+            logger.debug("Command results: \n", whereResults);
+            const results = whereResults.split(/\n/g);
+            return results[0];
+        }
+        catch (error) {
+            logger.verbose("Error while executing %s", command, { error });
+        }
+    };
+    let result = undefined;
+    for (const possibleDir of possibleDirs) {
+        logger.debug("Checking directory: %s", possibleDir);
+        result = where(possibleDir);
+        if (result)
+            break;
+    }
+    if (!result) {
+        throw new Error("'where' yielded no results");
+    }
+    return result;
+}
+function findBrowserMac(browserName) {
+    const checkPathExists = (path) => {
+        logger.debug("Checking path: %s", path);
+        const exists = existsSync(path);
+        if (!exists) {
+            throw new Error(`Did not find ${browserName} at ${path}`);
+        }
+        return path;
+    };
+    return checkPathExists(macBrowserPaths[browserName]);
+}
+const linuxBinaryNames = {
+    // chrome: "google-chrome",
+    firefox: "firefox",
+};
+function findBrowserLinux(browserName) {
+    const command = `which ${linuxBinaryNames[browserName]}`;
+    logger.debug("Running command: %s", command);
+    const result = execSync(command, {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    return result.replace(/\n/g, "");
+}

package/dist/browser/browser.d.ts

@@ -0,0 +1,95 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { SupportedBrowser } from "../types/browser.js";
+import { BiDiConnector } from "../transport/bidi-connection.js";
+import Page from "./page.js";
+import { BrowserContext } from "./browser-context.js";
+import type { UserPromptHandler } from "../types/bidi-modules/session.js";
+import { type EmulationOptions } from "./emulation.js";
+import type { BiDiCommands } from "../types/bidi.js";
+import type { CookieFilter, PartialCookie, PartitionDescriptor } from "../types/bidi-modules/storage.js";
+/**
+ * Sent with session.new. With "ignore" the browser leaves a JavaScript dialog open and reports it
+ * (`browsingContext.userPromptOpened`), so the framework decides how to answer instead of the browser.
+ */
+export declare const SESSION_CAPABILITIES: {
+    alwaysMatch: {
+        unhandledPromptBehavior: {
+            default: string;
+        };
+    };
+};
+export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOptions: Partial<BrowserLaunchOptions>) => string[];
+/**
+ * Stops what a failed launch started. A browser left running holds the profile (the next launch
+ * fails with "already open") and keeps the test process alive.
+ */
+export declare function abandonLaunch(browserProc: {
+    kill(): boolean;
+}, biDiConnector: {
+    kill(): void;
+} | undefined): void;
+export interface BrowserLaunchOptions {
+    /** Which port to use for the WebDeveloper tools */
+    port: number;
+    /** Firefox only */
+    profileDir: string;
+    /** Start the browser in headless mode or in UI mode */
+    headless: boolean;
+}
+/** Options of `browser.newContext()` */
+export interface ContextOptions extends EmulationOptions {
+    acceptInsecureCerts?: boolean;
+    /** How this context's pages answer JavaScript dialogs; the session default is to leave them for the framework */
+    unhandledPromptBehavior?: UserPromptHandler;
+}
+export declare class Browser {
+    private browserProc;
+    private biDiConnector;
+    private userContexts;
+    private host;
+    /** The browser's own context, the one `Browser.launch`'s page lives in */
+    readonly defaultContext: BrowserContext;
+    /** Where downloads are saved; undefined when the browser could not be told (it then uses its own folder) */
+    readonly downloadsDir: string | undefined;
+    private exitedPromise;
+    constructor({ browserProc, biDiConnector, downloadsDir, }: {
+        browserProc: ChildProcessWithoutNullStreams;
+        biDiConnector: BiDiConnector;
+        downloadsDir?: string | undefined;
+    });
+    /** Resolves when the browser process has exited, whether `close()` or a person closed it */
+    get exited(): Promise<void>;
+    static launch(browserName: SupportedBrowser, launchOptions?: Partial<BrowserLaunchOptions>, 
+    /** Aborting kills the browser process and rejects the launch */
+    signal?: AbortSignal): Promise<{
+        browser: Browser;
+        page: Page;
+    }>;
+    /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
+    close(): Promise<void>;
+    /** Alias of close() */
+    kill(): Promise<void>;
+    newPage({ type, background, userContext, }: BiDiCommands["browsingContext.create"]["params"]): Promise<Page>;
+    /**
+     * Creates an isolated context: its own cookies, storage and cache. `browser.close()` removes the contexts
+     * that are still open, as Firefox would otherwise keep them in its profile.
+     * @example
+     *  const alice = await browser.newContext();
+     *  const page = await alice.newPage();
+     */
+    newContext(options?: ContextOptions): Promise<BrowserContext>;
+    /** The default context, then the contexts this browser created that are still open */
+    contexts(): BrowserContext[];
+    private contextFor;
+    /** A user context this browser did not create (Firefox keeps them in its profile): usable, never closed by `close()` */
+    private adopt;
+    getCookie(filter: CookieFilter, partition: PartitionDescriptor): Promise<{
+        cookies: import("../types/bidi-modules/network.js").Cookie[];
+        partitionKey: import("../types/bidi-modules/storage.js").PartitionKey;
+    }>;
+    setCookie(cookie: PartialCookie, partition?: PartitionDescriptor): Promise<{
+        partitionKey: import("../types/bidi-modules/storage.js").PartitionKey;
+    }>;
+}
+/** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
+export declare function ensureBrowserProfile(browserName: SupportedBrowser, profilePath?: string | undefined): void;