@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/browser/page-logs.test.ts

@@ -1,212 +0,0 @@
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { autoReply, FakeWebSocket, tick } from "../testing/fake-websocket.js";
-import { BiDiConnector } from "../transport/bidi-connection.js";
-import { ContextTree } from "./context-tree.js";
-import { ConsoleMessage, PageError, PageLogs } from "./page-logs.js";
-
-const TREE = [
-  { context: "top", parent: null, children: [{ context: "frame", parent: "top", children: [] }] },
-  { context: "other", parent: null, children: [] },
-];
-const stops: Array<() => void> = [];
-afterEach(() => stops.splice(0).forEach((stop) => stop()));
-
-async function setup(options?: { maxEntries?: number }) {
-  const ws = new FakeWebSocket();
-  const connector = new BiDiConnector(ws as unknown as WebSocket);
-  stops.push(autoReply(ws, { "browsingContext.getTree": () => ({ contexts: TREE }) }));
-  const tree = await ContextTree.create(connector);
-  const logs = await PageLogs.start(connector, tree, "top", options);
-  return { ws, logs };
-}
-
-const source = (context: string | undefined) => ({ realm: "r", userContext: "default", ...(context && { context }) });
-const str = (value: string) => ({ type: "string", value });
-const consoleEntry = (context: string | undefined, method: string, text: string, extra: object = {}) => ({
-  type: "console",
-  method,
-  level: method === "error" ? "error" : method === "warn" ? "warn" : "info",
-  text,
-  args: [str(text)],
-  timestamp: 1000,
-  source: source(context),
-  ...extra,
-});
-const errorEntry = (context: string | undefined, text: string, extra: object = {}) => ({
-  type: "javascript",
-  level: "error",
-  text,
-  timestamp: 2000,
-  source: source(context),
-  ...extra,
-});
-const emit = (ws: FakeWebSocket, entry: object) => ws.emitEvent("log.entryAdded", entry);
-
-describe("PageLogs console messages", () => {
-  it("turns a console entry into a ConsoleMessage with deserialized arguments", async () => {
-    const { ws, logs } = await setup();
-    const seen: ConsoleMessage[] = [];
-    logs.on("console", (message) => seen.push(message));
-    emit(ws, {
-      ...consoleEntry("top", "log", "a 1 {…}", {
-        args: [str("a"), { type: "number", value: 1 }, { type: "object", value: [["k", str("v")]] }],
-        stackTrace: { callFrames: [{ functionName: "run", url: "https://x.test/app.js", lineNumber: 4, columnNumber: 2 }] },
-      }),
-    });
-    assert.equal(seen.length, 1);
-    const [message] = seen as [ConsoleMessage];
-    assert.ok(message instanceof ConsoleMessage);
-    assert.equal(message.type(), "log");
-    assert.equal(message.text(), "a 1 {…}");
-    assert.equal(message.level, "info");
-    assert.deepEqual(message.args, ["a", 1, { k: "v" }]);
-    assert.equal(message.timestamp, 1000);
-    assert.deepEqual(message.location(), { url: "https://x.test/app.js", lineNumber: 4, columnNumber: 2 });
-  });
-
-  it("has no location without a stack, and an empty text for null", async () => {
-    const { ws, logs } = await setup();
-    let message!: ConsoleMessage;
-    logs.on("console", (m) => (message = m));
-    emit(ws, consoleEntry("top", "warn", "x", { text: null }));
-    assert.equal(message.location(), undefined);
-    assert.equal(message.text(), "");
-    assert.equal(message.type(), "warn");
-    assert.equal(message.level, "warn");
-  });
-
-  it("console.error is a log entry, not a page error", async () => {
-    const { ws, logs } = await setup();
-    emit(ws, consoleEntry("top", "error", "handled problem"));
-    assert.equal(logs.entries.length, 1);
-    assert.equal(logs.entries[0]!.level, "error");
-    assert.equal(logs.errors.length, 0);
-  });
-});
-
-describe("PageLogs page errors", () => {
-  it("turns an uncaught exception into a PageError with a readable stack", async () => {
-    const { ws, logs } = await setup();
-    const seen: PageError[] = [];
-    logs.on("pageerror", (error) => seen.push(error));
-    emit(ws, errorEntry("top", "TypeError: x is null", {
-      stackTrace: {
-        callFrames: [
-          { functionName: "click", url: "https://x.test/app.js", lineNumber: 10, columnNumber: 5 },
-          { functionName: "", url: "https://x.test/app.js", lineNumber: 20, columnNumber: 1 },
-        ],
-      },
-    }));
-    assert.equal(seen.length, 1);
-    const [error] = seen as [PageError];
-    assert.ok(error instanceof Error);
-    assert.ok(error instanceof PageError);
-    assert.equal(error.message, "TypeError: x is null");
-    assert.equal(error.name, "PageError");
-    assert.equal(error.timestamp, 2000);
-    assert.equal(
-      error.stack,
-      "TypeError: x is null\n    at click (https://x.test/app.js:10:5)\n    at https://x.test/app.js:20:1",
-    );
-    assert.deepEqual(logs.errors, [error]);
-    assert.deepEqual(logs.entries.map((entry) => entry.type), ["javascript"]);
-  });
-
-  it("a PageError without a stack is just its text", async () => {
-    const { ws, logs } = await setup();
-    emit(ws, errorEntry("top", "Error: bare"));
-    assert.equal(logs.errors[0]!.stack, "Error: bare");
-  });
-});
-
-describe("PageLogs scope", () => {
-  it("keeps entries of iframes, drops other pages and entries without a context", async () => {
-    const { ws, logs } = await setup();
-    emit(ws, consoleEntry("frame", "log", "from frame"));
-    emit(ws, consoleEntry("other", "log", "from another page"));
-    emit(ws, consoleEntry(undefined, "log", "from a worker"));
-    assert.deepEqual(logs.entries.map((entry) => entry.text), ["from frame"]);
-  });
-
-  it("records entries of other types without emitting an event", async () => {
-    const { ws, logs } = await setup();
-    let events = 0;
-    logs.on("console", () => events++);
-    logs.on("pageerror", () => events++);
-    emit(ws, { type: "deprecation", level: "warn", text: "old api", timestamp: 3, source: source("top") });
-    assert.equal(events, 0);
-    assert.deepEqual(logs.entries.map((entry) => [entry.type, entry.text]), [["deprecation", "old api"]]);
-  });
-});
-
-describe("PageLogs buffer", () => {
-  it("keeps the newest entries and counts what it dropped", async () => {
-    const { ws, logs } = await setup({ maxEntries: 3 });
-    for (let i = 1; i <= 5; i++) emit(ws, consoleEntry("top", "log", `m${i}`));
-    assert.deepEqual(logs.entries.map((entry) => entry.text), ["m3", "m4", "m5"]);
-    assert.equal(logs.dropped, 2);
-  });
-
-  it("records level, type, method, text and timestamp", async () => {
-    const { ws, logs } = await setup();
-    emit(ws, consoleEntry("top", "warn", "careful"));
-    assert.deepEqual(logs.entries[0], { level: "warn", type: "console", method: "warn", text: "careful", timestamp: 1000 });
-    emit(ws, errorEntry("top", "Error: x"));
-    assert.deepEqual(logs.entries[1], { level: "error", type: "javascript", text: "Error: x", timestamp: 2000 });
-  });
-
-  it("clear empties entries, errors and the dropped count", async () => {
-    const { ws, logs } = await setup({ maxEntries: 1 });
-    emit(ws, consoleEntry("top", "log", "a"));
-    emit(ws, consoleEntry("top", "log", "b"));
-    emit(ws, errorEntry("top", "Error: x"));
-    logs.clear();
-    assert.equal(logs.entries.length, 0);
-    assert.equal(logs.errors.length, 0);
-    assert.equal(logs.dropped, 0);
-  });
-
-  it("entries is a snapshot: later entries do not change what was read", async () => {
-    const { ws, logs } = await setup();
-    emit(ws, consoleEntry("top", "log", "a"));
-    const before = logs.entries;
-    emit(ws, consoleEntry("top", "log", "b"));
-    assert.equal(before.length, 1);
-  });
-});
-
-describe("PageLogs lifecycle", () => {
-  it("a throwing listener does not stop the others or the recording", async () => {
-    const { ws, logs } = await setup();
-    let second = 0;
-    logs.on("console", () => {
-      throw new Error("listener failed");
-    });
-    logs.on("console", () => second++);
-    emit(ws, consoleEntry("top", "log", "a"));
-    assert.equal(second, 1);
-    assert.equal(logs.entries.length, 1);
-  });
-
-  it("off removes a listener", async () => {
-    const { ws, logs } = await setup();
-    let count = 0;
-    const listener = () => count++;
-    logs.on("console", listener);
-    logs.off("console", listener);
-    emit(ws, consoleEntry("top", "log", "a"));
-    assert.equal(count, 0);
-  });
-
-  it("subscribes to log.entryAdded and releases it on dispose", async () => {
-    const { ws, logs } = await setup();
-    assert.ok(ws.sent.some((m) => m.method === "session.subscribe" && (m.params as any).events[0] === "log.entryAdded"));
-    await logs.dispose();
-    await tick(10);
-    emit(ws, consoleEntry("top", "log", "late"));
-    assert.equal(logs.entries.length, 0);
-    assert.ok(ws.sent.some((m) => m.method === "session.unsubscribe"), "the log subscription was released");
-    await assert.doesNotReject(logs.dispose());
-  });
-});

package/src/browser/page-logs.ts

@@ -1,208 +0,0 @@
-import EventEmitter from "node:events";
-import logger from "../logger/index.js";
-import { fromRemoteValue } from "../script/serialize.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import type { Subscription } from "../transport/subscriptions.js";
-import type { ConsoleLogEntry, Entry, Level } from "../types/bidi-modules/log.js";
-import type { StackFrame, StackTrace } from "../types/bidi-modules/script.js";
-import type { ContextTree } from "./context-tree.js";
-
-/** How many entries a page keeps before the oldest are dropped */
-const DEFAULT_MAX_ENTRIES = 1000;
-
-/** One line of the browser's log, as kept for reports */
-export interface LogRecord {
-  level: Level;
-  /** "console", "javascript" (an uncaught exception), or another type the browser reports */
-  type: string;
-  /** The console method, for `type: "console"` */
-  method?: string;
-  text: string;
-  timestamp: number;
-}
-
-export interface SourceLocation {
-  url: string;
-  lineNumber: number;
-  columnNumber: number;
-}
-
-/** A call to `console.log`, `console.warn`, … in the page */
-export class ConsoleMessage {
-  constructor(
-    /** "debug" | "info" | "warn" | "error" */
-    public readonly level: Level,
-    private readonly method: string,
-    private readonly message: string,
-    /** The arguments as plain values; DOM nodes and functions stay opaque (ElementHandle, RemoteObject) */
-    public readonly args: unknown[],
-    public readonly timestamp: number,
-    public readonly stackTrace?: StackTrace,
-  ) {}
-
-  /** The console method: "log", "warn", "error", "info", "debug", … */
-  public type(): string {
-    return this.method;
-  }
-
-  /** What the browser prints for the call */
-  public text(): string {
-    return this.message;
-  }
-
-  /** Where the call was made, when the browser says */
-  public location(): SourceLocation | undefined {
-    const frame = this.stackTrace?.callFrames[0];
-    return frame && { url: frame.url, lineNumber: frame.lineNumber, columnNumber: frame.columnNumber };
-  }
-}
-
-/** An exception nobody caught in the page */
-export class PageError extends Error {
-  public readonly timestamp: number;
-
-  constructor(text: string, timestamp: number, stackTrace?: StackTrace) {
-    super(text);
-    this.name = "PageError";
-    this.timestamp = timestamp;
-    this.stack = [text, ...(stackTrace?.callFrames ?? []).map(formatFrame)].join("\n");
-  }
-}
-
-function formatFrame({ functionName, url, lineNumber, columnNumber }: StackFrame): string {
-  const where = `${url}:${lineNumber}:${columnNumber}`;
-  return functionName ? `    at ${functionName} (${where})` : `    at ${where}`;
-}
-
-interface EventMap {
-  console: [ConsoleMessage];
-  pageerror: [PageError];
-}
-export type LogEventName = keyof EventMap;
-
-/**
- * Collects the browser's log (`console.*` calls and uncaught exceptions) of one page, frames included,
- * in a ring buffer, and emits `console` and `pageerror` events.
- */
-export class PageLogs {
-  private events = new EventEmitter();
-  private buffer: LogRecord[] = [];
-  private uncaught: PageError[] = [];
-  private droppedCount = 0;
-  private disposed = false;
-  private subscription: Subscription | undefined;
-
-  private constructor(
-    private connector: BiDiConnector,
-    private tree: ContextTree,
-    private contextId: string,
-    private maxEntries: number,
-  ) {}
-
-  public static async start(
-    connector: BiDiConnector,
-    tree: ContextTree,
-    contextId: string,
-    options: { maxEntries?: number } = {},
-  ): Promise<PageLogs> {
-    const logs = new PageLogs(connector, tree, contextId, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
-    connector.onEvent("log.entryAdded", logs.onEntry);
-    try {
-      logs.subscription = await connector.subscribe(["log.entryAdded"]);
-    } catch (err) {
-      connector.offEvent("log.entryAdded", logs.onEntry);
-      throw err;
-    }
-    return logs;
-  }
-
-  /** The newest entries, oldest first (a copy) */
-  public get entries(): readonly LogRecord[] {
-    return [...this.buffer];
-  }
-
-  /** Uncaught exceptions seen since the start or the last `clear()` */
-  public get errors(): readonly PageError[] {
-    return [...this.uncaught];
-  }
-
-  /** How many entries fell out of the buffer */
-  public get dropped(): number {
-    return this.droppedCount;
-  }
-
-  public on<E extends LogEventName>(event: E, listener: (...args: EventMap[E]) => void): void {
-    this.events.on(event, listener as (...args: unknown[]) => void);
-  }
-
-  public off<E extends LogEventName>(event: E, listener: (...args: EventMap[E]) => void): void {
-    this.events.off(event, listener as (...args: unknown[]) => void);
-  }
-
-  public clear(): void {
-    this.buffer = [];
-    this.uncaught = [];
-    this.droppedCount = 0;
-  }
-
-  /** Idempotent */
-  public async dispose(): Promise<void> {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.connector.offEvent("log.entryAdded", this.onEntry);
-    this.buffer = [];
-    this.uncaught = [];
-    await this.subscription?.unsubscribe();
-  }
-
-  private onEntry = (entry: Entry) => {
-    const context = entry.source.context;
-    // Worker realms have no context; entries of other pages are not ours
-    if (!context || !this.tree.isWithin(context, this.contextId)) return;
-
-    const text = entry.text ?? "";
-    const record: LogRecord = {
-      level: entry.level,
-      type: entry.type,
-      ...(entry.type === "console" && { method: (entry as ConsoleLogEntry).method }),
-      text,
-      timestamp: entry.timestamp,
-    };
-    this.buffer.push(record);
-    if (this.buffer.length > this.maxEntries) {
-      this.buffer.shift();
-      this.droppedCount++;
-    }
-
-    if (entry.type === "console") {
-      const consoleEntry = entry as ConsoleLogEntry;
-      this.emit(
-        "console",
-        new ConsoleMessage(
-          entry.level,
-          consoleEntry.method,
-          text,
-          (consoleEntry.args ?? []).map((arg) => fromRemoteValue(arg)),
-          entry.timestamp,
-          entry.stackTrace,
-        ),
-      );
-    } else if (entry.type === "javascript") {
-      const error = new PageError(text, entry.timestamp, entry.stackTrace);
-      this.uncaught.push(error);
-      if (this.uncaught.length > this.maxEntries) this.uncaught.shift();
-      this.emit("pageerror", error);
-    }
-  };
-
-  /** A listener that throws must not stop the recording or the other listeners */
-  private emit<E extends LogEventName>(event: E, ...args: EventMap[E]) {
-    for (const listener of this.events.rawListeners(event)) {
-      try {
-        listener(...args);
-      } catch (err) {
-        logger.error("A %s listener threw", event, { err });
-      }
-    }
-  }
-}

package/src/browser/page-wait.ts

@@ -1,19 +0,0 @@
-import { WaitTimeoutError } from "../wait/wait-until.js";
-
-/** No download started in time */
-export class DownloadWaitTimeoutError extends WaitTimeoutError<undefined> {
-  constructor(timeout: number) {
-    super(timeout, undefined);
-    this.name = "DownloadWaitTimeoutError";
-    this.message = `waitForDownload(): no download started within ${timeout}ms`;
-  }
-}
-
-/** No file picker opened in time */
-export class FileChooserTimeoutError extends WaitTimeoutError<undefined> {
-  constructor(timeout: number) {
-    super(timeout, undefined);
-    this.name = "FileChooserTimeoutError";
-    this.message = `waitForFileChooser(): no file chooser opened within ${timeout}ms`;
-  }
-}