@aria-cli/tools 1.0.0

package/tests/definitions/browser.test.ts

@@ -0,0 +1,495 @@
+/**
+ * @aria/tools - browser tool unit tests
+ *
+ * Tests for snapshot parsing, role-ref system, shared utilities,
+ * and the browser tool definition. Playwright is mocked — no real browser.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  buildRoleSnapshotFromAriaSnapshot,
+  getRoleSnapshotStats,
+} from "../../src/definitions/browser/pw-snapshot.js";
+import {
+  parseRoleRef,
+  requireRef,
+  normalizeTimeoutMs,
+  toAIFriendlyError,
+} from "../../src/definitions/browser/pw-shared.js";
+import {
+  closeBrowser,
+  getSession,
+  launchBrowser,
+  resolveChromiumLauncher,
+  setPlaywrightLoaderForTest,
+} from "../../src/definitions/browser/pw-session.js";
+
+// ── pw-snapshot ──────────────────────────────────────────────────────
+
+describe("browser", () => {
+  describe("pw-snapshot", () => {
+    it("builds role snapshot with refs from ariaSnapshot output", () => {
+      const ariaTree = [
+        "- navigation:",
+        '  - link "Home"',
+        '  - link "About"',
+        "- main:",
+        '  - heading "Welcome" [level=1]',
+        '  - button "Sign Up"',
+        '  - textbox "Email"',
+      ].join("\n");
+
+      const { snapshot, refs } = buildRoleSnapshotFromAriaSnapshot(ariaTree);
+
+      // Should have refs for interactive elements and named content elements
+      expect(Object.keys(refs).length).toBeGreaterThan(0);
+
+      // Should contain [ref=eN] markers
+      expect(snapshot).toContain("[ref=");
+
+      // Interactive elements should get refs
+      const refEntries = Object.values(refs);
+      const roles = refEntries.map((r) => r.role);
+      expect(roles).toContain("link");
+      expect(roles).toContain("button");
+      expect(roles).toContain("textbox");
+    });
+
+    it("filters to interactive elements only", () => {
+      const ariaTree = [
+        "- navigation:",
+        '  - link "Home"',
+        '  - link "About"',
+        "- main:",
+        '  - heading "Welcome" [level=1]',
+        '  - paragraph "Some text"',
+        '  - button "Click me"',
+      ].join("\n");
+
+      const { refs, snapshot } = buildRoleSnapshotFromAriaSnapshot(ariaTree, {
+        interactive: true,
+      });
+
+      // Only interactive roles should appear
+      const roles = Object.values(refs).map((r) => r.role);
+      expect(roles).toContain("link");
+      expect(roles).toContain("button");
+      // heading is a content role, not interactive
+      expect(roles).not.toContain("heading");
+      // paragraph is not a known role in any category
+      expect(roles).not.toContain("paragraph");
+    });
+
+    it("deduplicates refs with nth disambiguation", () => {
+      const ariaTree = ['- button "Submit"', '- button "Submit"', '- button "Cancel"'].join("\n");
+
+      const { refs } = buildRoleSnapshotFromAriaSnapshot(ariaTree);
+
+      // There should be 3 refs total
+      const entries = Object.entries(refs);
+      expect(entries).toHaveLength(3);
+
+      // The duplicate "Submit" buttons should get nth values
+      const submitRefs = entries.filter(([, r]) => r.name === "Submit");
+      expect(submitRefs).toHaveLength(2);
+
+      // nth should be set for duplicates
+      const nthValues = submitRefs.map(([, r]) => r.nth);
+      expect(nthValues).toContain(0);
+      expect(nthValues).toContain(1);
+
+      // "Cancel" button has no duplicates, nth should be removed
+      const cancelRef = entries.find(([, r]) => r.name === "Cancel");
+      expect(cancelRef).toBeDefined();
+      expect(cancelRef![1].nth).toBeUndefined();
+    });
+
+    it("calculates interactive vs total stats", () => {
+      const ariaTree = [
+        '- heading "Title"',
+        '- button "Click"',
+        '- link "Go"',
+        '- textbox "Input"',
+      ].join("\n");
+
+      const { snapshot, refs } = buildRoleSnapshotFromAriaSnapshot(ariaTree);
+      const stats = getRoleSnapshotStats(snapshot, refs);
+
+      expect(stats.refs).toBe(Object.keys(refs).length);
+      // 3 interactive (button, link, textbox), 1 content (heading)
+      expect(stats.interactive).toBe(3);
+      expect(stats.lines).toBeGreaterThan(0);
+      expect(stats.chars).toBeGreaterThan(0);
+    });
+
+    it("returns (empty) for blank input", () => {
+      const { snapshot } = buildRoleSnapshotFromAriaSnapshot("");
+      expect(snapshot).toBe("(empty)");
+    });
+
+    it("returns (no interactive elements) for interactive mode with no interactive elements", () => {
+      const ariaTree = ['- heading "Title"', "- generic:"].join("\n");
+
+      const { snapshot } = buildRoleSnapshotFromAriaSnapshot(ariaTree, {
+        interactive: true,
+      });
+
+      expect(snapshot).toBe("(no interactive elements)");
+    });
+
+    it("respects maxDepth option", () => {
+      const ariaTree = [
+        "- main:",
+        "  - navigation:",
+        '    - link "Deep Link"',
+        '  - button "Top Button"',
+      ].join("\n");
+
+      const { refs } = buildRoleSnapshotFromAriaSnapshot(ariaTree, {
+        maxDepth: 1,
+      });
+
+      // Only depth 0 (main) and depth 1 (navigation, button) should be processed
+      const roles = Object.values(refs).map((r) => r.role);
+      expect(roles).toContain("button");
+      // Deep link at depth 2 should be excluded
+      expect(roles).not.toContain("link");
+    });
+
+    it("compact mode removes empty structural elements", () => {
+      const ariaTree = ["- generic:", "  - generic:", '    - button "Click"', "- group:"].join(
+        "\n",
+      );
+
+      const { snapshot } = buildRoleSnapshotFromAriaSnapshot(ariaTree, {
+        compact: true,
+      });
+
+      // The empty "group:" at the end should be stripped (no children with refs)
+      // But the generic parent chain leading to button should remain
+      expect(snapshot).toContain("button");
+    });
+
+    it("ref counter generates sequential e1, e2, e3 ids", () => {
+      const ariaTree = ['- button "A"', '- button "B"', '- button "C"'].join("\n");
+
+      const { refs } = buildRoleSnapshotFromAriaSnapshot(ariaTree);
+      const keys = Object.keys(refs);
+
+      expect(keys).toContain("e1");
+      expect(keys).toContain("e2");
+      expect(keys).toContain("e3");
+    });
+  });
+
+  // ── pw-shared ──────────────────────────────────────────────────────
+
+  describe("pw-shared", () => {
+    it('parses ref formats: "e1"', () => {
+      expect(parseRoleRef("e1")).toBe("e1");
+    });
+
+    it('parses ref formats: "@e1"', () => {
+      expect(parseRoleRef("@e1")).toBe("e1");
+    });
+
+    it('parses ref formats: "ref=e1"', () => {
+      expect(parseRoleRef("ref=e1")).toBe("e1");
+    });
+
+    it("parses multi-digit refs", () => {
+      expect(parseRoleRef("e123")).toBe("e123");
+      expect(parseRoleRef("@e42")).toBe("e42");
+      expect(parseRoleRef("ref=e999")).toBe("e999");
+    });
+
+    it("handles whitespace around refs", () => {
+      expect(parseRoleRef("  e1  ")).toBe("e1");
+      expect(parseRoleRef("  @e2  ")).toBe("e2");
+    });
+
+    it("rejects invalid ref formats", () => {
+      expect(parseRoleRef("")).toBeNull();
+      expect(parseRoleRef("   ")).toBeNull();
+      expect(parseRoleRef("abc")).toBeNull();
+      expect(parseRoleRef("e")).toBeNull();
+      expect(parseRoleRef("1")).toBeNull();
+      expect(parseRoleRef("button")).toBeNull();
+      expect(parseRoleRef("@abc")).toBeNull();
+      expect(parseRoleRef("ref=xyz")).toBeNull();
+    });
+
+    it("requireRef throws on empty/invalid input", () => {
+      expect(() => requireRef("")).toThrow("ref is required");
+      expect(() => requireRef(undefined)).toThrow("ref is required");
+      expect(() => requireRef(null)).toThrow("ref is required");
+    });
+
+    it("requireRef normalizes valid refs", () => {
+      expect(requireRef("e5")).toBe("e5");
+      expect(requireRef("@e5")).toBe("e5");
+      expect(requireRef("ref=e5")).toBe("e5");
+    });
+
+    it("requireRef passes through non-standard refs as-is", () => {
+      // When the ref doesn't match eN pattern but is non-empty, it's passed through
+      const result = requireRef("custom-selector");
+      expect(result).toBe("custom-selector");
+    });
+
+    it("clamps timeout to 500-120000ms", () => {
+      expect(normalizeTimeoutMs(100, 5000)).toBe(500);
+      expect(normalizeTimeoutMs(200_000, 5000)).toBe(120_000);
+      expect(normalizeTimeoutMs(5000, 5000)).toBe(5000);
+      expect(normalizeTimeoutMs(undefined, 3000)).toBe(3000);
+    });
+
+    it("clamps timeout with boundary values", () => {
+      expect(normalizeTimeoutMs(500, 5000)).toBe(500);
+      expect(normalizeTimeoutMs(120_000, 5000)).toBe(120_000);
+      expect(normalizeTimeoutMs(0, 5000)).toBe(500);
+      expect(normalizeTimeoutMs(-1, 5000)).toBe(500);
+    });
+
+    it("formats AI-friendly error for strict mode violation", () => {
+      const error = new Error("strict mode violation: getByRole resolved to 3 elements");
+      const friendly = toAIFriendlyError(error, "button[Submit]");
+
+      expect(friendly.message).toContain("3 elements");
+      expect(friendly.message).toContain("snapshot");
+    });
+
+    it("formats AI-friendly error for timeout/not visible", () => {
+      const error = new Error("Timeout 30000ms exceeded waiting for element to be visible");
+      const friendly = toAIFriendlyError(error, "e5");
+
+      expect(friendly.message).toContain("not found or not visible");
+      expect(friendly.message).toContain("snapshot");
+    });
+
+    it("formats AI-friendly error for pointer interception", () => {
+      const error = new Error("Element intercepts pointer events");
+      const friendly = toAIFriendlyError(error, "e3");
+
+      expect(friendly.message).toContain("not interactable");
+      expect(friendly.message).toContain("scrolling");
+    });
+
+    it("passes through unrecognized errors unchanged", () => {
+      const error = new Error("some random error");
+      const friendly = toAIFriendlyError(error, "e1");
+
+      expect(friendly.message).toBe("some random error");
+    });
+
+    it("handles non-Error objects", () => {
+      const friendly = toAIFriendlyError("string error", "e1");
+      expect(friendly).toBeInstanceOf(Error);
+      expect(friendly.message).toBe("string error");
+    });
+  });
+
+  describe("pw-session", () => {
+    beforeEach(async () => {
+      await closeBrowser();
+      setPlaywrightLoaderForTest(null);
+      vi.restoreAllMocks();
+    });
+
+    afterEach(async () => {
+      await closeBrowser();
+      setPlaywrightLoaderForTest(null);
+      vi.restoreAllMocks();
+    });
+
+    function installMockPlaywright(opts?: { failNavigationTo?: string }): {
+      goto: ReturnType<typeof vi.fn>;
+    } {
+      let currentUrl = "about:blank";
+      const goto = vi.fn(async (url: string) => {
+        if (opts?.failNavigationTo && url === opts.failNavigationTo) {
+          throw new Error("page.goto: Timeout 20000ms exceeded.");
+        }
+        currentUrl = url;
+      });
+
+      const page = {
+        goto,
+        url: () => currentUrl,
+        title: async () => "Mock page",
+        close: async () => undefined,
+        content: async () => "",
+        setViewportSize: async () => undefined,
+        screenshot: async () => Buffer.from(""),
+        evaluate: async () => undefined,
+        locator: () =>
+          ({
+            ariaSnapshot: async () => "",
+          }) as unknown,
+        getByRole: () => ({}) as unknown,
+        keyboard: { press: async () => undefined },
+        mouse: { wheel: async () => undefined },
+        waitForTimeout: async () => undefined,
+        waitForSelector: async () => undefined,
+        waitForLoadState: async () => undefined,
+        on: () => undefined,
+        off: () => undefined,
+        isClosed: () => false,
+        frameLocator: () => ({}) as unknown,
+      } as any;
+
+      const context = {
+        pages: () => [page],
+        newPage: async () => page,
+        cookies: async () => [],
+        addCookies: async () => undefined,
+        clearCookies: async () => undefined,
+        setOffline: async () => undefined,
+        close: async () => undefined,
+      };
+
+      const browser = {
+        close: async () => undefined,
+        contexts: () => [context],
+        isConnected: () => true,
+        newContext: async () => context,
+      };
+
+      setPlaywrightLoaderForTest(async () => ({
+        chromium: {
+          launch: async () => browser,
+        },
+      }));
+
+      return { goto };
+    }
+
+    it("accepts playwright module with top-level chromium", () => {
+      const launch = async () => ({ close: async () => undefined });
+      const chromium = resolveChromiumLauncher({ chromium: { launch } });
+      expect(chromium.launch).toBe(launch);
+    });
+
+    it("accepts playwright module with default.chromium", () => {
+      const launch = async () => ({ close: async () => undefined });
+      const chromium = resolveChromiumLauncher({
+        default: { chromium: { launch } },
+      });
+      expect(chromium.launch).toBe(launch);
+    });
+
+    it("throws a descriptive error when chromium launcher is missing", () => {
+      expect(() => resolveChromiumLauncher({ default: {} })).toThrow(
+        "Invalid playwright module shape",
+      );
+      expect(() => resolveChromiumLauncher({ default: {} })).toThrow("missing chromium.launch");
+    });
+
+    it("keeps a live session when initial launch navigation times out", async () => {
+      installMockPlaywright({ failNavigationTo: "https://news.ycombinator.com/" });
+
+      await expect(launchBrowser({ url: "https://news.ycombinator.com/" })).rejects.toThrow(
+        "Session remains active",
+      );
+
+      const session = getSession();
+      expect(session).not.toBeNull();
+      expect(session?.page.url()).toBe("about:blank");
+    });
+
+    it("allows navigate after launch timeout because session remains active", async () => {
+      const { goto } = installMockPlaywright({
+        failNavigationTo: "https://news.ycombinator.com/",
+      });
+
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      const launchResult = await browserTool.execute(
+        { action: "launch", url: "https://news.ycombinator.com/" },
+        {} as never,
+      );
+      expect(launchResult.success).toBe(false);
+      expect(launchResult.message).toContain("Session remains active");
+
+      const navigateResult = await browserTool.execute(
+        { action: "navigate", url: "https://example.com/" },
+        {} as never,
+      );
+      expect(navigateResult.success).toBe(true);
+      expect(goto).toHaveBeenCalledWith(
+        "https://example.com/",
+        expect.objectContaining({ waitUntil: "domcontentloaded" }),
+      );
+    });
+
+    it("auto-launches when navigate is called without an explicit launch", async () => {
+      const { goto } = installMockPlaywright();
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      const result = await browserTool.execute(
+        { action: "navigate", url: "https://example.com/" },
+        {} as never,
+      );
+
+      expect(result.success).toBe(true);
+      expect(goto).toHaveBeenCalledWith(
+        "https://example.com/",
+        expect.objectContaining({ waitUntil: "domcontentloaded" }),
+      );
+    });
+
+    it("auto-launches when tab_new is called without an explicit launch", async () => {
+      installMockPlaywright();
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      const result = await browserTool.execute(
+        { action: "tab_new", url: "https://example.com/" },
+        {} as never,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("[0]");
+      expect(result.message).toContain("https://example.com/");
+    });
+  });
+
+  // ── browser tool definition ───────────────────────────────────────
+
+  describe("browser tool definition", () => {
+    it("has correct tool metadata", async () => {
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      expect(browserTool.name).toBe("browser");
+      expect(browserTool.category).toBe("web");
+      expect(browserTool.riskLevel).toBe("moderate");
+      expect(browserTool.isReadOnly).toBe(false);
+      expect(browserTool.loadingTier).toBe("always");
+      expect(typeof browserTool.execute).toBe("function");
+    });
+
+    it("validates action parameter is required in schema", async () => {
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      const schema = browserTool.parameters as {
+        required?: string[];
+        properties?: Record<string, unknown>;
+      };
+      expect(schema.required).toContain("action");
+      expect(schema.properties?.action).toBeDefined();
+    });
+
+    it("schema lists all supported actions", async () => {
+      const { browserTool } = await import("../../src/definitions/browser/browser.js");
+
+      const actionProp = (browserTool.parameters as any).properties.action;
+      expect(actionProp.enum).toContain("launch");
+      expect(actionProp.enum).toContain("close");
+      expect(actionProp.enum).toContain("navigate");
+      expect(actionProp.enum).toContain("snapshot");
+      expect(actionProp.enum).toContain("click");
+      expect(actionProp.enum).toContain("type");
+      expect(actionProp.enum).toContain("screenshot");
+      expect(actionProp.enum).toContain("evaluate");
+    });
+  });
+});