@aria-cli/tools 1.0.9 → 1.0.11

package/tests/definitions/browser.test.ts

@@ -1,495 +0,0 @@
-/**
- * @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");
-    });
-  });
-});