Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

19.4 KB
Raw Blame
import { afterEach, beforeEach, describe, it, mock } from "node:test";
import assert from "node:assert";
import { isRefToken, normalizeActionParams, looksLikeStaleRef, pinchtabFetch, textResult, imageResult, resourceResult, clearPinchtabSessionCache } from "./client.ts";

describe("isRefToken", () => {
  it("returns true for valid ref tokens", () => {
    assert.strictEqual(isRefToken("e5"), true);
    assert.strictEqual(isRefToken("e123"), true);
    assert.strictEqual(isRefToken("E5"), true);
    assert.strictEqual(isRefToken("e0"), true);
  });

  it("returns false for invalid ref tokens", () => {
    assert.strictEqual(isRefToken("e"), false);
    assert.strictEqual(isRefToken("5"), false);
    assert.strictEqual(isRefToken("ref5"), false);
    assert.strictEqual(isRefToken(""), false);
    assert.strictEqual(isRefToken(null), false);
    assert.strictEqual(isRefToken(undefined), false);
    assert.strictEqual(isRefToken(123), false);
  });

  it("handles whitespace", () => {
    assert.strictEqual(isRefToken(" e5 "), true);
    assert.strictEqual(isRefToken("e5\n"), true);
  });
});

describe("normalizeActionParams", () => {
  it("converts ref-like selector to ref", () => {
    const result = normalizeActionParams({ selector: "e5" });
    assert.strictEqual(result.ref, "e5");
    assert.strictEqual(result.selector, undefined);
  });

  it("preserves non-ref selector", () => {
    const result = normalizeActionParams({ selector: "#button" });
    assert.strictEqual(result.selector, "#button");
    assert.strictEqual(result.ref, undefined);
  });

  it("does not override existing ref", () => {
    const result = normalizeActionParams({ ref: "e10", selector: "e5" });
    assert.strictEqual(result.ref, "e10");
    assert.strictEqual(result.selector, "e5");
  });

  it("trims ref whitespace", () => {
    const result = normalizeActionParams({ ref: " e5 " });
    assert.strictEqual(result.ref, "e5");
  });

  it("preserves other params", () => {
    const result = normalizeActionParams({ action: "click", ref: "e5", text: "hello" });
    assert.strictEqual(result.action, "click");
    assert.strictEqual(result.ref, "e5");
    assert.strictEqual(result.text, "hello");
  });
});

describe("looksLikeStaleRef", () => {
  it("returns false for non-error results", () => {
    assert.strictEqual(looksLikeStaleRef({ success: true }), false);
    assert.strictEqual(looksLikeStaleRef(null), false);
    assert.strictEqual(looksLikeStaleRef(undefined), false);
  });

  it("returns true for stale ref errors", () => {
    assert.strictEqual(looksLikeStaleRef({ error: "stale element reference" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "ref not found" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "no node with id" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "unknown element" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "context canceled" }), true);
  });

  it("matches Pinchtab backend-node failures", () => {
    assert.strictEqual(
      looksLikeStaleRef({ error: "element not found in DOM (backendNodeId=42)" }),
      true,
    );
    assert.strictEqual(looksLikeStaleRef({ error: "backend-node-not-found" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "backend node detached" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "element no longer in DOM" }), true);
    assert.strictEqual(looksLikeStaleRef({ error: "element no longer attached" }), true);
  });

  it("returns false for other errors", () => {
    assert.strictEqual(looksLikeStaleRef({ error: "network timeout" }), false);
    assert.strictEqual(looksLikeStaleRef({ error: "server error" }), false);
  });

  it("does not match unrelated substrings containing 'ref'", () => {
    assert.strictEqual(looksLikeStaleRef({ error: "referrer policy violation" }), false);
    assert.strictEqual(looksLikeStaleRef({ error: "unsupported preferences" }), false);
    assert.strictEqual(looksLikeStaleRef({ error: "page not found" }), false);
  });

  it("checks body as well as error", () => {
    assert.strictEqual(looksLikeStaleRef({ error: "failed", body: "stale ref" }), true);
  });
});

describe("pinchtabFetch", () => {
  const originalFetch = globalThis.fetch;

  beforeEach(() => {
    globalThis.fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
      return new Response(JSON.stringify({ headers: init?.headers ?? {} }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      });
    }) as typeof fetch;
  });

  afterEach(() => {
    globalThis.fetch = originalFetch;
  });

  it("forwards OpenClaw agent and session headers", async () => {
    const result = await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "secret" },
      "/health",
      {},
      { agentId: "writer", sessionId: "session-123", sessionKey: "chat:writer" },
    );
    assert.deepStrictEqual(result.headers, {
      Authorization: "Bearer secret",
      "X-OpenClaw-Agent-Id": "writer",
      "X-OpenClaw-Session-Id": "session-123",
    });
  });
});

describe("pinchtabFetch per-agent session token", () => {
  const originalFetch = globalThis.fetch;
  let calls: Array<{ url: string; method: string; headers: Record<string, string>; body?: string }>;

  beforeEach(() => {
    clearPinchtabSessionCache();
    calls = [];
    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
      const url = typeof input === "string" ? input : input.toString();
      const method = (init?.method || "GET").toUpperCase();
      const headers = (init?.headers ?? {}) as Record<string, string>;
      const body = typeof init?.body === "string" ? init.body : undefined;
      calls.push({ url, method, headers, body });
      if (url.endsWith("/sessions") && method === "POST") {
        return new Response(JSON.stringify({ id: "ses_abc", sessionToken: "ses_token_xyz" }), {
          status: 200,
          headers: { "Content-Type": "application/json" },
        });
      }
      return new Response(JSON.stringify({ ok: true, headers }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      });
    }) as typeof fetch;
  });

  afterEach(() => {
    globalThis.fetch = originalFetch;
    clearPinchtabSessionCache();
  });

  it("creates a Pinchtab session lazily and uses its token for browser actions", async () => {
    await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "server-token" },
      "/snapshot",
      {},
      { agentId: "alpha" },
    );
    assert.strictEqual(calls.length, 2);
    assert.strictEqual(calls[0].url, "http://localhost:9867/sessions");
    assert.strictEqual(calls[0].method, "POST");
    assert.strictEqual(calls[0].headers.Authorization, "Bearer server-token");
    assert.deepStrictEqual(JSON.parse(calls[0].body!), { agentId: "alpha", label: "openclaw" });
    assert.strictEqual(calls[1].url, "http://localhost:9867/snapshot");
    assert.strictEqual(calls[1].headers.Authorization, "Session ses_token_xyz");
  });

  it("reuses the cached session token across calls for the same agent", async () => {
    const cfg = { baseUrl: "http://localhost:9867", token: "server-token" };
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "alpha" });
    await pinchtabFetch(cfg, "/tabs", {}, { agentId: "alpha" });
    const sessionPosts = calls.filter((c) => c.url.endsWith("/sessions") && c.method === "POST");
    assert.strictEqual(sessionPosts.length, 1);
    const tabsCall = calls.find((c) => c.url.endsWith("/tabs"));
    assert.strictEqual(tabsCall?.headers.Authorization, "Session ses_token_xyz");
  });

  it("creates separate sessions for distinct agents", async () => {
    const cfg = { baseUrl: "http://localhost:9867", token: "server-token" };
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "alpha" });
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "beta" });
    const sessionPosts = calls.filter((c) => c.url.endsWith("/sessions") && c.method === "POST");
    assert.strictEqual(sessionPosts.length, 2);
    const agentIds = sessionPosts.map((c) => JSON.parse(c.body!).agentId).sort();
    assert.deepStrictEqual(agentIds, ["alpha", "beta"]);
  });

  it("uses the server token for /health, /sessions, /instances, /profiles", async () => {
    const cfg = { baseUrl: "http://localhost:9867", token: "server-token" };
    await pinchtabFetch(cfg, "/health", {}, { agentId: "alpha" });
    await pinchtabFetch(cfg, "/instances", {}, { agentId: "alpha" });
    await pinchtabFetch(cfg, "/profiles", {}, { agentId: "alpha" });
    for (const call of calls) {
      assert.strictEqual(call.headers.Authorization, "Bearer server-token");
    }
  });

  it("falls back to server token when context has no agentId", async () => {
    await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "server-token" },
      "/snapshot",
      {},
    );
    assert.strictEqual(calls.length, 1);
    assert.strictEqual(calls[0].headers.Authorization, "Bearer server-token");
  });
});

describe("pinchtabFetch session failure modes", () => {
  const originalFetch = globalThis.fetch;

  afterEach(() => {
    globalThis.fetch = originalFetch;
    clearPinchtabSessionCache();
  });

  it("fails closed (no bearer fallback) when /sessions creation fails for an agent", async () => {
    clearPinchtabSessionCache();
    const calls: Array<{ url: string; method: string }> = [];
    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
      const url = typeof input === "string" ? input : input.toString();
      const method = (init?.method || "GET").toUpperCase();
      calls.push({ url, method });
      if (url.endsWith("/sessions") && method === "POST") {
        return new Response("upstream timeout", { status: 503 });
      }
      throw new Error("must not fall back to bearer for the snapshot path");
    }) as typeof fetch;

    const result = await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "server-token" },
      "/snapshot",
      {},
      { agentId: "alpha" },
    );
    assert.strictEqual(calls.length, 1);
    assert.strictEqual(calls[0].url, "http://localhost:9867/sessions");
    assert.match(result.error, /Pinchtab session creation failed for agent alpha/);
    assert.match(result.error, /503/);
  });

  it("evicts cached token and retries once on 401 from a Session-scheme call", async () => {
    clearPinchtabSessionCache();
    const calls: Array<{ url: string; method: string; headers: Record<string, string> }> = [];
    let sessionTokenCounter = 0;
    let firstSnapshot = true;
    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
      const url = typeof input === "string" ? input : input.toString();
      const method = (init?.method || "GET").toUpperCase();
      const headers = (init?.headers ?? {}) as Record<string, string>;
      calls.push({ url, method, headers });
      if (url.endsWith("/sessions") && method === "POST") {
        sessionTokenCounter += 1;
        return new Response(
          JSON.stringify({ id: `ses_${sessionTokenCounter}`, sessionToken: `ses_token_${sessionTokenCounter}` }),
          { status: 200, headers: { "Content-Type": "application/json" } },
        );
      }
      if (url.endsWith("/snapshot")) {
        if (firstSnapshot) {
          firstSnapshot = false;
          return new Response(JSON.stringify({ error: "bad_session" }), {
            status: 401,
            headers: { "Content-Type": "application/json" },
          });
        }
        return new Response(JSON.stringify({ ok: true }), {
          status: 200,
          headers: { "Content-Type": "application/json" },
        });
      }
      return new Response("", { status: 200 });
    }) as typeof fetch;

    const result = await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "server-token" },
      "/snapshot",
      {},
      { agentId: "alpha" },
    );
    assert.deepStrictEqual(result, { ok: true });
    const sessionPosts = calls.filter((c) => c.url.endsWith("/sessions") && c.method === "POST");
    assert.strictEqual(sessionPosts.length, 2, "should re-create session after 401");
    const snapshotCalls = calls.filter((c) => c.url.endsWith("/snapshot"));
    assert.strictEqual(snapshotCalls.length, 2);
    assert.strictEqual(snapshotCalls[0].headers.Authorization, "Session ses_token_1");
    assert.strictEqual(snapshotCalls[1].headers.Authorization, "Session ses_token_2");
  });

  it("does not loop indefinitely if 401s keep coming after retry", async () => {
    clearPinchtabSessionCache();
    let sessionPosts = 0;
    let snapshotCalls = 0;
    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
      const url = typeof input === "string" ? input : input.toString();
      const method = (init?.method || "GET").toUpperCase();
      if (url.endsWith("/sessions") && method === "POST") {
        sessionPosts += 1;
        return new Response(JSON.stringify({ sessionToken: `ses_${sessionPosts}` }), {
          status: 200,
          headers: { "Content-Type": "application/json" },
        });
      }
      snapshotCalls += 1;
      return new Response("bad_session", { status: 401 });
    }) as typeof fetch;

    const result = await pinchtabFetch(
      { baseUrl: "http://localhost:9867", token: "server-token" },
      "/snapshot",
      {},
      { agentId: "alpha" },
    );
    assert.strictEqual(snapshotCalls, 2, "exactly one retry, no infinite loop");
    assert.strictEqual(result.error, "401 ");
  });
});

describe("pinchtabFetch session cache bounding", () => {
  const originalFetch = globalThis.fetch;
  const maxEntries = 256; // mirrors pinchtabSessionMaxEntries in client.ts (not exported)
  const maxAgeMs = 60 * 60 * 1000; // mirrors pinchtabSessionMaxAgeMs in client.ts (not exported)
  let sessionPostsByAgent: Map<string, number>;

  function installFetchStub(): void {
    sessionPostsByAgent = new Map();
    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
      const url = typeof input === "string" ? input : input.toString();
      const method = (init?.method || "GET").toUpperCase();
      if (url.endsWith("/sessions") && method === "POST") {
        const agentId = JSON.parse(String(init?.body ?? "{}")).agentId as string;
        const count = (sessionPostsByAgent.get(agentId) ?? 0) + 1;
        sessionPostsByAgent.set(agentId, count);
        return new Response(JSON.stringify({ sessionToken: `tok_${agentId}_${count}` }), {
          status: 200,
          headers: { "Content-Type": "application/json" },
        });
      }
      return new Response(JSON.stringify({ ok: true }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      });
    }) as typeof fetch;
  }

  beforeEach(() => {
    clearPinchtabSessionCache();
    installFetchStub();
  });

  afterEach(() => {
    globalThis.fetch = originalFetch;
    clearPinchtabSessionCache();
    mock.timers.reset();
  });

  const cfg = { baseUrl: "http://localhost:9867", token: "server-token" };

  it("evicts the oldest agent's session once the cap is exceeded, but retains the newest", async () => {
    // Drive maxEntries distinct agents through the public API; each gets one
    // /sessions POST and is then cached. The cache is exactly full (== cap).
    for (let i = 0; i < maxEntries; i++) {
      await pinchtabFetch(cfg, "/snapshot", {}, { agentId: `agent_${i}` });
    }
    // Every agent so far should have created exactly one session.
    assert.strictEqual(sessionPostsByAgent.size, maxEntries);
    for (const [, count] of sessionPostsByAgent) assert.strictEqual(count, 1);

    // One more distinct agent pushes size to cap+1 → prune evicts the single
    // oldest-by-updatedAt entry (agent_0, inserted first).
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "agent_overflow" });
    assert.strictEqual(sessionPostsByAgent.get("agent_overflow"), 1);

    // The newest agent is still cached: re-calling reuses its token (no new POST).
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "agent_overflow" });
    assert.strictEqual(sessionPostsByAgent.get("agent_overflow"), 1, "newest agent retained");

    // The oldest agent (agent_0) was evicted: re-calling forces a fresh session.
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "agent_0" });
    assert.strictEqual(sessionPostsByAgent.get("agent_0"), 2, "oldest agent evicted → re-created");

    // A middle agent that was never the oldest survivor stays cached (no new POST).
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: `agent_${maxEntries - 1}` });
    assert.strictEqual(sessionPostsByAgent.get(`agent_${maxEntries - 1}`), 1, "recent agent retained");
  });

  it("evicts exactly one entry per single-entry overflow (stays bounded at the cap)", async () => {
    for (let i = 0; i < maxEntries; i++) {
      await pinchtabFetch(cfg, "/snapshot", {}, { agentId: `a_${i}` });
    }
    // Overflow by one: only the single oldest (a_0) is evicted; a_1 survives.
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "extra" });

    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "a_1" });
    assert.strictEqual(sessionPostsByAgent.get("a_1"), 1, "second-oldest survives a one-entry overflow");

    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "a_0" });
    assert.strictEqual(sessionPostsByAgent.get("a_0"), 2, "only the single oldest entry was evicted");
  });

  it("ages out a cached session older than the max age (Date-mocked) and re-creates it", async () => {
    // Mock only the Date API so Date.now() is controllable; the real setTimeout
    // used by ensurePinchtabSession's abort controller is left untouched and the
    // fetch stub resolves synchronously, so no timers need to fire.
    mock.timers.enable({ apis: ["Date"] });
    mock.timers.setTime(1_000_000);

    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "stale" });
    assert.strictEqual(sessionPostsByAgent.get("stale"), 1);

    // Still within max age → cached token reused, no new POST.
    mock.timers.tick(maxAgeMs - 1);
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "stale" });
    assert.strictEqual(sessionPostsByAgent.get("stale"), 1, "fresh entry reused within max age");

    // Cross the max-age boundary → entry is treated as aged out and re-created.
    mock.timers.tick(2);
    await pinchtabFetch(cfg, "/snapshot", {}, { agentId: "stale" });
    assert.strictEqual(sessionPostsByAgent.get("stale"), 2, "aged-out entry re-created past max age");
  });
});

describe("textResult", () => {
  it("wraps string as text content", () => {
    const result = textResult("hello");
    assert.deepStrictEqual(result, { content: [{ type: "text", text: "hello" }] });
  });

  it("wraps object as JSON text", () => {
    const result = textResult({ key: "value" });
    assert.strictEqual(result.content[0].type, "text");
    assert.ok(result.content[0].text.includes('"key"'));
  });

  it("uses text property if present", () => {
    const result = textResult({ text: "extracted" });
    assert.deepStrictEqual(result, { content: [{ type: "text", text: "extracted" }] });
  });
});

describe("imageResult", () => {
  it("creates image content", () => {
    const result = imageResult("base64data", "image/png");
    assert.deepStrictEqual(result, {
      content: [{ type: "image", data: "base64data", mimeType: "image/png" }],
    });
  });
});

describe("resourceResult", () => {
  it("creates resource content", () => {
    const result = resourceResult("pdf://export", "application/pdf", "base64blob");
    assert.deepStrictEqual(result, {
      content: [{ type: "resource", resource: { uri: "pdf://export", mimeType: "application/pdf", blob: "base64blob" } }],
    });
  });
});