@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/cjs/tests/integration/page-extra-http-headers.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-extra-http-headers.spec.js","sourceRoot":"","sources":["../../../../tests/integration/page-extra-http-headers.spec.ts"],"names":[],"mappings":"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","sourcesContent":["import { test, expect } from \"@playwright/test\";\nimport type { Protocol } from \"devtools-protocol\";\nimport { V3 } from \"../../lib/v3/v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport { closeV3 } from \"./testUtils.js\";\n\nconst TEST_URL =\n  \"https://browserbase.github.io/stagehand-eval-sites/sites/example/\";\n\ntest.describe(\"page.setExtraHTTPHeaders\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3(v3TestConfig);\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await closeV3(v3);\n  });\n\n  test(\"applies headers to navigation requests\", async () => {\n    const ctx = v3.context;\n    const page = await ctx.awaitActivePage();\n\n    await page.setExtraHTTPHeaders({ \"x-page-header\": \"from-page\" });\n\n    const internal = page as unknown as {\n      mainSession: {\n        send: (method: string, params?: unknown) => Promise<unknown>;\n        on: (event: string, handler: (params: unknown) => void) => void;\n        off: (event: string, handler: (params: unknown) => void) => void;\n      };\n    };\n\n    await internal.mainSession.send(\"Network.enable\");\n\n    const requestPromise = new Promise<Protocol.Network.RequestWillBeSentEvent>(\n      (resolve, reject) => {\n        const timeout = setTimeout(() => {\n          internal.mainSession.off(\"Network.requestWillBeSent\", handler);\n          reject(new Error(\"Timed out waiting for request\"));\n        }, 5000);\n\n        const handler = (evt: Protocol.Network.RequestWillBeSentEvent) => {\n          if (evt.type !== \"Document\") return;\n          const url = String(evt.request?.url ?? \"\");\n          if (!url.startsWith(TEST_URL)) return;\n          clearTimeout(timeout);\n          internal.mainSession.off(\"Network.requestWillBeSent\", handler);\n          resolve(evt);\n        };\n\n        internal.mainSession.on(\"Network.requestWillBeSent\", handler);\n      },\n    );\n\n    await page.goto(TEST_URL, { waitUntil: \"domcontentloaded\" });\n\n    const request = await requestPromise;\n    const headers = Object.fromEntries(\n      Object.entries(request.request.headers ?? {}).map(([key, value]) => [\n        key.toLowerCase(),\n        String(value),\n      ]),\n    );\n\n    expect(headers[\"x-page-header\"]).toBe(\"from-page\");\n  });\n\n  test(\"updated headers replace previous ones\", async () => {\n    const ctx = v3.context;\n    const page = await ctx.awaitActivePage();\n\n    const internal = page as unknown as {\n      mainSession: {\n        send: (method: string, params?: unknown) => Promise<unknown>;\n        on: (event: string, handler: (params: unknown) => void) => void;\n        off: (event: string, handler: (params: unknown) => void) => void;\n      };\n    };\n\n    await internal.mainSession.send(\"Network.enable\");\n\n    // Set initial headers and navigate\n    await page.setExtraHTTPHeaders({ \"x-first\": \"yes\" });\n    await page.goto(TEST_URL, { waitUntil: \"domcontentloaded\" });\n\n    // Update headers\n    await page.setExtraHTTPHeaders({ \"x-second\": \"yes\" });\n\n    const requestPromise = new Promise<Protocol.Network.RequestWillBeSentEvent>(\n      (resolve, reject) => {\n        const timeout = setTimeout(() => {\n          internal.mainSession.off(\"Network.requestWillBeSent\", handler);\n          reject(new Error(\"Timed out waiting for request\"));\n        }, 5000);\n\n        const handler = (evt: Protocol.Network.RequestWillBeSentEvent) => {\n          if (evt.type !== \"Document\") return;\n          const url = String(evt.request?.url ?? \"\");\n          if (!url.startsWith(TEST_URL)) return;\n          clearTimeout(timeout);\n          internal.mainSession.off(\"Network.requestWillBeSent\", handler);\n          resolve(evt);\n        };\n\n        internal.mainSession.on(\"Network.requestWillBeSent\", handler);\n      },\n    );\n\n    await page.goto(TEST_URL, { waitUntil: \"domcontentloaded\" });\n\n    const request = await requestPromise;\n    const headers = Object.fromEntries(\n      Object.entries(request.request.headers ?? {}).map(([key, value]) => [\n        key.toLowerCase(),\n        String(value),\n      ]),\n    );\n\n    expect(headers[\"x-second\"]).toBe(\"yes\");\n    expect(headers[\"x-first\"]).toBeUndefined();\n  });\n});\n"]}

package/dist/cjs/tests/integration/page-goto-response.spec.d.ts

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

package/dist/cjs/tests/integration/page-goto-response.spec.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
+const v3_js_1 = require("../../lib/v3/v3.js");
+const v3_config_js_1 = require("./v3.config.js");
+test_1.test.describe("Page.goto() response surface", () => {
+    let v3;
+    test_1.test.beforeEach(async () => {
+        v3 = new v3_js_1.V3(v3_config_js_1.v3TestConfig);
+        await v3.init();
+    });
+    test_1.test.afterEach(async () => {
+        await v3?.close?.().catch(() => { });
+    });
+    (0, test_1.test)("returns a response object for network navigations", async () => {
+        const page = v3.context.pages()[0];
+        const response = await page.goto("https://example.com");
+        (0, test_1.expect)(response).not.toBeNull();
+        (0, test_1.expect)(response.status()).toBe(200);
+        (0, test_1.expect)(response.ok()).toBeTruthy();
+        const headers = await response.headersArray();
+        (0, test_1.expect)(headers.length).toBeGreaterThan(0);
+        const body = await response.text();
+        (0, test_1.expect)(body).toContain("Example Domain");
+        const finished = await response.finished();
+        (0, test_1.expect)(finished).toBeNull();
+    });
+    (0, test_1.test)("falls back to null for data URLs", async () => {
+        const page = v3.context.pages()[0];
+        const response = await page.goto("data:text/html,<html><body data-testid='fallback'>inline</body></html>");
+        (0, test_1.expect)(response).toBeNull();
+    });
+});
+//# sourceMappingURL=page-goto-response.spec.js.map

package/dist/cjs/tests/integration/page-goto-response.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-goto-response.spec.js","sourceRoot":"","sources":["../../../../tests/integration/page-goto-response.spec.ts"],"names":[],"mappings":";;AAAA,2CAAgD;AAChD,8CAAwC;AACxC,iDAA8C;AAE9C,WAAI,CAAC,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IACjD,IAAI,EAAM,CAAC;IAEX,WAAI,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE;QACzB,EAAE,GAAG,IAAI,UAAE,CAAC,2BAAY,CAAC,CAAC;QAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,WAAI,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE;QACxB,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,IAAA,WAAI,EAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAEnC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAExD,IAAA,aAAM,EAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAChC,IAAA,aAAM,EAAC,QAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,IAAA,aAAM,EAAC,QAAS,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;QAEpC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,CAAC;QAC9C,IAAA,aAAM,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAE1C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAA,aAAM,EAAC,IAAI,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAEzC,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC3C,IAAA,aAAM,EAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAI,EAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAClD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAEnC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAC9B,wEAAwE,CACzE,CAAC;QAEF,IAAA,aAAM,EAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { test, expect } from \"@playwright/test\";\nimport { V3 } from \"../../lib/v3/v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\n\ntest.describe(\"Page.goto() response surface\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3(v3TestConfig);\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"returns a response object for network navigations\", async () => {\n    const page = v3.context.pages()[0];\n\n    const response = await page.goto(\"https://example.com\");\n\n    expect(response).not.toBeNull();\n    expect(response!.status()).toBe(200);\n    expect(response!.ok()).toBeTruthy();\n\n    const headers = await response.headersArray();\n    expect(headers.length).toBeGreaterThan(0);\n\n    const body = await response.text();\n    expect(body).toContain(\"Example Domain\");\n\n    const finished = await response.finished();\n    expect(finished).toBeNull();\n  });\n\n  test(\"falls back to null for data URLs\", async () => {\n    const page = v3.context.pages()[0];\n\n    const response = await page.goto(\n      \"data:text/html,<html><body data-testid='fallback'>inline</body></html>\",\n    );\n\n    expect(response).toBeNull();\n  });\n});\n"]}

package/dist/cjs/tests/integration/page-hover.spec.d.ts

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

package/dist/cjs/tests/integration/page-hover.spec.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
+const v3_js_1 = require("../../lib/v3/v3.js");
+const v3_config_js_1 = require("./v3.config.js");
+test_1.test.describe("Page.hover() - mouse hover at coordinates", () => {
+    let v3;
+    test_1.test.beforeEach(async () => {
+        v3 = new v3_js_1.V3(v3_config_js_1.v3TestConfig);
+        await v3.init();
+    });
+    test_1.test.afterEach(async () => {
+        await v3?.close?.().catch(() => { });
+    });
+    (0, test_1.test)("hover triggers mouseover event at coordinates", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html><body style="margin: 0; padding: 0;">
+            <div id="target" 
+                 style="position: absolute; top: 100px; left: 100px; width: 200px; height: 200px; background: lightblue;"
+                 onmouseover="this.dataset.hovered='true'"
+                 onmouseout="this.dataset.hovered='false'">
+              Hover Me
+            </div>
+          </body></html>`));
+        // Check initial state
+        let hovered = await page.evaluate(() => {
+            const el = document.getElementById("target");
+            return el?.dataset.hovered === "true";
+        });
+        (0, test_1.expect)(hovered).toBe(false);
+        // Hover at coordinates within the target element (200, 200 is center of the div)
+        await page.hover(200, 200);
+        // Verify mouseover was triggered
+        hovered = await page.evaluate(() => {
+            const el = document.getElementById("target");
+            return el?.dataset.hovered === "true";
+        });
+        (0, test_1.expect)(hovered).toBe(true);
+    });
+    (0, test_1.test)("hover moves mouse without clicking", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html><body style="margin: 0; padding: 0;">
+            <button id="btn" 
+                    style="position: absolute; top: 100px; left: 100px; width: 200px; height: 100px;"
+                    onclick="this.dataset.clicked='true'"
+                    onmouseover="this.dataset.hovered='true'">
+              Click Me
+            </button>
+          </body></html>`));
+        // Hover over the button
+        await page.hover(200, 150);
+        // Check that hover happened but click did not
+        const state = await page.evaluate(() => {
+            const btn = document.getElementById("btn");
+            return {
+                hovered: btn?.dataset.hovered === "true",
+                clicked: btn?.dataset.clicked === "true",
+            };
+        });
+        (0, test_1.expect)(state.hovered).toBe(true);
+        (0, test_1.expect)(state.clicked).toBe(false);
+    });
+    (0, test_1.test)("hover returns xpath when requested", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html><body style="margin: 0; padding: 0;">
+            <div id="target" style="position: absolute; top: 0px; left: 400px; width: 300px; height: 100px; background: blue;">
+              Target element
+            </div>
+            <p style="position: absolute; top: 200px; left: 0px;">Content below</p>
+          </body></html>`));
+        // Hover at coordinate (550, 50) which should be directly over the target div
+        const xpath = await page.hover(550, 50, { returnXpath: true });
+        // Should return a non-empty xpath string for the element at that coordinate
+        (0, test_1.expect)(typeof xpath).toBe("string");
+        (0, test_1.expect)(xpath.length).toBeGreaterThan(0);
+        // Xpath should reference the div
+        (0, test_1.expect)(xpath.toLowerCase()).toMatch(/div|target/);
+    });
+    (0, test_1.test)("hover without returnXpath returns empty string", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html><body style="margin: 0; padding: 0;">
+            <div style="width: 100px; height: 100px; background: lightblue;">Content</div>
+          </body></html>`));
+        // Hover without returnXpath
+        const result = await page.hover(50, 50);
+        // Should return empty string
+        (0, test_1.expect)(result).toBe("");
+    });
+    (0, test_1.test)("hover triggers CSS :hover styles", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html>
+          <head>
+            <style>
+              #hoverable {
+                position: absolute;
+                top: 100px;
+                left: 100px;
+                width: 200px;
+                height: 200px;
+                background: red;
+              }
+              #hoverable:hover {
+                background: green;
+              }
+            </style>
+          </head>
+          <body style="margin: 0; padding: 0;">
+            <div id="hoverable">Hover to change color</div>
+          </body></html>`));
+        // Get initial background color
+        let bgColor = await page.evaluate(() => {
+            const el = document.getElementById("hoverable");
+            return getComputedStyle(el).backgroundColor;
+        });
+        (0, test_1.expect)(bgColor).toBe("rgb(255, 0, 0)"); // red
+        // Hover over the element
+        await page.hover(200, 200);
+        // Check that CSS :hover state is applied
+        bgColor = await page.evaluate(() => {
+            const el = document.getElementById("hoverable");
+            return getComputedStyle(el).backgroundColor;
+        });
+        (0, test_1.expect)(bgColor).toBe("rgb(0, 128, 0)"); // green
+    });
+    (0, test_1.test)("multiple hovers move the mouse correctly", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html," +
+            encodeURIComponent(`<!doctype html><html><body style="margin: 0; padding: 0;">
+            <div id="box1" 
+                 style="position: absolute; top: 0; left: 0; width: 100px; height: 100px; background: red;"
+                 onmouseover="this.dataset.hovered='true'"
+                 onmouseout="this.dataset.hovered='false'">
+              Box 1
+            </div>
+            <div id="box2" 
+                 style="position: absolute; top: 0; left: 200px; width: 100px; height: 100px; background: blue;"
+                 onmouseover="this.dataset.hovered='true'"
+                 onmouseout="this.dataset.hovered='false'">
+              Box 2
+            </div>
+          </body></html>`));
+        // Hover over box1
+        await page.hover(50, 50);
+        let state = await page.evaluate(() => ({
+            box1: document.getElementById("box1")?.dataset.hovered === "true",
+            box2: document.getElementById("box2")?.dataset.hovered === "true",
+        }));
+        (0, test_1.expect)(state.box1).toBe(true);
+        (0, test_1.expect)(state.box2).toBe(false);
+        // Move hover to box2
+        await page.hover(250, 50);
+        state = await page.evaluate(() => ({
+            box1: document.getElementById("box1")?.dataset.hovered === "true",
+            box2: document.getElementById("box2")?.dataset.hovered === "true",
+        }));
+        (0, test_1.expect)(state.box1).toBe(false);
+        (0, test_1.expect)(state.box2).toBe(true);
+    });
+});
+//# sourceMappingURL=page-hover.spec.js.map

package/dist/cjs/tests/integration/page-hover.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-hover.spec.js","sourceRoot":"","sources":["../../../../tests/integration/page-hover.spec.ts"],"names":[],"mappings":"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","sourcesContent":["import { test, expect } from \"@playwright/test\";\nimport { V3 } from \"../../lib/v3/v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\n\ntest.describe(\"Page.hover() - mouse hover at coordinates\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3(v3TestConfig);\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"hover triggers mouseover event at coordinates\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html><body style=\"margin: 0; padding: 0;\">\n            <div id=\"target\" \n                 style=\"position: absolute; top: 100px; left: 100px; width: 200px; height: 200px; background: lightblue;\"\n                 onmouseover=\"this.dataset.hovered='true'\"\n                 onmouseout=\"this.dataset.hovered='false'\">\n              Hover Me\n            </div>\n          </body></html>`,\n        ),\n    );\n\n    // Check initial state\n    let hovered = await page.evaluate(() => {\n      const el = document.getElementById(\"target\");\n      return el?.dataset.hovered === \"true\";\n    });\n    expect(hovered).toBe(false);\n\n    // Hover at coordinates within the target element (200, 200 is center of the div)\n    await page.hover(200, 200);\n\n    // Verify mouseover was triggered\n    hovered = await page.evaluate(() => {\n      const el = document.getElementById(\"target\");\n      return el?.dataset.hovered === \"true\";\n    });\n    expect(hovered).toBe(true);\n  });\n\n  test(\"hover moves mouse without clicking\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html><body style=\"margin: 0; padding: 0;\">\n            <button id=\"btn\" \n                    style=\"position: absolute; top: 100px; left: 100px; width: 200px; height: 100px;\"\n                    onclick=\"this.dataset.clicked='true'\"\n                    onmouseover=\"this.dataset.hovered='true'\">\n              Click Me\n            </button>\n          </body></html>`,\n        ),\n    );\n\n    // Hover over the button\n    await page.hover(200, 150);\n\n    // Check that hover happened but click did not\n    const state = await page.evaluate(() => {\n      const btn = document.getElementById(\"btn\");\n      return {\n        hovered: btn?.dataset.hovered === \"true\",\n        clicked: btn?.dataset.clicked === \"true\",\n      };\n    });\n\n    expect(state.hovered).toBe(true);\n    expect(state.clicked).toBe(false);\n  });\n\n  test(\"hover returns xpath when requested\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html><body style=\"margin: 0; padding: 0;\">\n            <div id=\"target\" style=\"position: absolute; top: 0px; left: 400px; width: 300px; height: 100px; background: blue;\">\n              Target element\n            </div>\n            <p style=\"position: absolute; top: 200px; left: 0px;\">Content below</p>\n          </body></html>`,\n        ),\n    );\n\n    // Hover at coordinate (550, 50) which should be directly over the target div\n    const xpath = await page.hover(550, 50, { returnXpath: true });\n\n    // Should return a non-empty xpath string for the element at that coordinate\n    expect(typeof xpath).toBe(\"string\");\n    expect(xpath.length).toBeGreaterThan(0);\n    // Xpath should reference the div\n    expect(xpath.toLowerCase()).toMatch(/div|target/);\n  });\n\n  test(\"hover without returnXpath returns empty string\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html><body style=\"margin: 0; padding: 0;\">\n            <div style=\"width: 100px; height: 100px; background: lightblue;\">Content</div>\n          </body></html>`,\n        ),\n    );\n\n    // Hover without returnXpath\n    const result = await page.hover(50, 50);\n\n    // Should return empty string\n    expect(result).toBe(\"\");\n  });\n\n  test(\"hover triggers CSS :hover styles\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html>\n          <head>\n            <style>\n              #hoverable {\n                position: absolute;\n                top: 100px;\n                left: 100px;\n                width: 200px;\n                height: 200px;\n                background: red;\n              }\n              #hoverable:hover {\n                background: green;\n              }\n            </style>\n          </head>\n          <body style=\"margin: 0; padding: 0;\">\n            <div id=\"hoverable\">Hover to change color</div>\n          </body></html>`,\n        ),\n    );\n\n    // Get initial background color\n    let bgColor = await page.evaluate(() => {\n      const el = document.getElementById(\"hoverable\");\n      return getComputedStyle(el!).backgroundColor;\n    });\n    expect(bgColor).toBe(\"rgb(255, 0, 0)\"); // red\n\n    // Hover over the element\n    await page.hover(200, 200);\n\n    // Check that CSS :hover state is applied\n    bgColor = await page.evaluate(() => {\n      const el = document.getElementById(\"hoverable\");\n      return getComputedStyle(el!).backgroundColor;\n    });\n    expect(bgColor).toBe(\"rgb(0, 128, 0)\"); // green\n  });\n\n  test(\"multiple hovers move the mouse correctly\", async () => {\n    const page = v3.context.pages()[0];\n\n    await page.goto(\n      \"data:text/html,\" +\n        encodeURIComponent(\n          `<!doctype html><html><body style=\"margin: 0; padding: 0;\">\n            <div id=\"box1\" \n                 style=\"position: absolute; top: 0; left: 0; width: 100px; height: 100px; background: red;\"\n                 onmouseover=\"this.dataset.hovered='true'\"\n                 onmouseout=\"this.dataset.hovered='false'\">\n              Box 1\n            </div>\n            <div id=\"box2\" \n                 style=\"position: absolute; top: 0; left: 200px; width: 100px; height: 100px; background: blue;\"\n                 onmouseover=\"this.dataset.hovered='true'\"\n                 onmouseout=\"this.dataset.hovered='false'\">\n              Box 2\n            </div>\n          </body></html>`,\n        ),\n    );\n\n    // Hover over box1\n    await page.hover(50, 50);\n\n    let state = await page.evaluate(() => ({\n      box1: document.getElementById(\"box1\")?.dataset.hovered === \"true\",\n      box2: document.getElementById(\"box2\")?.dataset.hovered === \"true\",\n    }));\n\n    expect(state.box1).toBe(true);\n    expect(state.box2).toBe(false);\n\n    // Move hover to box2\n    await page.hover(250, 50);\n\n    state = await page.evaluate(() => ({\n      box1: document.getElementById(\"box1\")?.dataset.hovered === \"true\",\n      box2: document.getElementById(\"box2\")?.dataset.hovered === \"true\",\n    }));\n\n    expect(state.box1).toBe(false);\n    expect(state.box2).toBe(true);\n  });\n});\n"]}

package/dist/cjs/tests/integration/page-screenshot.spec.d.ts

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

package/dist/cjs/tests/integration/page-screenshot.spec.js

@@ -0,0 +1,292 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
+const fs_1 = require("fs");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const v3_js_1 = require("../../lib/v3/v3.js");
+const v3_config_js_1 = require("./v3.config.js");
+const frame_js_1 = require("../../lib/v3/understudy/frame.js");
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+test_1.test.describe("Page.screenshot options", () => {
+    let v3;
+    test_1.test.beforeEach(async () => {
+        v3 = new v3_js_1.V3(v3_config_js_1.v3TestConfig);
+        await v3.init();
+    });
+    test_1.test.afterEach(async () => {
+        await v3?.close?.().catch(() => { });
+    });
+    (0, test_1.test)("rejects clip combined with fullPage", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html,<html><body>test</body></html>");
+        await (0, test_1.expect)(page.screenshot({
+            fullPage: true,
+            clip: { x: 0, y: 0, width: 100, height: 100 },
+        })).rejects.toThrow(/clip and fullPage/);
+    });
+    (0, test_1.test)("rejects unsupported image type", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html,<html><body>noop</body></html>");
+        await (0, test_1.expect)(page.screenshot({
+            // @ts-expect-error intentional invalid type for runtime validation
+            type: "webp",
+        })).rejects.toThrow(/unsupported image type/);
+    });
+    (0, test_1.test)("rejects jpeg quality for png screenshots", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html,<html><body>noop</body></html>");
+        await (0, test_1.expect)(page.screenshot({ type: "png", quality: 50 })).rejects.toThrow(/quality option is only valid/);
+    });
+    (0, test_1.test)("honours timeout option", async () => {
+        const page = v3.context.pages()[0];
+        await page.goto("data:text/html,<html><body>noop</body></html>");
+        const mainFrame = page.mainFrame();
+        const originalScreenshot = mainFrame.screenshot.bind(mainFrame);
+        mainFrame.screenshot = async () => {
+            await wait(50);
+            return Buffer.from("late");
+        };
+        try {
+            await (0, test_1.expect)(page.screenshot({ timeout: 10 })).rejects.toThrow(/timed out|timeout/i);
+        }
+        finally {
+            mainFrame.screenshot = originalScreenshot;
+        }
+    });
+    (0, test_1.test)("applies advanced options and cleans up overlays", async () => {
+        const page = v3.context.pages()[0];
+        const screenshotTimeout = process.env.CI ? 15000 : 5000;
+        const testStart = Date.now();
+        console.log(`[screenshot-test] start ${new Date(testStart).toISOString()} timeout=${screenshotTimeout}`);
+        const html = `
+      <!doctype html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <style>
+            body { background: #aaccee; margin: 0; height: 100vh; display: flex; flex-direction: column; align-items: flex-start; }
+            .mask-target { width: 80px; height: 80px; margin: 40px; background: rgb(0, 180, 60); animation: pulse 1s infinite alternate; }
+            @keyframes pulse { from { transform: scale(1); } to { transform: scale(1.2); } }
+          </style>
+        </head>
+        <body>
+          <div class="mask-target"></div>
+          <div class="mask-target"></div>
+          <input id="focus-me" value="focus" />
+          <script>document.getElementById('focus-me').focus();</script>
+        </body>
+      </html>
+    `;
+        await page.goto("data:text/html," + encodeURIComponent(html));
+        console.log(`[screenshot-test] page loaded in ${Date.now() - testStart}ms`);
+        const maskLocator = page.locator(".mask-target");
+        const tempPath = path.join(os.tmpdir(), `stagehand-screenshot-${Date.now()}-${Math.random().toString(36).slice(2)}.jpeg`);
+        console.log(`[screenshot-test] tempPath=${tempPath}`);
+        const targetId = page.targetId();
+        const screenshotCalls = [];
+        const evaluateCalls = [];
+        const originalScreenshot = frame_js_1.Frame.prototype.screenshot;
+        const originalEvaluate = frame_js_1.Frame.prototype.evaluate;
+        // Hook Frame.screenshot so we can assert which options reach CDP without writing real data.
+        frame_js_1.Frame.prototype.screenshot = async function screenshotSpy(options) {
+            const frame = this;
+            if (frame.pageId === targetId) {
+                screenshotCalls.push({ frameId: frame.frameId, options });
+                return Buffer.from("stub-image");
+            }
+            return originalScreenshot.call(this, options);
+        };
+        // Spy on Frame.evaluate to capture the arguments used to inject CSS/masks.
+        frame_js_1.Frame.prototype.evaluate = async function evaluateSpy(expression, arg) {
+            const frame = this;
+            if (frame.pageId === targetId) {
+                evaluateCalls.push({ frameId: frame.frameId, arg });
+            }
+            return originalEvaluate.call(this, expression, arg);
+        };
+        const internalPage = page;
+        const sendCalls = [];
+        const originalSend = internalPage.mainSession.send.bind(internalPage.mainSession);
+        // Capture background overrides so we can confirm omitBackground toggles on/off.
+        internalPage.mainSession.send = async (method, params) => {
+            sendCalls.push({ method, params });
+            return originalSend(method, params);
+        };
+        try {
+            const maskCount = await maskLocator.count();
+            console.log(`[screenshot-test] maskLocator.count=${maskCount}`);
+            const buffer = await page.screenshot({
+                animations: "disabled",
+                caret: "hide",
+                clip: { x: 0, y: 0, width: 200, height: 200 },
+                mask: [maskLocator],
+                maskColor: "rgba(255, 0, 0, 0.4)",
+                omitBackground: true,
+                path: tempPath,
+                quality: 80,
+                scale: "css",
+                style: "body { border: 3px solid black; }",
+                timeout: screenshotTimeout,
+                type: "jpeg",
+            });
+            console.log(`[screenshot-test] screenshot returned bytes=${buffer.length} elapsed=${Date.now() - testStart}ms`);
+            (0, test_1.expect)(Buffer.isBuffer(buffer)).toBeTruthy();
+            (0, test_1.expect)(screenshotCalls.length).toBeGreaterThanOrEqual(1);
+            console.log(`[screenshot-test] screenshotCalls=${screenshotCalls.length} evaluateCalls=${evaluateCalls.length} sendCalls=${sendCalls.length}`);
+            const recorded = screenshotCalls[0]?.options ?? {};
+            (0, test_1.expect)(recorded).toMatchObject({ type: "jpeg", quality: 80 });
+            (0, test_1.expect)(recorded?.clip).toMatchObject({
+                x: 0,
+                y: 0,
+                width: 200,
+                height: 200,
+            });
+            if (typeof recorded?.scale === "number") {
+                (0, test_1.expect)(recorded.scale).toBeGreaterThan(0);
+                (0, test_1.expect)(recorded.scale).toBeLessThanOrEqual(2);
+            }
+            await fs_1.promises.stat(tempPath);
+            const maskNodes = await page.evaluate(() => document.querySelectorAll("[data-stagehand-mask]").length);
+            (0, test_1.expect)(maskNodes).toBe(0);
+            const styleNodes = await page.evaluate(() => document.querySelectorAll("[data-stagehand-style]").length);
+            (0, test_1.expect)(styleNodes).toBe(0);
+            const backgroundCalls = sendCalls.filter((call) => call.method === "Emulation.setDefaultBackgroundColorOverride");
+            (0, test_1.expect)(backgroundCalls.length).toBeGreaterThan(1);
+            (0, test_1.expect)(backgroundCalls.some((call) => call.params &&
+                typeof call.params === "object" &&
+                "color" in call.params)).toBeTruthy();
+            (0, test_1.expect)(backgroundCalls.some((call) => !call.params ||
+                Object.keys(call.params).length === 0)).toBeTruthy();
+            const cssArgs = evaluateCalls
+                .map((entry) => {
+                const value = entry.arg;
+                return value?.css ?? null;
+            })
+                .filter((css) => typeof css === "string");
+            const tokens = evaluateCalls
+                .map((entry) => {
+                const arg = entry.arg;
+                return arg?.token ?? null;
+            })
+                .filter((token) => typeof token === "string");
+            // Tokens include which helper injected the style (animations/caret/custom).
+            (0, test_1.expect)(tokens.some((token) => token.includes("animations"))).toBeTruthy();
+            (0, test_1.expect)(tokens.some((token) => token.includes("caret"))).toBeTruthy();
+            (0, test_1.expect)(tokens.some((token) => token.includes("custom"))).toBeTruthy();
+            // Custom style should bubble through so we check the actual CSS text.
+            (0, test_1.expect)(cssArgs.some((css) => css.includes("border: 3px solid black"))).toBeTruthy();
+            const maskCalls = evaluateCalls.filter((entry) => {
+                const arg = entry.arg;
+                return (arg &&
+                    typeof arg === "object" &&
+                    "rects" in arg);
+            });
+            (0, test_1.expect)(maskCalls.length).toBeGreaterThan(0);
+            const rects = maskCalls[0]?.arg
+                ?.rects;
+            (0, test_1.expect)(Array.isArray(rects)).toBeTruthy();
+            (0, test_1.expect)(rects.length).toBe(2);
+        }
+        finally {
+            frame_js_1.Frame.prototype.screenshot = originalScreenshot;
+            frame_js_1.Frame.prototype.evaluate = originalEvaluate;
+            internalPage.mainSession.send = originalSend;
+            await fs_1.promises.unlink(tempPath).catch(() => { });
+        }
+    });
+    (0, test_1.test)("masks elements inside dialog top layer", async () => {
+        const page = v3.context.pages()[0];
+        const html = `
+      <!doctype html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <style>
+            dialog { padding: 16px; border: 2px solid #444; }
+            #dialog-input { display: block; width: 160px; height: 32px; }
+          </style>
+        </head>
+        <body>
+          <dialog id="dialog">
+            <label>Secret <input id="dialog-input" value="top-layer" /></label>
+          </dialog>
+          <script>
+            const dialog = document.getElementById("dialog");
+            if (dialog) {
+              if (typeof dialog.showModal === "function") {
+                try {
+                  dialog.showModal();
+                } catch {
+                  dialog.setAttribute("open", "");
+                }
+              } else {
+                dialog.setAttribute("open", "");
+              }
+            }
+          </script>
+        </body>
+      </html>
+    `;
+        await page.goto("data:text/html," + encodeURIComponent(html));
+        const targetId = page.targetId();
+        const originalScreenshot = frame_js_1.Frame.prototype.screenshot;
+        let dialogMaskCount = 0;
+        frame_js_1.Frame.prototype.screenshot = async function screenshotSpy(options) {
+            const frame = this;
+            if (frame.pageId === targetId) {
+                dialogMaskCount = await frame.evaluate(() => {
+                    const dialog = document.querySelector("dialog[open]");
+                    if (!dialog)
+                        return 0;
+                    return dialog.querySelectorAll("[data-stagehand-mask]").length;
+                });
+                return Buffer.from("stub-image");
+            }
+            return originalScreenshot.call(this, options);
+        };
+        try {
+            await page.screenshot({
+                mask: [page.locator("#dialog-input")],
+            });
+            (0, test_1.expect)(dialogMaskCount).toBeGreaterThan(0);
+        }
+        finally {
+            frame_js_1.Frame.prototype.screenshot = originalScreenshot;
+        }
+    });
+});
+//# sourceMappingURL=page-screenshot.spec.js.map

package/dist/cjs/tests/integration/page-screenshot.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-screenshot.spec.js","sourceRoot":"","sources":["../../../../tests/integration/page-screenshot.spec.ts"],"names":[],"mappings":"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","sourcesContent":["import { test, expect } from \"@playwright/test\";\nimport { promises as fs } from \"fs\";\nimport * as os from \"os\";\nimport * as path from \"path\";\nimport { V3 } from \"../../lib/v3/v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport { Frame } from \"../../lib/v3/understudy/frame.js\";\n\nconst wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));\n\ntest.describe(\"Page.screenshot options\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3(v3TestConfig);\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"rejects clip combined with fullPage\", async () => {\n    const page = v3.context.pages()[0];\n    await page.goto(\"data:text/html,<html><body>test</body></html>\");\n\n    await expect(\n      page.screenshot({\n        fullPage: true,\n        clip: { x: 0, y: 0, width: 100, height: 100 },\n      }),\n    ).rejects.toThrow(/clip and fullPage/);\n  });\n\n  test(\"rejects unsupported image type\", async () => {\n    const page = v3.context.pages()[0];\n    await page.goto(\"data:text/html,<html><body>noop</body></html>\");\n\n    await expect(\n      page.screenshot({\n        // @ts-expect-error intentional invalid type for runtime validation\n        type: \"webp\",\n      }),\n    ).rejects.toThrow(/unsupported image type/);\n  });\n\n  test(\"rejects jpeg quality for png screenshots\", async () => {\n    const page = v3.context.pages()[0];\n    await page.goto(\"data:text/html,<html><body>noop</body></html>\");\n\n    await expect(page.screenshot({ type: \"png\", quality: 50 })).rejects.toThrow(\n      /quality option is only valid/,\n    );\n  });\n\n  test(\"honours timeout option\", async () => {\n    const page = v3.context.pages()[0];\n    await page.goto(\"data:text/html,<html><body>noop</body></html>\");\n\n    const mainFrame = page.mainFrame();\n    const originalScreenshot = mainFrame.screenshot.bind(mainFrame);\n\n    (\n      mainFrame as typeof mainFrame & {\n        screenshot: typeof mainFrame.screenshot;\n      }\n    ).screenshot = async () => {\n      await wait(50);\n      return Buffer.from(\"late\");\n    };\n\n    try {\n      await expect(page.screenshot({ timeout: 10 })).rejects.toThrow(\n        /timed out|timeout/i,\n      );\n    } finally {\n      (\n        mainFrame as typeof mainFrame & {\n          screenshot: typeof mainFrame.screenshot;\n        }\n      ).screenshot = originalScreenshot;\n    }\n  });\n\n  test(\"applies advanced options and cleans up overlays\", async () => {\n    const page = v3.context.pages()[0];\n    const screenshotTimeout = process.env.CI ? 15000 : 5000;\n    const testStart = Date.now();\n    console.log(\n      `[screenshot-test] start ${new Date(testStart).toISOString()} timeout=${screenshotTimeout}`,\n    );\n\n    const html = `\n      <!doctype html>\n      <html>\n        <head>\n          <meta charset=\"utf-8\" />\n          <style>\n            body { background: #aaccee; margin: 0; height: 100vh; display: flex; flex-direction: column; align-items: flex-start; }\n            .mask-target { width: 80px; height: 80px; margin: 40px; background: rgb(0, 180, 60); animation: pulse 1s infinite alternate; }\n            @keyframes pulse { from { transform: scale(1); } to { transform: scale(1.2); } }\n          </style>\n        </head>\n        <body>\n          <div class=\"mask-target\"></div>\n          <div class=\"mask-target\"></div>\n          <input id=\"focus-me\" value=\"focus\" />\n          <script>document.getElementById('focus-me').focus();</script>\n        </body>\n      </html>\n    `;\n\n    await page.goto(\"data:text/html,\" + encodeURIComponent(html));\n    console.log(`[screenshot-test] page loaded in ${Date.now() - testStart}ms`);\n\n    const maskLocator = page.locator(\".mask-target\");\n    const tempPath = path.join(\n      os.tmpdir(),\n      `stagehand-screenshot-${Date.now()}-${Math.random().toString(36).slice(2)}.jpeg`,\n    );\n    console.log(`[screenshot-test] tempPath=${tempPath}`);\n\n    const targetId = page.targetId();\n    const screenshotCalls: Array<{\n      frameId: string;\n      options: Parameters<Frame[\"screenshot\"]>[0];\n    }> = [];\n    const evaluateCalls: Array<{ frameId: string; arg: unknown }> = [];\n    const originalScreenshot = Frame.prototype.screenshot;\n    const originalEvaluate = Frame.prototype.evaluate;\n\n    // Hook Frame.screenshot so we can assert which options reach CDP without writing real data.\n    Frame.prototype.screenshot = async function screenshotSpy(options) {\n      const frame = this as Frame;\n      if (frame.pageId === targetId) {\n        screenshotCalls.push({ frameId: frame.frameId, options });\n        return Buffer.from(\"stub-image\");\n      }\n      return originalScreenshot.call(this, options);\n    };\n\n    // Spy on Frame.evaluate to capture the arguments used to inject CSS/masks.\n    Frame.prototype.evaluate = async function evaluateSpy(expression, arg?) {\n      const frame = this as Frame;\n      if (frame.pageId === targetId) {\n        evaluateCalls.push({ frameId: frame.frameId, arg });\n      }\n      return originalEvaluate.call(this, expression as never, arg);\n    } as Frame[\"evaluate\"];\n\n    const internalPage = page as unknown as {\n      mainSession: {\n        send: (method: string, params?: unknown) => Promise<unknown>;\n      };\n    };\n    const sendCalls: Array<{ method: string; params: unknown }> = [];\n    const originalSend = internalPage.mainSession.send.bind(\n      internalPage.mainSession,\n    ) as (method: string, params?: unknown) => Promise<unknown>;\n    // Capture background overrides so we can confirm omitBackground toggles on/off.\n    internalPage.mainSession.send = async (\n      method: string,\n      params?: unknown,\n    ) => {\n      sendCalls.push({ method, params });\n      return originalSend(method, params);\n    };\n\n    try {\n      const maskCount = await maskLocator.count();\n      console.log(`[screenshot-test] maskLocator.count=${maskCount}`);\n\n      const buffer = await page.screenshot({\n        animations: \"disabled\",\n        caret: \"hide\",\n        clip: { x: 0, y: 0, width: 200, height: 200 },\n        mask: [maskLocator],\n        maskColor: \"rgba(255, 0, 0, 0.4)\",\n        omitBackground: true,\n        path: tempPath,\n        quality: 80,\n        scale: \"css\",\n        style: \"body { border: 3px solid black; }\",\n        timeout: screenshotTimeout,\n        type: \"jpeg\",\n      });\n      console.log(\n        `[screenshot-test] screenshot returned bytes=${buffer.length} elapsed=${Date.now() - testStart}ms`,\n      );\n\n      expect(Buffer.isBuffer(buffer)).toBeTruthy();\n      expect(screenshotCalls.length).toBeGreaterThanOrEqual(1);\n      console.log(\n        `[screenshot-test] screenshotCalls=${screenshotCalls.length} evaluateCalls=${evaluateCalls.length} sendCalls=${sendCalls.length}`,\n      );\n      const recorded = screenshotCalls[0]?.options ?? {};\n      expect(recorded).toMatchObject({ type: \"jpeg\", quality: 80 });\n      expect(recorded?.clip).toMatchObject({\n        x: 0,\n        y: 0,\n        width: 200,\n        height: 200,\n      });\n      if (typeof recorded?.scale === \"number\") {\n        expect(recorded.scale).toBeGreaterThan(0);\n        expect(recorded.scale).toBeLessThanOrEqual(2);\n      }\n\n      await fs.stat(tempPath);\n\n      const maskNodes = await page.evaluate(\n        () => document.querySelectorAll(\"[data-stagehand-mask]\").length,\n      );\n      expect(maskNodes).toBe(0);\n\n      const styleNodes = await page.evaluate(\n        () => document.querySelectorAll(\"[data-stagehand-style]\").length,\n      );\n      expect(styleNodes).toBe(0);\n\n      const backgroundCalls = sendCalls.filter(\n        (call) => call.method === \"Emulation.setDefaultBackgroundColorOverride\",\n      );\n      expect(backgroundCalls.length).toBeGreaterThan(1);\n      expect(\n        backgroundCalls.some(\n          (call) =>\n            call.params &&\n            typeof call.params === \"object\" &&\n            \"color\" in (call.params as Record<string, unknown>),\n        ),\n      ).toBeTruthy();\n      expect(\n        backgroundCalls.some(\n          (call) =>\n            !call.params ||\n            Object.keys(call.params as Record<string, unknown>).length === 0,\n        ),\n      ).toBeTruthy();\n\n      const cssArgs = evaluateCalls\n        .map((entry) => {\n          const value = entry.arg as { css?: string } | undefined;\n          return value?.css ?? null;\n        })\n        .filter((css): css is string => typeof css === \"string\");\n\n      const tokens = evaluateCalls\n        .map((entry) => {\n          const arg = entry.arg as { token?: string } | undefined;\n          return arg?.token ?? null;\n        })\n        .filter((token): token is string => typeof token === \"string\");\n\n      // Tokens include which helper injected the style (animations/caret/custom).\n      expect(tokens.some((token) => token.includes(\"animations\"))).toBeTruthy();\n      expect(tokens.some((token) => token.includes(\"caret\"))).toBeTruthy();\n      expect(tokens.some((token) => token.includes(\"custom\"))).toBeTruthy();\n      // Custom style should bubble through so we check the actual CSS text.\n      expect(\n        cssArgs.some((css) => css.includes(\"border: 3px solid black\")),\n      ).toBeTruthy();\n\n      const maskCalls = evaluateCalls.filter((entry) => {\n        const arg = entry.arg;\n        return (\n          arg &&\n          typeof arg === \"object\" &&\n          \"rects\" in (arg as Record<string, unknown>)\n        );\n      });\n      expect(maskCalls.length).toBeGreaterThan(0);\n      const rects = (maskCalls[0]?.arg as { rects?: unknown } | undefined)\n        ?.rects;\n      expect(Array.isArray(rects)).toBeTruthy();\n      expect((rects as unknown[]).length).toBe(2);\n    } finally {\n      Frame.prototype.screenshot = originalScreenshot;\n      Frame.prototype.evaluate = originalEvaluate;\n      internalPage.mainSession.send = originalSend;\n      await fs.unlink(tempPath).catch(() => {});\n    }\n  });\n\n  test(\"masks elements inside dialog top layer\", async () => {\n    const page = v3.context.pages()[0];\n\n    const html = `\n      <!doctype html>\n      <html>\n        <head>\n          <meta charset=\"utf-8\" />\n          <style>\n            dialog { padding: 16px; border: 2px solid #444; }\n            #dialog-input { display: block; width: 160px; height: 32px; }\n          </style>\n        </head>\n        <body>\n          <dialog id=\"dialog\">\n            <label>Secret <input id=\"dialog-input\" value=\"top-layer\" /></label>\n          </dialog>\n          <script>\n            const dialog = document.getElementById(\"dialog\");\n            if (dialog) {\n              if (typeof dialog.showModal === \"function\") {\n                try {\n                  dialog.showModal();\n                } catch {\n                  dialog.setAttribute(\"open\", \"\");\n                }\n              } else {\n                dialog.setAttribute(\"open\", \"\");\n              }\n            }\n          </script>\n        </body>\n      </html>\n    `;\n\n    await page.goto(\"data:text/html,\" + encodeURIComponent(html));\n\n    const targetId = page.targetId();\n    const originalScreenshot = Frame.prototype.screenshot;\n    let dialogMaskCount = 0;\n\n    Frame.prototype.screenshot = async function screenshotSpy(options) {\n      const frame = this as Frame;\n      if (frame.pageId === targetId) {\n        dialogMaskCount = await frame.evaluate(() => {\n          const dialog = document.querySelector(\"dialog[open]\");\n          if (!dialog) return 0;\n          return dialog.querySelectorAll(\"[data-stagehand-mask]\").length;\n        });\n        return Buffer.from(\"stub-image\");\n      }\n      return originalScreenshot.call(this, options);\n    };\n\n    try {\n      await page.screenshot({\n        mask: [page.locator(\"#dialog-input\")],\n      });\n      expect(dialogMaskCount).toBeGreaterThan(0);\n    } finally {\n      Frame.prototype.screenshot = originalScreenshot;\n    }\n  });\n});\n"]}

package/dist/cjs/tests/integration/page-scroll.spec.d.ts

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