@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/script/call-function.browser-test.ts

@@ -1,112 +0,0 @@
-import assert from "node:assert/strict";
-import { after, before, test } from "node:test";
-import { Browser } from "../browser/browser.js";
-import type Page from "../browser/page.js";
-import { setContent } from "../testing/browser-fixture.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { BiDiError } from "../transport/bidi-error.js";
-import { callFunction, disown, ScriptError } from "./call-function.js";
-import { ElementHandle } from "./element-handle.js";
-import { RemoteObject } from "./serialize.js";
-
-let browser: Browser;
-let page: Page;
-let connector: BiDiConnector;
-
-before(async () => {
-  ({ browser, page } = await Browser.launch("firefox", { port: 9233, headless: true }));
-  connector = (page as unknown as { biDiConnector: BiDiConnector }).biDiConnector;
-  await page.navigateTo("about:blank", "complete");
-});
-
-after(async () => {
-  await browser?.close();
-});
-
-const OPTIONS = { timeout: 15000 };
-const call = <T>(fn: string | ((...args: any[]) => unknown), args: unknown[] = [], options = {}) =>
-  callFunction<T>(connector, page.contextId, fn, args, options);
-
-test("plain values, Map, Set, Date and RegExp round trip", OPTIONS, async () => {
-  const input = {
-    text: `quote " apostrophe ' backslash \\ newline \n`,
-    numbers: [1, -0, NaN, Infinity],
-    map: new Map<unknown, unknown>([["k", 1]]),
-    set: new Set([1, 2]),
-    date: new Date("2026-09-29T10:00:00.000Z"),
-    pattern: /a+b/gi,
-    big: 12345678901234567890n,
-    nothing: null,
-    missing: undefined,
-  };
-  const output = await call<typeof input>("(value) => value", [input]);
-  assert.equal(output.text, input.text);
-  assert.ok(Object.is(output.numbers[1], -0));
-  assert.ok(Number.isNaN(output.numbers[2]));
-  assert.equal(output.numbers[3], Infinity);
-  assert.deepEqual([...output.map], [["k", 1]]);
-  assert.deepEqual([...output.set], [1, 2]);
-  assert.equal(output.date.toISOString(), input.date.toISOString());
-  assert.equal(output.pattern.source, "a+b");
-  assert.equal(output.pattern.flags, "gi");
-  assert.equal(output.big, input.big);
-  assert.equal(output.nothing, null);
-  assert.equal(output.missing, undefined);
-});
-
-test("an xpath with every quote style and a newline is located without escaping", OPTIONS, async () => {
-  await setContent(page, `<a id="x">Don't "stop"</a>`);
-  const xpath = `//a[@id="x" and contains(., "Don't")]\n`;
-  const link = page.locator(xpath);
-  assert.equal(await link.count(), 1);
-  assert.equal(await link.textContent(), `Don't "stop"`);
-});
-
-test("awaitPromise resolves async functions", OPTIONS, async () => {
-  assert.equal(await call("async () => { await new Promise((r) => setTimeout(r, 50)); return 7; }"), 7);
-});
-
-test("a function object is sent as its source", OPTIONS, async () => {
-  assert.equal(await call((a: number, b: number) => a + b, [2, 3]), 5);
-});
-
-test("a throwing function becomes a ScriptError", OPTIONS, async () => {
-  await assert.rejects(call(`() => { null.x; }`), (err: unknown) => {
-    assert.ok(err instanceof ScriptError);
-    assert.match(err.text, /TypeError/);
-    return true;
-  });
-});
-
-test("nodes come back as ElementHandles and can be passed in again", OPTIONS, async () => {
-  await setContent(page, `<p id="p">hello</p>`);
-  const handle = await call<ElementHandle>(`() => document.getElementById("p")`);
-  assert.ok(handle instanceof ElementHandle);
-  assert.equal(await call<string>(`(el) => el.textContent`, [handle]), "hello");
-});
-
-test("a removed node stays usable, a node from a previous document fails with no such node", OPTIONS, async () => {
-  await setContent(page, `<p id="p">hello</p>`);
-  const handle = await call<ElementHandle>(`() => document.getElementById("p")`);
-  await call(`() => document.getElementById("p").remove()`);
-  // Detached but alive: the browser still resolves the reference
-  assert.equal(await call<string>(`(el) => el.textContent`, [handle]), "hello");
-  await page.navigateTo("about:blank?next", "complete");
-  await assert.rejects(
-    call(`(el) => el.textContent`, [handle]),
-    (err: unknown) => err instanceof BiDiError && err.code === "no such node",
-  );
-});
-
-test("ownership root keeps a handle that disown releases, twice without error", OPTIONS, async () => {
-  const kept = await call<RemoteObject>(`() => ({ a: 1 })`, [], { ownership: "root" });
-  assert.ok(kept instanceof RemoteObject);
-  assert.ok(kept.handle);
-  assert.deepEqual(kept.value, { a: 1 });
-  await disown(connector, page.contextId, [kept.handle!]);
-  await assert.doesNotReject(disown(connector, page.contextId, [kept.handle!]));
-});
-
-test("unserializable arguments fail before anything is sent", OPTIONS, async () => {
-  await assert.rejects(call(`(f) => f`, [() => 1]), TypeError);
-});

package/src/script/call-function.test.ts

@@ -1,174 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { FakeWebSocket, tick } from "../testing/fake-websocket.js";
-import { BiDiConnector } from "../transport/bidi-connection.js";
-import { callFunction, disown, ScriptError, ScriptSerializationError } from "./call-function.js";
-import { ElementHandle } from "./element-handle.js";
-import { RemoteObject } from "./serialize.js";
-
-function setup(reply: (params: any) => object | Error) {
-  const ws = new FakeWebSocket();
-  const connector = new BiDiConnector(ws as unknown as WebSocket);
-  let answered = 0;
-  const pump = setInterval(() => {
-    while (answered < ws.sent.length) {
-      const { id, method, params } = ws.sent[answered++]!;
-      const result = method === "script.callFunction" || method === "script.disown" ? reply(params) : {};
-      if (result instanceof Error) ws.replyError(id, "no such handle", result.message);
-      else ws.reply(id, result);
-    }
-  }, 1);
-  return { ws, connector, stop: () => clearInterval(pump) };
-}
-
-const success = (result: object) => ({ type: "success", realm: "r", result });
-
-describe("callFunction", () => {
-  it("sends the declaration, serialized arguments, target and defaults", async () => {
-    const { ws, connector, stop } = setup(() => success({ type: "number", value: 3 }));
-    const result = await callFunction(connector, "ctx", "(a, b) => a + b", [1, "x"]);
-    assert.equal(result, 3);
-    assert.deepEqual(ws.sent[0]!.params, {
-      functionDeclaration: "(a, b) => a + b",
-      awaitPromise: true,
-      target: { context: "ctx" },
-      arguments: [
-        { type: "number", value: 1 },
-        { type: "string", value: "x" },
-      ],
-      resultOwnership: "none",
-    });
-    stop();
-  });
-
-  it("omits arguments when there are none and passes options through", async () => {
-    const { ws, connector, stop } = setup(() => success({ type: "undefined" }));
-    await callFunction(connector, "ctx", "function() { return this; }", [], {
-      awaitPromise: false,
-      sandbox: "samurai",
-      ownership: "root",
-      thisArg: { a: 1 },
-    });
-    assert.deepEqual(ws.sent[0]!.params, {
-      functionDeclaration: "function() { return this; }",
-      awaitPromise: false,
-      target: { context: "ctx", sandbox: "samurai" },
-      resultOwnership: "root",
-      this: { type: "object", value: [["a", { type: "number", value: 1 }]] },
-    });
-    stop();
-  });
-
-  it("serializes an ElementHandle argument as a shared reference", async () => {
-    const { ws, connector, stop } = setup(() => success({ type: "null" }));
-    await callFunction(connector, "ctx", "(el) => el.id", [new ElementHandle("n1")]);
-    assert.deepEqual((ws.sent[0]!.params as any).arguments, [{ sharedId: "n1" }]);
-    stop();
-  });
-
-  it("accepts a function and sends its source", async () => {
-    const { ws, connector, stop } = setup(() => success({ type: "number", value: 2 }));
-    await callFunction(connector, "ctx", (n: number) => n * 2, [1]);
-    assert.match((ws.sent[0]!.params as any).functionDeclaration, /n\s*\*\s*2/);
-    stop();
-  });
-
-  it("rejects a function whose source depends on the transpiler's __name helper", async () => {
-    const { connector, stop } = setup(() => success({ type: "null" }));
-    const named = () => {
-      function inner() {
-        return 1;
-      }
-      return inner();
-    };
-    // Under tsx (keepNames) `inner` is wrapped in __name(); the guard turns that into a clear error
-    if (named.toString().includes("__name(")) {
-      await assert.rejects(callFunction(connector, "ctx", named), ScriptSerializationError);
-    }
-    const guarded = "(x) => { __name(x, 'x'); }";
-    // A string is used as written, the guard is only for function objects
-    await assert.doesNotReject(callFunction(connector, "ctx", guarded));
-    const fake = Object.assign(() => 1, { toString: () => "() => { __name(a, 'a'); }" });
-    await assert.rejects(callFunction(connector, "ctx", fake), ScriptSerializationError);
-    stop();
-  });
-
-  it("fails before sending when an argument cannot be serialized", async () => {
-    const { ws, connector, stop } = setup(() => success({ type: "null" }));
-    await assert.rejects(callFunction(connector, "ctx", "(f) => f", [() => 1]), TypeError);
-    assert.equal(ws.sent.length, 0);
-    stop();
-  });
-
-  it("maps an exception result to ScriptError", async () => {
-    const { connector, stop } = setup(() => ({
-      type: "exception",
-      realm: "r",
-      exceptionDetails: {
-        text: "TypeError: x is null",
-        lineNumber: 1,
-        columnNumber: 2,
-        exception: { type: "error" },
-        stackTrace: { callFrames: [] },
-      },
-    }));
-    const longSource = "() => {" + " ".repeat(300) + "}";
-    await assert.rejects(callFunction(connector, "ctx", longSource), (err: unknown) => {
-      assert.ok(err instanceof ScriptError);
-      assert.equal(err.text, "TypeError: x is null");
-      assert.deepEqual(err.stackTrace, { callFrames: [] });
-      assert.ok(err.functionSource.length <= 201);
-      assert.match(err.message, /TypeError: x is null/);
-      return true;
-    });
-    stop();
-  });
-
-  it("returns nodes as ElementHandles", async () => {
-    const { connector, stop } = setup(() => success({ type: "node", sharedId: "n9", value: {} }));
-    const result = await callFunction<ElementHandle>(connector, "ctx", "() => document.body");
-    assert.ok(result instanceof ElementHandle);
-    assert.equal(result.sharedId, "n9");
-    stop();
-  });
-
-  it("keeps handles for ownership root", async () => {
-    const { connector, stop } = setup(() =>
-      success({ type: "object", handle: "h1", value: [["a", { type: "number", value: 1 }]] }),
-    );
-    const result = await callFunction<RemoteObject>(connector, "ctx", "() => ({a: 1})", [], { ownership: "root" });
-    assert.ok(result instanceof RemoteObject);
-    assert.equal(result.handle, "h1");
-    assert.deepEqual(result.value, { a: 1 });
-    stop();
-  });
-
-  it("does not keep handles for ownership none", async () => {
-    const { connector, stop } = setup(() => success({ type: "object", value: [["a", { type: "number", value: 1 }]] }));
-    assert.deepEqual(await callFunction(connector, "ctx", "() => ({a: 1})"), { a: 1 });
-    stop();
-  });
-});
-
-describe("disown", () => {
-  it("sends the handles for the context", async () => {
-    const { ws, connector, stop } = setup(() => ({}));
-    await disown(connector, "ctx", ["h1", "h2"]);
-    assert.deepEqual(ws.sent[0]!.params, { handles: ["h1", "h2"], target: { context: "ctx" } });
-    stop();
-  });
-
-  it("sends nothing for no handles", async () => {
-    const { ws, connector, stop } = setup(() => ({}));
-    await disown(connector, "ctx", []);
-    await tick(5);
-    assert.equal(ws.sent.length, 0);
-    stop();
-  });
-
-  it("swallows no such handle", async () => {
-    const { connector, stop } = setup(() => new Error("gone"));
-    await assert.doesNotReject(disown(connector, "ctx", ["h1"]));
-    stop();
-  });
-});

package/src/script/call-function.ts

@@ -1,113 +0,0 @@
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { BiDiError } from "../transport/bidi-error.js";
-import type { StackTrace } from "../types/bidi-modules/script.js";
-import { fromRemoteValue, toLocalValue, type Arg } from "./serialize.js";
-
-/** How much of a function's source `ScriptError` keeps */
-const SOURCE_PREVIEW = 200;
-
-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 class ScriptError extends Error {
-  /** The browser's description, e.g. "TypeError: el is null" */
-  public readonly text: string;
-  public readonly stackTrace: StackTrace | undefined;
-  /** Start of the function that threw */
-  public readonly functionSource: string;
-
-  constructor(text: string, functionSource: string, stackTrace?: 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: string) {
-    super(message);
-    this.name = "ScriptSerializationError";
-  }
-}
-
-/** The source to send for `fn`; a function object must not depend on transpiler helpers */
-export function toFunctionDeclaration(fn: string | ((...args: any[]) => unknown)): string {
-  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<T = unknown>(
-  connector: BiDiConnector,
-  context: string,
-  fn: string | ((...args: any[]) => unknown),
-  args: Arg[] = [],
-  options: CallOptions = {},
-): Promise<T> {
-  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" }) as T;
-}
-
-/** Releases handles obtained with `ownership: "root"`; a handle that is already gone is fine */
-export async function disown(
-  connector: BiDiConnector,
-  context: string,
-  handles: string[],
-): Promise<void> {
-  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/src/script/helpers.test.ts

@@ -1,116 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { autoReply, FakeWebSocket, tick } from "../testing/fake-websocket.js";
-import { BiDiConnector } from "../transport/bidi-connection.js";
-import {
-  CALL_PROBE,
-  HELPER_SANDBOX,
-  HELPERS_MISSING,
-  HELPERS_SOURCE,
-  HelperRealm,
-} from "./helpers.js";
-
-const ok = { type: "success", realm: "r", result: { type: "undefined" } };
-
-function setup(overrides: Record<string, (params: any) => object | Error> = {}) {
-  const ws = new FakeWebSocket();
-  const connector = new BiDiConnector(ws as unknown as WebSocket);
-  const stop = autoReply(ws, {
-    "script.addPreloadScript": () => ({ script: "helpers-1" }),
-    "browsingContext.getTree": () => ({ contexts: [{ context: "top", parent: null, children: [] }] }),
-    "script.callFunction": () => ok,
-    ...overrides,
-  });
-  const count = (method: string) => ws.sent.filter((m) => m.method === method).length;
-  return { ws, connector, stop, count, realm: new HelperRealm(connector, "top") };
-}
-
-describe("helper source", () => {
-  it("compiles and installs probeElement on the global", () => {
-    const fakeGlobal: Record<string, any> = {};
-    new Function("globalThis", `(${HELPERS_SOURCE})()`)(fakeGlobal);
-    assert.equal(typeof fakeGlobal.__samurai.probeElement, "function");
-  });
-
-  it("the call wrapper forwards to probeElement, or answers with the missing marker", () => {
-    const wrapper = (globalScope: object) =>
-      new Function("globalThis", `return (${CALL_PROBE})`)(globalScope) as (...args: unknown[]) => unknown;
-    const probeElement = (xpath: string, options: unknown) => ({ xpath, options });
-    assert.deepEqual(wrapper({ __samurai: { probeElement } })("//a", { scroll: true }), {
-      xpath: "//a",
-      options: { scroll: true },
-    });
-    assert.equal(wrapper({})("//a", {}), HELPERS_MISSING);
-  });
-
-  it("uses the samurai sandbox", () => {
-    assert.equal(HELPER_SANDBOX, "samurai");
-  });
-});
-
-describe("HelperRealm", () => {
-  it("registers once for the page context and runs in the sandbox", async () => {
-    const { ws, realm, stop } = setup();
-    await realm.ensureInstalled();
-    assert.deepEqual(ws.sent[0]!.params, {
-      functionDeclaration: HELPERS_SOURCE,
-      contexts: ["top"],
-      sandbox: "samurai",
-    });
-    stop();
-  });
-
-  it("concurrent and repeated ensureInstalled share one registration", async () => {
-    const { realm, count, stop } = setup();
-    await Promise.all([realm.ensureInstalled(), realm.ensureInstalled()]);
-    await realm.ensureInstalled();
-    assert.equal(count("script.addPreloadScript"), 1);
-    stop();
-  });
-
-  it("a failed install can be retried", async () => {
-    let attempts = 0;
-    const { realm, count, stop } = setup({
-      "script.addPreloadScript": () => (++attempts === 1 ? new Error("first fails") : { script: "helpers-1" }),
-    });
-    await assert.rejects(realm.ensureInstalled());
-    await realm.ensureInstalled();
-    assert.equal(count("script.addPreloadScript"), 2);
-    stop();
-  });
-
-  it("reinstall runs the helpers in the current contexts without registering again", async () => {
-    const { ws, realm, count, stop } = setup();
-    await realm.ensureInstalled();
-    const before = count("script.addPreloadScript");
-    await realm.reinstall();
-    assert.equal(count("script.addPreloadScript"), before);
-    const last = ws.sent.filter((m) => m.method === "script.callFunction").pop()!.params as any;
-    assert.equal(last.functionDeclaration, HELPERS_SOURCE);
-    assert.deepEqual(last.target, { context: "top", sandbox: "samurai" });
-    stop();
-  });
-
-  it("reinstall before the first install installs first", async () => {
-    const { realm, count, stop } = setup();
-    await realm.reinstall();
-    assert.equal(count("script.addPreloadScript"), 1);
-    stop();
-  });
-
-  it("dispose removes the registration", async () => {
-    const { realm, count, stop } = setup({ "script.removePreloadScript": () => ({}) });
-    await realm.ensureInstalled();
-    await realm.dispose();
-    await tick(5);
-    assert.equal(count("script.removePreloadScript"), 1);
-    stop();
-  });
-
-  it("dispose without an install sends nothing", async () => {
-    const { realm, count, stop } = setup();
-    await realm.dispose();
-    assert.equal(count("script.removePreloadScript"), 0);
-    stop();
-  });
-});

package/src/script/helpers.ts

@@ -1,68 +0,0 @@
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { PROBE_ELEMENT } from "../locator/element-state.js";
-import { addPreload, runInLoadedContexts, type PreloadHandle } 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)};
-}`;
-
-/** 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 class HelperRealm implements HelperInstaller {
-  private installed: Promise<PreloadHandle> | undefined;
-
-  constructor(
-    private connector: BiDiConnector,
-    private contextId: string,
-  ) {}
-
-  public ensureInstalled(): Promise<void> {
-    this.installed ??= addPreload(this.connector, this.options()).catch((err) => {
-      this.installed = undefined;
-      throw err;
-    });
-    return this.installed.then(() => undefined);
-  }
-
-  public async reinstall(): Promise<void> {
-    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 */
-  public async dispose(): Promise<void> {
-    const installed = this.installed;
-    this.installed = undefined;
-    if (!installed) return;
-    await (await installed).dispose();
-  }
-
-  private options() {
-    return {
-      source: HELPERS_SOURCE,
-      contexts: [this.contextId],
-      sandbox: HELPER_SANDBOX,
-    };
-  }
-}