@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-preview.1

package/dist/esm/tests/unit/snapshot-a11y-resolvers.test.js

@@ -0,0 +1,295 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { a11yForFrame } from "../../lib/v3/understudy/a11y/snapshot/a11yTree.js";
+import * as focusSelectors from "../../lib/v3/understudy/a11y/snapshot/focusSelectors.js";
+import { MockCDPSession } from "./helpers/mockCDPSession.js";
+import { executionContexts } from "../../lib/v3/understudy/executionContextRegistry.js";
+import { tryScopedSnapshot } from "../../lib/v3/understudy/a11y/snapshot/capture.js";
+import * as domTree from "../../lib/v3/understudy/a11y/snapshot/domTree.js";
+import * as a11yTree from "../../lib/v3/understudy/a11y/snapshot/a11yTree.js";
+import * as logger from "../../lib/v3/logger.js";
+const stringType = "string";
+const baseAxNodes = () => [
+    {
+        nodeId: "1",
+        role: { type: stringType, value: "RootWebArea" },
+        backendDOMNodeId: 100,
+        childIds: ["2"],
+        ignored: false,
+    },
+    {
+        nodeId: "2",
+        role: { type: stringType, value: "link" },
+        name: { type: stringType, value: "Docs" },
+        backendDOMNodeId: 101,
+        parentId: "1",
+        childIds: [],
+        properties: [
+            {
+                name: "url",
+                value: { type: stringType, value: "https://example.com" },
+            },
+        ],
+        ignored: false,
+    },
+];
+const baseHandlers = {
+    "Accessibility.enable": async () => ({}),
+    "Runtime.enable": async () => ({}),
+    "DOM.enable": async () => ({}),
+};
+describe("a11yForFrame", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns full outline and url map when no focus selector is provided", async () => {
+        const session = new MockCDPSession({
+            ...baseHandlers,
+            "Accessibility.getFullAXTree": async () => ({ nodes: baseAxNodes() }),
+        });
+        const opts = {
+            focusSelector: undefined,
+            experimental: false,
+            tagNameMap: { "enc-100": "#document", "enc-101": "a" },
+            scrollableMap: {},
+            encode: (backend) => `enc-${backend}`,
+        };
+        const result = await a11yForFrame(session, undefined, opts);
+        expect(result.scopeApplied).toBe(false);
+        expect(result.urlMap["enc-101"]).toBe("https://example.com");
+        expect(result.outline).toContain("Docs");
+    });
+    it("scopes the tree to the resolved focus selector target", async () => {
+        const nodes = baseAxNodes().map((n) => n.nodeId === "2"
+            ? {
+                ...n,
+                childIds: ["3"],
+            }
+            : n);
+        nodes.push({
+            nodeId: "3",
+            parentId: "2",
+            childIds: [],
+            role: { type: stringType, value: "StaticText" },
+            backendDOMNodeId: 102,
+            ignored: false,
+        });
+        let scopedOnce = false;
+        const session = new MockCDPSession({
+            ...baseHandlers,
+            "Accessibility.getFullAXTree": async (params) => {
+                if (params?.frameId && !scopedOnce) {
+                    scopedOnce = true;
+                    throw new Error("does not belong to the target");
+                }
+                return { nodes };
+            },
+            "DOM.describeNode": async () => ({
+                node: { backendNodeId: 101 },
+            }),
+        });
+        const resolveSpy = vi
+            .spyOn(focusSelectors, "resolveObjectIdForXPath")
+            .mockResolvedValue("object-1");
+        const opts = {
+            focusSelector: "xpath=//a",
+            experimental: false,
+            tagNameMap: { "enc-101": "a" },
+            scrollableMap: {},
+            encode: (backend) => `enc-${backend}`,
+        };
+        const result = await a11yForFrame(session, "frame-1", opts);
+        expect(result.scopeApplied).toBe(true);
+        expect(result.outline).not.toContain("RootWebArea");
+        expect(resolveSpy).toHaveBeenCalled();
+        resolveSpy.mockRestore();
+    });
+    it("falls back to full tree when resolveObjectId throws", async () => {
+        const session = new MockCDPSession({
+            ...baseHandlers,
+            "Accessibility.getFullAXTree": async () => ({ nodes: baseAxNodes() }),
+        });
+        vi.spyOn(focusSelectors, "resolveObjectIdForCss").mockRejectedValue(new Error("fail"));
+        const opts = {
+            focusSelector: ".btn",
+            experimental: false,
+            tagNameMap: {},
+            scrollableMap: {},
+            encode: (backend) => `enc-${backend}`,
+        };
+        const result = await a11yForFrame(session, "frame-1", opts);
+        expect(result.scopeApplied).toBe(false);
+    });
+});
+describe("resolveObjectIdForXPath", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("evaluates in the target frame's main world when available", async () => {
+        vi.spyOn(executionContexts, "waitForMainWorld").mockResolvedValue(42);
+        vi.spyOn(executionContexts, "getMainWorld").mockReturnValue(undefined);
+        const session = new MockCDPSession({
+            "Runtime.evaluate": async (params) => {
+                expect(params?.contextId).toBe(42);
+                return { result: { objectId: "node-obj" } };
+            },
+        });
+        const objectId = await focusSelectors.resolveObjectIdForXPath(session, "//div", "frame-1");
+        expect(objectId).toBe("node-obj");
+    });
+    it("returns null when evaluation throws or reports exception details", async () => {
+        vi.spyOn(executionContexts, "waitForMainWorld").mockRejectedValue(new Error("missing"));
+        vi.spyOn(executionContexts, "getMainWorld").mockReturnValue(undefined);
+        const session = new MockCDPSession({
+            "Runtime.evaluate": async () => ({
+                result: {},
+                exceptionDetails: { exception: { description: "bad" } },
+            }),
+        });
+        const objectId = await focusSelectors.resolveObjectIdForXPath(session, "//div", "frame-2");
+        expect(objectId).toBeNull();
+    });
+});
+describe("resolveObjectIdForCss", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns primary evaluation result when available", async () => {
+        vi.spyOn(executionContexts, "waitForMainWorld").mockResolvedValue(7);
+        const session = new MockCDPSession({
+            "Runtime.evaluate": async () => ({
+                result: { objectId: "primary-obj" },
+            }),
+        });
+        const objectId = await focusSelectors.resolveObjectIdForCss(session, ".btn", "frame-1");
+        expect(objectId).toBe("primary-obj");
+    });
+    it("falls back to the pierce selector when the primary lookup fails", async () => {
+        let call = 0;
+        const session = new MockCDPSession({
+            "Runtime.evaluate": async (params) => {
+                call++;
+                if (call === 1) {
+                    expect(String(params?.expression)).toContain("resolveCssSelector");
+                    return { result: {} };
+                }
+                expect(String(params?.expression)).toContain("resolveCssSelectorPierce");
+                return { result: { objectId: "css-obj" } };
+            },
+        });
+        const objectId = await focusSelectors.resolveObjectIdForCss(session, ".btn", undefined);
+        expect(objectId).toBe("css-obj");
+    });
+    it("returns null when both primary and fallback evaluations throw", async () => {
+        vi.spyOn(executionContexts, "waitForMainWorld").mockResolvedValue(11);
+        vi.spyOn(executionContexts, "getMainWorld").mockReturnValue(undefined);
+        const session = new MockCDPSession({
+            "Runtime.evaluate": async () => ({
+                result: {},
+                exceptionDetails: { exception: { description: "fail" } },
+            }),
+        });
+        const objectId = await focusSelectors.resolveObjectIdForCss(session, ".missing", "frame-1");
+        expect(objectId).toBeNull();
+    });
+});
+describe("tryScopedSnapshot", () => {
+    const ordinal = (frameId) => (frameId === "frame-1" ? 0 : 1);
+    const context = {
+        rootId: "frame-1",
+        frames: ["frame-1", "frame-2"],
+        parentByFrame: new Map([
+            ["frame-1", null],
+            ["frame-2", "frame-1"],
+        ]),
+    };
+    const makePage = (session, overrides) => ({
+        mainFrameId: () => "frame-1",
+        asProtocolFrameTree: () => ({
+            frame: { id: "frame-1" },
+            childFrames: [{ frame: { id: "frame-2" } }],
+        }),
+        listAllFrameIds: () => ["frame-1", "frame-2"],
+        getSessionForFrame: () => session,
+        getOrdinal: (fid) => ordinal(fid),
+        ...overrides,
+    });
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns scoped snapshot when focus selector resolves via CSS hops", async () => {
+        const session = new MockCDPSession({});
+        const domMapsSpy = vi
+            .spyOn(domTree, "domMapsForSession")
+            .mockResolvedValue({
+            tagNameMap: { "1-10": "div" },
+            xpathMap: { "1-10": "/div[1]" },
+            scrollableMap: {},
+        });
+        const a11ySpy = vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+            outline: "[1-10] div",
+            urlMap: { "1-10": "https://example.com" },
+            scopeApplied: true,
+        });
+        vi.spyOn(focusSelectors, "resolveCssFocusFrameAndTail").mockResolvedValue({
+            targetFrameId: "frame-2",
+            tailSelector: ".btn-inner",
+            absPrefix: "/html/body/iframe[1]",
+        });
+        const result = await tryScopedSnapshot(makePage(session), { focusSelector: ".btn" }, context, true);
+        expect(result).not.toBeNull();
+        expect(result?.combinedXpathMap["1-10"]).toBe("/html/body/iframe[1]/div[1]");
+        expect(domMapsSpy).toHaveBeenCalled();
+        expect(a11ySpy).toHaveBeenCalled();
+    });
+    it("returns null and logs fallback when scope is not applied", async () => {
+        const session = new MockCDPSession({});
+        vi.spyOn(domTree, "domMapsForSession").mockResolvedValue({
+            tagNameMap: { "1-10": "div" },
+            xpathMap: { "1-10": "/div[1]" },
+            scrollableMap: {},
+        });
+        vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+            outline: "ignored",
+            urlMap: {},
+            scopeApplied: false,
+        });
+        const loggerSpy = vi.spyOn(logger, "v3Logger").mockImplementation(() => { });
+        const result = await tryScopedSnapshot(makePage(session), { focusSelector: ".btn" }, context, false);
+        expect(result).toBeNull();
+        expect(loggerSpy).toHaveBeenCalled();
+    });
+    it("returns null immediately when no focus selector is provided", async () => {
+        const result = await tryScopedSnapshot(makePage(new MockCDPSession({})), {}, context, true);
+        expect(result).toBeNull();
+    });
+    it("supports XPath focus resolution branch", async () => {
+        const session = new MockCDPSession({});
+        vi.spyOn(domTree, "domMapsForSession").mockResolvedValue({
+            tagNameMap: { "1-10": "div" },
+            xpathMap: { "1-10": "/div[1]" },
+            scrollableMap: {},
+        });
+        vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+            outline: "[1-10] div",
+            urlMap: {},
+            scopeApplied: true,
+        });
+        vi.spyOn(focusSelectors, "resolveFocusFrameAndTail").mockResolvedValue({
+            targetFrameId: "frame-1",
+            tailXPath: "//div[1]",
+            absPrefix: "",
+        });
+        const result = await tryScopedSnapshot(makePage(session), { focusSelector: "xpath=//div" }, context, true);
+        expect(result).not.toBeNull();
+        expect(result?.combinedXpathMap["1-10"]).toBe("/div[1]");
+    });
+    it("logs and returns null when resolver throws", async () => {
+        const session = new MockCDPSession({});
+        vi.spyOn(focusSelectors, "resolveCssFocusFrameAndTail").mockRejectedValue(new Error("bad selector"));
+        const loggerSpy = vi.spyOn(logger, "v3Logger").mockImplementation(() => { });
+        const result = await tryScopedSnapshot(makePage(session), { focusSelector: ".bad" }, context, true);
+        expect(result).toBeNull();
+        expect(loggerSpy).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=snapshot-a11y-resolvers.test.js.map

package/dist/esm/tests/unit/snapshot-a11y-resolvers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-a11y-resolvers.test.js","sourceRoot":"","sources":["../../../../tests/unit/snapshot-a11y-resolvers.test.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport { beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { a11yForFrame } from \"../../lib/v3/understudy/a11y/snapshot/a11yTree.js\";\nimport type { AccessibilityTreeResult } from \"../../lib/v3/types/private/index.js\";\nimport * as focusSelectors from \"../../lib/v3/understudy/a11y/snapshot/focusSelectors.js\";\nimport { MockCDPSession } from \"./helpers/mockCDPSession.js\";\nimport { executionContexts } from \"../../lib/v3/understudy/executionContextRegistry.js\";\nimport { tryScopedSnapshot } from \"../../lib/v3/understudy/a11y/snapshot/capture.js\";\nimport type {\n  FrameContext,\n  A11yOptions,\n} from \"../../lib/v3/types/private/index.js\";\nimport type { Page } from \"../../lib/v3/understudy/page.js\";\nimport * as domTree from \"../../lib/v3/understudy/a11y/snapshot/domTree.js\";\nimport * as a11yTree from \"../../lib/v3/understudy/a11y/snapshot/a11yTree.js\";\nimport * as logger from \"../../lib/v3/logger.js\";\n\nconst stringType = \"string\" as Protocol.Accessibility.AXValueType;\n\nconst baseAxNodes = (): Protocol.Accessibility.AXNode[] => [\n  {\n    nodeId: \"1\",\n    role: { type: stringType, value: \"RootWebArea\" },\n    backendDOMNodeId: 100,\n    childIds: [\"2\"],\n    ignored: false,\n  },\n  {\n    nodeId: \"2\",\n    role: { type: stringType, value: \"link\" },\n    name: { type: stringType, value: \"Docs\" },\n    backendDOMNodeId: 101,\n    parentId: \"1\",\n    childIds: [],\n    properties: [\n      {\n        name: \"url\",\n        value: { type: stringType, value: \"https://example.com\" },\n      },\n    ],\n    ignored: false,\n  },\n];\n\nconst baseHandlers = {\n  \"Accessibility.enable\": async () => ({}),\n  \"Runtime.enable\": async () => ({}),\n  \"DOM.enable\": async () => ({}),\n};\n\ndescribe(\"a11yForFrame\", () => {\n  beforeEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it(\"returns full outline and url map when no focus selector is provided\", async () => {\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"Accessibility.getFullAXTree\": async () => ({ nodes: baseAxNodes() }),\n    });\n\n    const opts: A11yOptions = {\n      focusSelector: undefined,\n      experimental: false,\n      tagNameMap: { \"enc-100\": \"#document\", \"enc-101\": \"a\" },\n      scrollableMap: {},\n      encode: (backend) => `enc-${backend}`,\n    };\n\n    const result = await a11yForFrame(session, undefined, opts);\n\n    expect(result.scopeApplied).toBe(false);\n    expect(result.urlMap[\"enc-101\"]).toBe(\"https://example.com\");\n    expect(result.outline).toContain(\"Docs\");\n  });\n\n  it(\"scopes the tree to the resolved focus selector target\", async () => {\n    const nodes = baseAxNodes().map((n) =>\n      n.nodeId === \"2\"\n        ? {\n            ...n,\n            childIds: [\"3\"],\n          }\n        : n,\n    );\n    nodes.push({\n      nodeId: \"3\",\n      parentId: \"2\",\n      childIds: [],\n      role: { type: stringType, value: \"StaticText\" },\n      backendDOMNodeId: 102,\n      ignored: false,\n    });\n\n    let scopedOnce = false;\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"Accessibility.getFullAXTree\": async (params) => {\n        if (params?.frameId && !scopedOnce) {\n          scopedOnce = true;\n          throw new Error(\"does not belong to the target\");\n        }\n        return { nodes };\n      },\n      \"DOM.describeNode\": async () => ({\n        node: { backendNodeId: 101 },\n      }),\n    });\n\n    const resolveSpy = vi\n      .spyOn(focusSelectors, \"resolveObjectIdForXPath\")\n      .mockResolvedValue(\"object-1\");\n\n    const opts: A11yOptions = {\n      focusSelector: \"xpath=//a\",\n      experimental: false,\n      tagNameMap: { \"enc-101\": \"a\" },\n      scrollableMap: {},\n      encode: (backend) => `enc-${backend}`,\n    };\n\n    const result = await a11yForFrame(session, \"frame-1\", opts);\n\n    expect(result.scopeApplied).toBe(true);\n    expect(result.outline).not.toContain(\"RootWebArea\");\n    expect(resolveSpy).toHaveBeenCalled();\n    resolveSpy.mockRestore();\n  });\n\n  it(\"falls back to full tree when resolveObjectId throws\", async () => {\n    const session = new MockCDPSession({\n      ...baseHandlers,\n      \"Accessibility.getFullAXTree\": async () => ({ nodes: baseAxNodes() }),\n    });\n    vi.spyOn(focusSelectors, \"resolveObjectIdForCss\").mockRejectedValue(\n      new Error(\"fail\"),\n    );\n    const opts: A11yOptions = {\n      focusSelector: \".btn\",\n      experimental: false,\n      tagNameMap: {},\n      scrollableMap: {},\n      encode: (backend) => `enc-${backend}`,\n    };\n\n    const result = await a11yForFrame(session, \"frame-1\", opts);\n    expect(result.scopeApplied).toBe(false);\n  });\n});\n\ndescribe(\"resolveObjectIdForXPath\", () => {\n  beforeEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it(\"evaluates in the target frame's main world when available\", async () => {\n    vi.spyOn(executionContexts, \"waitForMainWorld\").mockResolvedValue(42);\n    vi.spyOn(executionContexts, \"getMainWorld\").mockReturnValue(undefined);\n    const session = new MockCDPSession({\n      \"Runtime.evaluate\": async (params) => {\n        expect(params?.contextId).toBe(42);\n        return { result: { objectId: \"node-obj\" } };\n      },\n    });\n\n    const objectId = await focusSelectors.resolveObjectIdForXPath(\n      session,\n      \"//div\",\n      \"frame-1\",\n    );\n    expect(objectId).toBe(\"node-obj\");\n  });\n\n  it(\"returns null when evaluation throws or reports exception details\", async () => {\n    vi.spyOn(executionContexts, \"waitForMainWorld\").mockRejectedValue(\n      new Error(\"missing\"),\n    );\n    vi.spyOn(executionContexts, \"getMainWorld\").mockReturnValue(undefined);\n    const session = new MockCDPSession({\n      \"Runtime.evaluate\": async () => ({\n        result: {},\n        exceptionDetails: { exception: { description: \"bad\" } },\n      }),\n    });\n\n    const objectId = await focusSelectors.resolveObjectIdForXPath(\n      session,\n      \"//div\",\n      \"frame-2\",\n    );\n    expect(objectId).toBeNull();\n  });\n});\n\ndescribe(\"resolveObjectIdForCss\", () => {\n  beforeEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it(\"returns primary evaluation result when available\", async () => {\n    vi.spyOn(executionContexts, \"waitForMainWorld\").mockResolvedValue(7);\n    const session = new MockCDPSession({\n      \"Runtime.evaluate\": async () => ({\n        result: { objectId: \"primary-obj\" },\n      }),\n    });\n    const objectId = await focusSelectors.resolveObjectIdForCss(\n      session,\n      \".btn\",\n      \"frame-1\",\n    );\n    expect(objectId).toBe(\"primary-obj\");\n  });\n\n  it(\"falls back to the pierce selector when the primary lookup fails\", async () => {\n    let call = 0;\n    const session = new MockCDPSession({\n      \"Runtime.evaluate\": async (params) => {\n        call++;\n        if (call === 1) {\n          expect(String(params?.expression)).toContain(\"resolveCssSelector\");\n          return { result: {} };\n        }\n        expect(String(params?.expression)).toContain(\n          \"resolveCssSelectorPierce\",\n        );\n        return { result: { objectId: \"css-obj\" } };\n      },\n    });\n\n    const objectId = await focusSelectors.resolveObjectIdForCss(\n      session,\n      \".btn\",\n      undefined,\n    );\n    expect(objectId).toBe(\"css-obj\");\n  });\n\n  it(\"returns null when both primary and fallback evaluations throw\", async () => {\n    vi.spyOn(executionContexts, \"waitForMainWorld\").mockResolvedValue(11);\n    vi.spyOn(executionContexts, \"getMainWorld\").mockReturnValue(undefined);\n    const session = new MockCDPSession({\n      \"Runtime.evaluate\": async () => ({\n        result: {},\n        exceptionDetails: { exception: { description: \"fail\" } },\n      }),\n    });\n\n    const objectId = await focusSelectors.resolveObjectIdForCss(\n      session,\n      \".missing\",\n      \"frame-1\",\n    );\n    expect(objectId).toBeNull();\n  });\n});\n\ndescribe(\"tryScopedSnapshot\", () => {\n  const ordinal = (frameId: string) => (frameId === \"frame-1\" ? 0 : 1);\n  const context: FrameContext = {\n    rootId: \"frame-1\",\n    frames: [\"frame-1\", \"frame-2\"],\n    parentByFrame: new Map([\n      [\"frame-1\", null],\n      [\"frame-2\", \"frame-1\"],\n    ]),\n  };\n\n  const makePage = (session: MockCDPSession, overrides?: Partial<Page>): Page =>\n    ({\n      mainFrameId: () => \"frame-1\",\n      asProtocolFrameTree: () => ({\n        frame: { id: \"frame-1\" as Protocol.Page.FrameId },\n        childFrames: [{ frame: { id: \"frame-2\" as Protocol.Page.FrameId } }],\n      }),\n      listAllFrameIds: () => [\"frame-1\", \"frame-2\"],\n      getSessionForFrame: () => session,\n      getOrdinal: (fid: string) => ordinal(fid),\n      ...overrides,\n    }) as unknown as Page;\n\n  beforeEach(() => {\n    vi.restoreAllMocks();\n  });\n\n  it(\"returns scoped snapshot when focus selector resolves via CSS hops\", async () => {\n    const session = new MockCDPSession({});\n    const domMapsSpy = vi\n      .spyOn(domTree, \"domMapsForSession\")\n      .mockResolvedValue({\n        tagNameMap: { \"1-10\": \"div\" },\n        xpathMap: { \"1-10\": \"/div[1]\" },\n        scrollableMap: {},\n      });\n    const a11ySpy = vi.spyOn(a11yTree, \"a11yForFrame\").mockResolvedValue({\n      outline: \"[1-10] div\",\n      urlMap: { \"1-10\": \"https://example.com\" },\n      scopeApplied: true,\n    } as AccessibilityTreeResult);\n    vi.spyOn(focusSelectors, \"resolveCssFocusFrameAndTail\").mockResolvedValue({\n      targetFrameId: \"frame-2\",\n      tailSelector: \".btn-inner\",\n      absPrefix: \"/html/body/iframe[1]\",\n    });\n\n    const result = await tryScopedSnapshot(\n      makePage(session),\n      { focusSelector: \".btn\" },\n      context,\n      true,\n    );\n\n    expect(result).not.toBeNull();\n    expect(result?.combinedXpathMap[\"1-10\"]).toBe(\n      \"/html/body/iframe[1]/div[1]\",\n    );\n    expect(domMapsSpy).toHaveBeenCalled();\n    expect(a11ySpy).toHaveBeenCalled();\n  });\n\n  it(\"returns null and logs fallback when scope is not applied\", async () => {\n    const session = new MockCDPSession({});\n    vi.spyOn(domTree, \"domMapsForSession\").mockResolvedValue({\n      tagNameMap: { \"1-10\": \"div\" },\n      xpathMap: { \"1-10\": \"/div[1]\" },\n      scrollableMap: {},\n    });\n    vi.spyOn(a11yTree, \"a11yForFrame\").mockResolvedValue({\n      outline: \"ignored\",\n      urlMap: {},\n      scopeApplied: false,\n    } as AccessibilityTreeResult);\n    const loggerSpy = vi.spyOn(logger, \"v3Logger\").mockImplementation(() => {});\n\n    const result = await tryScopedSnapshot(\n      makePage(session),\n      { focusSelector: \".btn\" },\n      context,\n      false,\n    );\n\n    expect(result).toBeNull();\n    expect(loggerSpy).toHaveBeenCalled();\n  });\n\n  it(\"returns null immediately when no focus selector is provided\", async () => {\n    const result = await tryScopedSnapshot(\n      makePage(new MockCDPSession({})),\n      {},\n      context,\n      true,\n    );\n    expect(result).toBeNull();\n  });\n\n  it(\"supports XPath focus resolution branch\", async () => {\n    const session = new MockCDPSession({});\n    vi.spyOn(domTree, \"domMapsForSession\").mockResolvedValue({\n      tagNameMap: { \"1-10\": \"div\" },\n      xpathMap: { \"1-10\": \"/div[1]\" },\n      scrollableMap: {},\n    });\n    vi.spyOn(a11yTree, \"a11yForFrame\").mockResolvedValue({\n      outline: \"[1-10] div\",\n      urlMap: {},\n      scopeApplied: true,\n    } as AccessibilityTreeResult);\n    vi.spyOn(focusSelectors, \"resolveFocusFrameAndTail\").mockResolvedValue({\n      targetFrameId: \"frame-1\",\n      tailXPath: \"//div[1]\",\n      absPrefix: \"\",\n    });\n\n    const result = await tryScopedSnapshot(\n      makePage(session),\n      { focusSelector: \"xpath=//div\" },\n      context,\n      true,\n    );\n\n    expect(result).not.toBeNull();\n    expect(result?.combinedXpathMap[\"1-10\"]).toBe(\"/div[1]\");\n  });\n\n  it(\"logs and returns null when resolver throws\", async () => {\n    const session = new MockCDPSession({});\n    vi.spyOn(focusSelectors, \"resolveCssFocusFrameAndTail\").mockRejectedValue(\n      new Error(\"bad selector\"),\n    );\n    const loggerSpy = vi.spyOn(logger, \"v3Logger\").mockImplementation(() => {});\n\n    const result = await tryScopedSnapshot(\n      makePage(session),\n      { focusSelector: \".bad\" },\n      context,\n      true,\n    );\n\n    expect(result).toBeNull();\n    expect(loggerSpy).toHaveBeenCalled();\n  });\n});\n"]}

package/dist/esm/tests/unit/snapshot-a11y-tree-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/tests/unit/snapshot-a11y-tree-utils.test.js

@@ -0,0 +1,284 @@
+import { describe, expect, it } from "vitest";
+import { buildHierarchicalTree, decorateRoles, extractUrlFromAXNode, isStructural, removeRedundantStaticTextChildren, } from "../../lib/v3/understudy/a11y/snapshot/a11yTree.js";
+const axString = (value) => ({
+    type: "string",
+    value,
+});
+const defaultOpts = {
+    focusSelector: undefined,
+    experimental: false,
+    tagNameMap: {},
+    scrollableMap: {},
+    encode: (backendNodeId) => `enc-${backendNodeId}`,
+};
+const makeAxNode = (overrides = {}) => ({
+    nodeId: overrides.nodeId ?? String(Math.random()),
+    backendDOMNodeId: overrides.backendDOMNodeId ?? Math.floor(Math.random() * 1e6),
+    role: overrides.role ?? axString("generic"),
+    childIds: overrides.childIds ?? [],
+    parentId: overrides.parentId,
+    properties: overrides.properties ?? [],
+    name: overrides.name,
+    description: overrides.description,
+    value: overrides.value,
+    ignored: overrides.ignored ?? false,
+});
+describe("decorateRoles", () => {
+    it("marks scrollable DOM nodes with tag labels and encoded ids", () => {
+        const opts = {
+            ...defaultOpts,
+            tagNameMap: {
+                "enc-1": "div",
+                "enc-2": "html",
+                "enc-3": "#document",
+                "enc-4": "#svg",
+            },
+            scrollableMap: { "enc-1": true, "enc-4": true },
+        };
+        const nodes = [
+            makeAxNode({
+                backendDOMNodeId: 1,
+                role: { type: "string", value: "region" },
+            }),
+            makeAxNode({
+                backendDOMNodeId: 2,
+                role: { type: "string", value: "generic" },
+            }),
+            makeAxNode({
+                backendDOMNodeId: 3,
+                role: { type: "string", value: "generic" },
+            }),
+            makeAxNode({
+                backendDOMNodeId: 4,
+                role: { type: "string", value: "generic" },
+            }),
+        ];
+        const decorated = decorateRoles(nodes, opts);
+        expect(decorated).toMatchObject([
+            { encodedId: "enc-1", role: "scrollable, div" },
+            { encodedId: "enc-2", role: "scrollable, html" },
+            { encodedId: "enc-3", role: "generic" },
+            { encodedId: "enc-4", role: "scrollable, svg" },
+        ]);
+    });
+    it("falls back when encoding fails", () => {
+        const opts = {
+            ...defaultOpts,
+            encode: () => {
+                throw new Error("boom");
+            },
+        };
+        const nodes = [makeAxNode({ backendDOMNodeId: 4 })];
+        const decorated = decorateRoles(nodes, opts);
+        expect(decorated[0]?.encodedId).toBeUndefined();
+    });
+});
+describe("buildHierarchicalTree", () => {
+    const opts = {
+        ...defaultOpts,
+        tagNameMap: { root: "div", child: "span" },
+    };
+    it("drops structural nodes without children or names", async () => {
+        const nodes = [
+            {
+                role: "generic",
+                name: "",
+                nodeId: "root",
+                encodedId: "root",
+                parentId: undefined,
+                childIds: ["child"],
+            },
+            {
+                role: "generic",
+                name: "",
+                nodeId: "child",
+                encodedId: "child",
+                parentId: "root",
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, opts);
+        expect(tree).toEqual([]);
+    });
+    it("promotes select/combobox tag names for structural nodes", async () => {
+        const nodes = [
+            {
+                role: "combobox",
+                name: "Select",
+                nodeId: "root",
+                encodedId: "root",
+                parentId: undefined,
+                childIds: ["child"],
+            },
+            {
+                role: "StaticText",
+                name: "Option",
+                nodeId: "child",
+                encodedId: "child",
+                parentId: "root",
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, {
+            ...opts,
+            tagNameMap: { root: "select" },
+        });
+        expect(tree[0]?.role).toBe("select");
+    });
+    it("drops structural parents with a single cleaned child while keeping it in place", async () => {
+        const nodes = [
+            {
+                role: "generic",
+                name: "",
+                nodeId: "root",
+                encodedId: "root",
+                parentId: undefined,
+                childIds: ["child"],
+            },
+            {
+                role: "StaticText",
+                name: "Ok",
+                nodeId: "child",
+                encodedId: "child",
+                parentId: "root",
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, opts);
+        expect(tree[0]?.role).toBe("StaticText");
+    });
+    it("drops structural parents entirely when all descendants are pruned", async () => {
+        const nodes = [
+            {
+                role: "generic",
+                name: "",
+                nodeId: "root",
+                encodedId: "root",
+                parentId: undefined,
+                childIds: ["child"],
+            },
+            {
+                role: "generic",
+                name: "",
+                nodeId: "child",
+                encodedId: "child",
+                parentId: "root",
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, opts);
+        expect(tree).toEqual([]);
+    });
+    it("renames structural nodes to their tag names when not combobox", async () => {
+        const nodes = [
+            {
+                role: "generic",
+                name: "Container",
+                nodeId: "root",
+                encodedId: "root",
+                parentId: undefined,
+                childIds: ["child-a", "child-b"],
+            },
+            {
+                role: "StaticText",
+                name: "A",
+                nodeId: "child-a",
+                encodedId: "child-a",
+                parentId: "root",
+                childIds: [],
+            },
+            {
+                role: "StaticText",
+                name: "B",
+                nodeId: "child-b",
+                encodedId: "child-b",
+                parentId: "root",
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, {
+            ...opts,
+            tagNameMap: { root: "section" },
+        });
+        expect(tree[0]?.role).toBe("section");
+    });
+    it("skips nodes with negative node ids early", async () => {
+        const nodes = [
+            {
+                role: "button",
+                name: "Hidden",
+                nodeId: "-1",
+                encodedId: "hidden",
+                parentId: undefined,
+                childIds: [],
+            },
+        ];
+        const { tree } = await buildHierarchicalTree(nodes, opts);
+        expect(tree).toEqual([]);
+    });
+});
+describe("isStructural", () => {
+    it("marks generic/none/InlineTextBox roles as structural", () => {
+        expect(isStructural("generic")).toBe(true);
+        expect(isStructural("none")).toBe(true);
+        expect(isStructural("InlineTextBox")).toBe(true);
+        expect(isStructural("button")).toBe(false);
+    });
+});
+describe("removeRedundantStaticTextChildren", () => {
+    it("removes static text children whose concatenated text equals the parent name", () => {
+        const parent = {
+            role: "button",
+            name: "HelloWorld",
+            nodeId: "root",
+        };
+        const children = [
+            { role: "StaticText", name: "Hello", nodeId: "c1" },
+            { role: "StaticText", name: "World", nodeId: "c2" },
+            { role: "button", name: "Child", nodeId: "c3" },
+        ];
+        const pruned = removeRedundantStaticTextChildren(parent, children);
+        expect(pruned).toEqual([{ role: "button", name: "Child", nodeId: "c3" }]);
+    });
+    it("keeps static text when combined text differs", () => {
+        const parent = {
+            role: "button",
+            name: "Hello World",
+            nodeId: "root",
+        };
+        const children = [
+            { role: "StaticText", name: "Hello", nodeId: "c1" },
+            { role: "StaticText", name: "Mars", nodeId: "c2" },
+        ];
+        expect(removeRedundantStaticTextChildren(parent, children)).toEqual(children);
+    });
+    it("returns original children when parent name is empty", () => {
+        const parent = {
+            role: "button",
+            nodeId: "root",
+        };
+        const children = [
+            { role: "StaticText", name: "Hello", nodeId: "c1" },
+            { role: "StaticText", name: "World", nodeId: "c2" },
+        ];
+        expect(removeRedundantStaticTextChildren(parent, children)).toEqual(children);
+    });
+});
+describe("extractUrlFromAXNode", () => {
+    it("returns trimmed URL string from node properties", () => {
+        const node = makeAxNode({
+            properties: [
+                { name: "busy", value: axString("bar") },
+                { name: "url", value: axString(" https://example.com ") },
+            ],
+        });
+        expect(extractUrlFromAXNode(node)).toBe("https://example.com");
+    });
+    it("returns undefined when url property missing or invalid", () => {
+        expect(extractUrlFromAXNode(makeAxNode({ properties: [] }))).toBeUndefined();
+        expect(extractUrlFromAXNode(makeAxNode({
+            properties: [{ name: "url", value: { type: "number", value: 123 } }],
+        }))).toBeUndefined();
+    });
+});
+//# sourceMappingURL=snapshot-a11y-tree-utils.test.js.map