@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/script/serialize.ts

@@ -1,203 +0,0 @@
-import type {
-  ArgumentValue,
-  RemoteValue,
-} from "../types/bidi-modules/script.js";
-import { ElementHandle } from "./element-handle.js";
-
-/** A value passed to a page function */
-export type Arg = unknown;
-
-/** Deepest nesting `toLocalValue` accepts; a second guard next to cycle detection */
-const MAX_DEPTH = 100;
-
-/** A remote value that cannot be copied to plain JS (function, window, promise, …), kept by type and handle */
-export class RemoteObject {
-  constructor(
-    public readonly type: string,
-    public readonly handle?: string,
-    /** The deserialized value, when the browser sent one and handles were kept */
-    public readonly value?: unknown,
-  ) {}
-}
-
-/** Serializes `value` for `script.callFunction` arguments; throws TypeError for what cannot cross the wire */
-export function toLocalValue(value: Arg): ArgumentValue {
-  return serialize(value, new Set(), 0);
-}
-
-function serialize(value: unknown, ancestors: Set<object>, depth: number): ArgumentValue {
-  if (depth > MAX_DEPTH) throw new TypeError("cannot serialize a value that is too deeply nested");
-
-  switch (typeof value) {
-    case "undefined":
-      return { type: "undefined" };
-    case "boolean":
-      return { type: "boolean", value };
-    case "string":
-      return { type: "string", value };
-    case "number":
-      return { type: "number", value: numberValue(value) };
-    case "bigint":
-      return { type: "bigint", value: value.toString() };
-    case "function":
-    case "symbol":
-      throw new TypeError(`cannot serialize ${typeof value}`);
-  }
-
-  if (value === null) return { type: "null" };
-  if (value instanceof ElementHandle) {
-    return value.handle === undefined
-      ? { sharedId: value.sharedId }
-      : { sharedId: value.sharedId, handle: value.handle };
-  }
-  if (value instanceof Date) return { type: "date", value: value.toISOString() };
-  if (value instanceof RegExp) {
-    return { type: "regexp", value: { pattern: value.source, flags: value.flags } };
-  }
-
-  const object = value as object;
-  if (ancestors.has(object)) throw new TypeError("cannot serialize a circular structure");
-  ancestors.add(object);
-  try {
-    const next = (item: unknown) => serialize(item, ancestors, depth + 1);
-    if (Array.isArray(object)) return { type: "array", value: object.map(next) };
-    if (object instanceof Set) return { type: "set", value: [...object].map(next) };
-    if (object instanceof Map) {
-      return {
-        type: "map",
-        value: [...object].map(([key, item]) => [
-          typeof key === "string" ? key : next(key),
-          next(item),
-        ]),
-      };
-    }
-    const prototype = Object.getPrototypeOf(object);
-    if (prototype !== Object.prototype && prototype !== null) {
-      throw new TypeError(`cannot serialize ${prototype.constructor?.name ?? "object"}`);
-    }
-    return {
-      type: "object",
-      value: Object.entries(object).map(([key, item]) => [key, next(item)]),
-    };
-  } finally {
-    ancestors.delete(object);
-  }
-}
-
-function numberValue(value: number): number | string {
-  if (Number.isNaN(value)) return "NaN";
-  if (value === Infinity) return "Infinity";
-  if (value === -Infinity) return "-Infinity";
-  if (Object.is(value, -0)) return "-0";
-  return value;
-}
-
-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 function fromRemoteValue(value: RemoteValue, options: DeserializeOptions = {}): unknown {
-  return deserialize(value, new Map(), options);
-}
-
-function deserialize(
-  value: RemoteValue,
-  known: Map<string, unknown>,
-  options: DeserializeOptions,
-): unknown {
-  const loose = value as RemoteValue & {
-    value?: unknown;
-    handle?: string;
-    internalId?: string;
-    sharedId?: string;
-  };
-
-  switch (value.type) {
-    case "undefined":
-      return undefined;
-    case "null":
-      return null;
-    case "string":
-    case "boolean":
-      return value.value;
-    case "number":
-      return specialNumber(value.value);
-    case "bigint":
-      return BigInt(value.value);
-    case "date":
-      return new Date(value.value);
-    case "regexp": {
-      const { pattern, flags } = loose.value as { pattern: string; flags?: string };
-      return new RegExp(pattern, flags);
-    }
-    case "node":
-      return new ElementHandle(loose.sharedId ?? "", loose.handle);
-  }
-
-  const nested = (item: RemoteValue) => deserialize(item, known, options);
-  const remember = <T>(result: T): T => {
-    if (loose.internalId !== undefined) known.set(loose.internalId, result);
-    return result;
-  };
-  const backReference = () =>
-    loose.internalId !== undefined && known.has(loose.internalId)
-      ? { found: true as const, value: known.get(loose.internalId) }
-      : undefined;
-
-  let result: unknown;
-  switch (value.type) {
-    case "array":
-    case "set":
-    case "object":
-    case "map": {
-      const reference = backReference();
-      if (reference && loose.value === undefined) return reference.value;
-      if (loose.value === undefined) break; // cut off by the serialization depth
-      if (value.type === "array") {
-        const list: unknown[] = remember([]);
-        (loose.value as RemoteValue[]).forEach((item) => list.push(nested(item)));
-        result = list;
-      } else if (value.type === "set") {
-        const set = remember(new Set<unknown>());
-        (loose.value as RemoteValue[]).forEach((item) => set.add(nested(item)));
-        result = set;
-      } else {
-        const entries = loose.value as Array<[RemoteValue | string, RemoteValue]>;
-        const key = (raw: RemoteValue | string) =>
-          typeof raw === "string" ? raw : nested(raw);
-        if (value.type === "map") {
-          const map = remember(new Map<unknown, unknown>());
-          entries.forEach(([k, item]) => map.set(key(k), nested(item)));
-          result = map;
-        } else {
-          const object: Record<string, unknown> = remember({});
-          entries.forEach(([k, item]) => {
-            object[String(key(k))] = nested(item);
-          });
-          result = object;
-        }
-      }
-      return options.keepHandles && loose.handle !== undefined
-        ? new RemoteObject(value.type, loose.handle, result)
-        : result;
-    }
-  }
-  return new RemoteObject(value.type, loose.handle);
-}
-
-function specialNumber(value: number | string): number {
-  switch (value) {
-    case "NaN":
-      return NaN;
-    case "Infinity":
-      return Infinity;
-    case "-Infinity":
-      return -Infinity;
-    case "-0":
-      return -0;
-    default:
-      return Number(value);
-  }
-}

package/src/testing/browser-fixture.ts

@@ -1,18 +0,0 @@
-import type Page from "../browser/page.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-
-/**
- * Test-only: replaces the page body with `html`, then runs `setup` (JavaScript source,
- * wrapped in its own function scope) in the page. Reaches into Page's private fields.
- */
-export async function setContent(page: Page, html: string, setup = "") {
-  const internals = page as unknown as { biDiConnector: BiDiConnector; contextId: string };
-  const result = await internals.biDiConnector.send("script.evaluate", {
-    expression: `document.body.innerHTML = ${JSON.stringify(html)}; (() => { ${setup} })();`,
-    awaitPromise: false,
-    target: { context: internals.contextId },
-  });
-  if (result.type === "exception") {
-    throw new Error(`setContent failed: ${result.exceptionDetails.text}`);
-  }
-}

package/src/testing/fake-websocket.ts

@@ -1,72 +0,0 @@
-/**
- * Minimal WebSocket stand-in for BiDiConnector unit tests. Commands the connector sends are
- * recorded in `sent`; tests answer them with `reply` and push events with `emitEvent`.
- */
-export class FakeWebSocket extends EventTarget {
-  /** Every command the connector sent, parsed */
-  public readonly sent: Array<{ id: number; method: string; params?: unknown }> = [];
-  public closed = false;
-
-  send(data: string) {
-    this.sent.push(JSON.parse(data));
-  }
-
-  close() {
-    this.closed = true;
-  }
-
-  private receive(message: object) {
-    this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify(message) }));
-  }
-
-  reply(id: number, result: object = {}) {
-    this.receive({ type: "success", id, result });
-  }
-
-  replyError(id: number | null, error: string, message = "boom", stacktrace?: string) {
-    this.receive({ type: "error", id, error, message, stacktrace });
-  }
-
-  emitEvent(method: string, params: object) {
-    this.receive({ type: "event", method, params });
-  }
-
-  /** Simulates the socket closing */
-  drop() {
-    this.dispatchEvent(new Event("close"));
-  }
-}
-
-/** Waits one macrotask so the connector's promise callbacks and timers have run */
-export function tick(ms = 0) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Answers every command the connector sends. `handlers` maps a method to its result;
- * unknown methods get `{}`; `session.subscribe` gets a fresh subscription id unless a handler answers it.
- * A handler that returns an Error with a `code` property answers with that BiDi error code.
- */
-export function autoReply(
-  ws: FakeWebSocket,
-  handlers: Record<string, (params: any) => object | Error> = {},
-) {
-  let answered = 0;
-  let subscriptions = 0;
-  const pump = setInterval(() => {
-    while (answered < ws.sent.length) {
-      const { id, method, params } = ws.sent[answered++]!;
-      const handler = handlers[method];
-      if (method === "session.subscribe" && !handler) {
-        ws.reply(id, { subscription: `sub-${++subscriptions}` });
-        continue;
-      }
-      const result = handler?.(params) ?? {};
-      // An Error with a `code` answers with that BiDi error code
-      if (result instanceof Error) ws.replyError(id, (result as { code?: string }).code ?? "unknown error", result.message);
-      else if (method === "session.subscribe") ws.reply(id, { subscription: `sub-${++subscriptions}`, ...result });
-      else ws.reply(id, result);
-    }
-  }, 1).unref();
-  return () => clearInterval(pump);
-}

package/src/testing/stub-connector.ts

@@ -1,154 +0,0 @@
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { BiDiError } from "../transport/bidi-error.js";
-import type { ErrorCode } from "../types/bidi-protocols/error.js";
-import type { RemoteValue } from "../types/bidi-modules/script.js";
-
-/** `{ error }` rejects the command like a BiDi error reply (e.g. "no such node") */
-export type StubResponse =
-  | RemoteValue
-  | { exception: string }
-  | { hang: true }
-  | { error: ErrorCode };
-
-/** Converts plain JS (JSON-like) to the RemoteValue the browser would answer with */
-export function remote(value: unknown): RemoteValue {
-  if (value === undefined) return { type: "undefined" };
-  if (value === null) return { type: "null" };
-  if (typeof value === "string") return { type: "string", value };
-  if (typeof value === "number") return { type: "number", value };
-  if (typeof value === "boolean") return { type: "boolean", value };
-  if (Array.isArray(value)) return { type: "array", value: value.map(remote) };
-  return {
-    type: "object",
-    value: Object.entries(value as object).map(([key, item]) => [key, remote(item)]),
-  };
-}
-
-/** Plain JS for a serialized argument, so tests can assert on what the page function received */
-function decodeArgument(argument: any): unknown {
-  if (argument.sharedId !== undefined) return { sharedId: argument.sharedId };
-  switch (argument.type) {
-    case "undefined":
-      return undefined;
-    case "null":
-      return null;
-    case "array":
-      return argument.value.map(decodeArgument);
-    case "object":
-      return Object.fromEntries(
-        argument.value.map(([key, item]: [string, unknown]) => [key, decodeArgument(item)]),
-      );
-    default:
-      return argument.value;
-  }
-}
-
-/** A `script.callFunction` the stub received */
-export interface StubCall {
-  functionDeclaration: string;
-  /** Arguments decoded to plain JS */
-  args: unknown[];
-}
-
-/**
- * Fake BiDiConnector for unit tests. Every `script.evaluate` and `script.callFunction` answers
- * with the next queued response; the last response repeats. `{ hang: true }` never answers.
- * `input.performActions`, `input.setFiles` and `browsingContext.navigate` resolve empty. Sent commands are recorded.
- * `browsingContext.locateNodes` answers with as many nodes as the next queued count (see `nodeCounts`;
- * default: always one), capped by `maxNodeCount`, named `stub-node-<n>`.
- * `expressions` holds one entry per script call: the expression, or the function declaration
- * followed by its arguments as a JSON comment, so tests can match on either.
- */
-export function stubConnector(...responses: StubResponse[]) {
-  if (responses.length === 0) {
-    throw new Error("stubConnector needs at least one response");
-  }
-  const expressions: string[] = [];
-  /** Every `script.callFunction`, in order */
-  const calls: StubCall[] = [];
-  /** Every command sent, in order */
-  const sent: Array<{ method: string; params: unknown }> = [];
-  let scriptCalls = 0;
-  let counts: number[] = [1];
-  let locateCalls = 0;
-  let locateFailure: Error | undefined;
-  const unsupported = new Set<string>();
-  const failures = new Map<string, Error>();
-
-  const connector = {
-    async send(method: string, params: any) {
-      sent.push({ method, params });
-      const failure = failures.get(method);
-      if (failure) throw failure;
-      if (method === "browsingContext.locateNodes") {
-        if (locateFailure) throw locateFailure;
-        if (unsupported.has(params.locator.type)) {
-          throw new BiDiError(method, "unsupported operation", `${params.locator.type} is not supported`);
-        }
-        const available = counts[Math.min(locateCalls++, counts.length - 1)]!;
-        const length = Math.min(available, params.maxNodeCount ?? Infinity);
-        return {
-          nodes: Array.from({ length }, (_, index) => ({
-            type: "node",
-            sharedId: `stub-node-${index}`,
-          })),
-        };
-      }
-      if (
-        method === "input.performActions" ||
-        method === "input.setFiles" ||
-        method === "browsingContext.navigate"
-      ) {
-        return {};
-      }
-      if (method === "script.evaluate") {
-        expressions.push(params.expression);
-      } else if (method === "script.callFunction") {
-        const args = (params.arguments ?? []).map(decodeArgument);
-        calls.push({ functionDeclaration: params.functionDeclaration, args });
-        expressions.push(`${params.functionDeclaration}\n/* args: ${JSON.stringify(args)} */`);
-      } else {
-        throw new Error(`stubConnector does not handle ${method}`);
-      }
-      const response = responses[Math.min(scriptCalls++, responses.length - 1)]!;
-      if ("hang" in response) {
-        return new Promise(() => {});
-      }
-      if ("error" in response) {
-        throw new BiDiError(method, response.error, "stub error");
-      }
-      if ("exception" in response) {
-        return {
-          type: "exception",
-          exceptionDetails: { text: response.exception },
-          realm: "stub",
-        };
-      }
-      return { type: "success", result: response, realm: "stub" };
-    },
-  };
-
-  return {
-    connector: connector as unknown as BiDiConnector,
-    expressions,
-    calls,
-    sent,
-    /** Queues how many nodes each `browsingContext.locateNodes` finds; the last count repeats. Restarts the queue */
-    nodeCounts(...queue: number[]) {
-      counts = queue.length > 0 ? queue : [1];
-      locateCalls = 0;
-    },
-    /** Makes `browsingContext.locateNodes` answer "unsupported operation" for these locator types (e.g. "innerText") */
-    unsupportedLocators(...types: string[]) {
-      types.forEach((type) => unsupported.add(type));
-    },
-    /** Makes every `browsingContext.locateNodes` reject with `error` */
-    failLocate(error: Error) {
-      locateFailure = error;
-    },
-    /** Makes every send of `method` reject with `error` */
-    failCommand(method: string, error: Error) {
-      failures.set(method, error);
-    },
-  };
-}

package/src/tests/index.spec.ts

@@ -1,30 +0,0 @@
-import { expect, test } from "../api.js";
-
-test("My first test", async ({ page }) => {
-  await page.goto("https://itmetsam.nl");
-  const link = page.locator("a[text()='Start een project']");
-  await link.click();
-  await page.waitForNetworkIdle();
-  const nameField = page.locator("input[@id='contact-name']");
-  await nameField.fill("test");
-  const emailField = page.locator("input[@id='contact-email']");
-  await emailField.fill("sammiedegroot@gmail.com");
-  const subjectField = page.locator("input[@id='contact-subject']");
-  await subjectField.fill("Test subject");
-  const messageField = page.locator("textarea[@id='contact-message']");
-  await messageField.fill(
-    "This is a very long message which describes what I would like",
-  );
-  await expect(nameField).toBeVisible();
-  await expect(nameField).toHaveValue("test");
-  await expect(emailField).toHaveValue("sammiedegroot@gmail.com");
-  await expect(subjectField).toHaveValue("Test subject");
-  await expect(messageField).toHaveValue(/very long message/);
-
-  const submitButton = page.locator("button[@type='submit']");
-  await submitButton.click();
-  const successAlert = page.locator("div[@class='alert-description']");
-  await expect(successAlert).toContainText(
-    "Je aanvraag is ontvangen! Je ontvangt automatisch een kopie van de aanvraag op het opgegeven E-mailadres. Ik neem binnen 3 werkdagen contact met je op over je aanvraag.",
-  );
-});

package/src/transport/bidi-connection.test.ts

@@ -1,155 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { FakeWebSocket, tick } from "../testing/fake-websocket.js";
-import { WaitTimeoutError } from "../wait/wait-until.js";
-import { BiDiError } from "./bidi-error.js";
-import { BiDiConnector } from "./bidi-connection.js";
-
-function setup(options?: { commandTimeout?: number }) {
-  const ws = new FakeWebSocket();
-  const connector = new BiDiConnector(ws as unknown as WebSocket, options);
-  return { ws, connector };
-}
-
-describe("BiDiConnector error replies", () => {
-  it("rejects only the matching command with a BiDiError", async () => {
-    const { ws, connector } = setup();
-    const first = connector.send("session.status", {});
-    const second = connector.send("browser.close", {});
-    ws.replyError(0, "no such frame", "frame is gone", "stack…");
-    await assert.rejects(first, (err: unknown) => {
-      assert.ok(err instanceof BiDiError);
-      assert.equal(err.code, "no such frame");
-      assert.equal(err.command, "session.status");
-      assert.equal(err.remoteStack, "stack…");
-      assert.match(err.message, /frame is gone/);
-      return true;
-    });
-    ws.reply(1);
-    assert.deepEqual(await second, {});
-  });
-
-  it("ignores an error reply for an unknown or null id", async () => {
-    const { ws, connector } = setup();
-    ws.replyError(99, "unknown error");
-    ws.replyError(null, "invalid session id");
-    const pending = connector.send("session.status", {});
-    ws.reply(0, { ready: true });
-    assert.deepEqual(await pending, { ready: true });
-  });
-});
-
-describe("BiDiConnector timeouts", () => {
-  it("rejects with code timeout and ignores a late reply", async () => {
-    const { ws, connector } = setup();
-    const pending = connector.send("session.status", {}, { timeout: 20 });
-    await assert.rejects(pending, (err: unknown) => {
-      assert.ok(err instanceof BiDiError);
-      assert.equal(err.code, "timeout");
-      assert.equal(err.command, "session.status");
-      return true;
-    });
-    assert.doesNotThrow(() => ws.reply(0));
-  });
-
-  it("uses the constructor commandTimeout by default", async () => {
-    const { connector } = setup({ commandTimeout: 15 });
-    await assert.rejects(connector.send("session.status", {}), { code: "timeout" });
-  });
-
-  it("does not leave a timer running after a reply", async () => {
-    const { ws, connector } = setup({ commandTimeout: 30 });
-    const pending = connector.send("session.status", {});
-    ws.reply(0);
-    await pending;
-    await tick(60); // an uncleared timer would try to reject a settled command: harmless, but must not throw
-  });
-});
-
-describe("BiDiConnector socket close", () => {
-  it("rejects pending commands and names them", async () => {
-    const { ws, connector } = setup();
-    const pending = connector.send("script.evaluate", {} as never);
-    ws.drop();
-    await assert.rejects(pending, /Websocket closed.*script\.evaluate/);
-  });
-});
-
-describe("BiDiConnector.waitForEvent", () => {
-  it("resolves with the params of the first matching event and removes its listener", async () => {
-    const { ws, connector } = setup();
-    const waiting = connector.waitForEvent(
-      "browsingContext.load",
-      (p) => p.context === "b",
-      { timeout: 1000 },
-    );
-    ws.emitEvent("browsingContext.load", { context: "a" });
-    ws.emitEvent("browsingContext.load", { context: "b", url: "x" });
-    assert.deepEqual(await waiting, { context: "b", url: "x" });
-    // listener gone: further events do not throw or leak
-    ws.emitEvent("browsingContext.load", { context: "b" });
-  });
-
-  it("is registered before it returns, so an event emitted right after is seen", async () => {
-    const { ws, connector } = setup();
-    const waiting = connector.waitForEvent("browsingContext.load", () => true, { timeout: 1000 });
-    ws.emitEvent("browsingContext.load", { context: "a" });
-    assert.deepEqual(await waiting, { context: "a" });
-  });
-
-  it("rejects with WaitTimeoutError on timeout", async () => {
-    const { connector } = setup();
-    await assert.rejects(
-      connector.waitForEvent("browsingContext.load", () => true, { timeout: 15 }),
-      (err: unknown) => err instanceof WaitTimeoutError && err.timeout === 15,
-    );
-  });
-
-  it("rejects with the abort reason and stops listening", async () => {
-    const { ws, connector } = setup();
-    const controller = new AbortController();
-    const waiting = connector.waitForEvent("browsingContext.load", () => true, {
-      timeout: 1000,
-      signal: controller.signal,
-    });
-    controller.abort(new Error("stop"));
-    await assert.rejects(waiting, /stop/);
-    ws.emitEvent("browsingContext.load", { context: "a" });
-  });
-
-  it("rejects immediately when the signal is already aborted", async () => {
-    const { connector } = setup();
-    const signal = AbortSignal.abort(new Error("already"));
-    await assert.rejects(
-      connector.waitForEvent("browsingContext.load", () => true, { timeout: 1000, signal }),
-      /already/,
-    );
-  });
-});
-
-describe("BiDiConnector.subscribe", () => {
-  it("sends session.subscribe once for two subscribers and unsubscribes after both leave", async () => {
-    const { ws, connector } = setup();
-    const answer = async () => {
-      await tick();
-      const last = ws.sent[ws.sent.length - 1]!;
-      ws.reply(last.id, last.method === "session.subscribe" ? { subscription: "s1" } : {});
-    };
-
-    const a = connector.subscribe(["browsingContext.load"]);
-    await answer();
-    const subA = await a;
-    const subB = await connector.subscribe(["browsingContext.load"]);
-    assert.equal(ws.sent.filter((m) => m.method === "session.subscribe").length, 1);
-
-    await subA.unsubscribe();
-    assert.equal(ws.sent.filter((m) => m.method === "session.unsubscribe").length, 0);
-
-    const leaving = subB.unsubscribe();
-    await answer();
-    await leaving;
-    const unsub = ws.sent.filter((m) => m.method === "session.unsubscribe");
-    assert.equal(unsub.length, 1);
-    assert.deepEqual(unsub[0]!.params, { subscriptions: ["s1"] });
-  });
-});