@empiricalrun/playwright-utils 0.20.14 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @empiricalrun/playwright-utils
 
+## 0.21.1
+
+### Patch Changes
+
+- d2513a2: fix: don't save screenshot to disk for visual assertions
+- 1ff54e7: fix: use CSS.escape for overlay text content and wrap in try-catch
+
+## 0.21.0
+
+### Minor Changes
+
+- 0622b6e: feat: add custom expect for visual usability assertions
+
 ## 0.20.14
 
 ### Patch Changes

package/dist/test/expect.d.ts

@@ -0,0 +1,7 @@
+import type { Page } from "@playwright/test";
+export type VisualMatcherResult = {
+    message: () => string;
+    pass: boolean;
+};
+export declare function toLookRight(page: Page, pageDescription: string): Promise<VisualMatcherResult>;
+//# sourceMappingURL=expect.d.ts.map

package/dist/test/expect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/test/expect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAO7C,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AA0BF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,mBAAmB,CAAC,CA4E9B"}

package/dist/test/expect.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLookRight = void 0;
+const llm_1 = require("@empiricalrun/llm");
+const vision_1 = require("@empiricalrun/llm/vision");
+const mouse_pointer_1 = require("./scripts/mouse-pointer");
+const SYSTEM_PROMPT = `
+You are a software QA tester who specializes in visual testing. You look at a
+UI screenshot and evaluate whether the UI is rendered correctly. While you don't
+have a reference design for it, you can use the page description that is provided
+to you to evaluate the UI.
+
+There are signs when a UI is not rendered correctly. UI elements are overlapping
+each other, text is cut off, or the UI components are not aligned. Margins are
+uneven, or the UI components are not spaced correctly.
+
+You need to ensure that the UI is rendered correctly. Among other things, you
+should check the following:
+- The page must be coherent. For example, the title of the page should be consistent
+with the content.
+- The page should not have large empty white/gray areas. These indicate UI layout
+issues or page loading bugs.
+- Images and other media on the page should be aligned and sized correctly.
+- The page should have legible text that is easy to read.
+- The page should not have popups or UI elements that are blocking the content.
+
+You are to respond to your visual evaluation with a Pass or Fail, and provide
+a reason for your evaluation.
+`;
+async function toLookRight(page, pageDescription) {
+    await (0, mouse_pointer_1.removeMousePointerHighlighter)(page);
+    const screenshot = await page.screenshot();
+    const base64Image = screenshot.toString("base64");
+    await (0, mouse_pointer_1.addHighlighterScriptsToPage)(page);
+    const llm = new llm_1.LLM({
+        provider: "openai",
+        defaultModel: "gpt-4o",
+    });
+    const response = await llm.createChatCompletion({
+        messages: [
+            {
+                role: "system",
+                content: SYSTEM_PROMPT,
+            },
+            {
+                role: "user",
+                content: [
+                    {
+                        type: "text",
+                        text: "Page description:\n" + pageDescription,
+                    },
+                    {
+                        type: "image_url",
+                        image_url: {
+                            url: (0, vision_1.imageFormatForProvider)("anthropic", base64Image),
+                        },
+                    },
+                ],
+            },
+        ],
+        modelParameters: {
+            temperature: 0.1,
+            tool_choice: {
+                type: "function",
+                function: { name: "send_response" },
+            },
+        },
+        tools: [
+            {
+                type: "function",
+                function: {
+                    name: "send_response",
+                    description: "Send your response after evaluating the image",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            reason: {
+                                type: "string",
+                                description: "Reasoning for the evaluation, shared as a step-by-step chain of thought.",
+                            },
+                            result: { type: "string", enum: ["Pass", "Fail"] },
+                            most_critical_reason: {
+                                type: "string",
+                                description: `
+Pick the most critical reason for your evaluation. For example, if you chose Fail as the result,
+go through the reasons and pick the one that made you choose Fail`,
+                            },
+                        },
+                        required: ["reason", "result", "most_critical_reason"],
+                    },
+                },
+            },
+        ],
+    });
+    const rawResponse = response.tool_calls[0];
+    const result = JSON.parse(rawResponse.function.arguments);
+    return {
+        message: () => result.most_critical_reason,
+        pass: result.result === "Pass",
+    };
+}
+exports.toLookRight = toLookRight;

package/dist/test/index.d.ts

@@ -1,6 +1,15 @@
 import type { BrowserContext, BrowserContextOptions, Page, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from "@playwright/test";
+import { expect } from "@playwright/test";
 import { injectLocatorHighlightScripts } from "./scripts";
 import { HighlighterOpts } from "./types";
+declare global {
+    namespace PlaywrightTest {
+        interface Matchers<R> {
+            toLookRight(description: string): Promise<R>;
+        }
+    }
+}
+declare const extendExpect: (expectInstance: typeof expect) => import("@playwright/test").Expect<{}>;
 type TestOptions = {
     page: Page;
     customContextPageProvider: (options?: BrowserContextOptions) => Promise<{
@@ -9,6 +18,6 @@ type TestOptions = {
     }>;
     saveVideos: void;
 };
-export declare const baseTestFixture: (testFn: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>, options?: HighlighterOpts) => TestType<PlaywrightTestArgs & PlaywrightTestOptions & TestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
-export { injectLocatorHighlightScripts };
+declare const baseTestFixture: (testFn: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>, options?: HighlighterOpts) => TestType<PlaywrightTestArgs & PlaywrightTestOptions & TestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+export { baseTestFixture, extendExpect, injectLocatorHighlightScripts };
 //# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,IAAI,EACJ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,yBAAyB,EAAE,CACzB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACtD,UAAU,EAAE,IAAI,CAAC;CAClB,CAAC;AAIF,eAAO,MAAM,eAAe,WAClB,SACN,kBAAkB,GAAG,qBAAqB,EAC1C,oBAAoB,GAAG,uBAAuB,CAC/C,YACQ,eAAe,uHA0DzB,CAAC;AAEF,OAAO,EAAE,6BAA6B,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,IAAI,EACJ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM1C,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,cAAc,CAAC;QACvB,UAAU,QAAQ,CAAC,CAAC;YAClB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;SAC9C;KACF;CACF;AAED,QAAA,MAAM,YAAY,mBAA6B,aAAa,0CAG3D,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,yBAAyB,EAAE,CACzB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACtD,UAAU,EAAE,IAAI,CAAC;CAClB,CAAC;AAIF,QAAA,MAAM,eAAe,WACX,SACN,kBAAkB,GAAG,qBAAqB,EAC1C,oBAAoB,GAAG,uBAAuB,CAC/C,YACQ,eAAe,uHA0DzB,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,6BAA6B,EAAE,CAAC"}

package/dist/test/index.js

@@ -3,12 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.injectLocatorHighlightScripts = exports.baseTestFixture = void 0;
+exports.injectLocatorHighlightScripts = exports.extendExpect = exports.baseTestFixture = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const rimraf_1 = require("rimraf");
+const expect_1 = require("./expect");
 const scripts_1 = require("./scripts");
 Object.defineProperty(exports, "injectLocatorHighlightScripts", { enumerable: true, get: function () { return scripts_1.injectLocatorHighlightScripts; } });
+const extendExpect = function (expectInstance) {
+    expectInstance.extend({ toLookRight: expect_1.toLookRight });
+    return expectInstance;
+};
+exports.extendExpect = extendExpect;
 const videoStore = "videos-store";
 const baseTestFixture = function (testFn, options = {
     mousePointerHighlighter: true,

package/dist/test/scripts/mouse-pointer.d.ts

@@ -1,3 +1,5 @@
 import type { Page } from "@playwright/test";
+export declare function addHighlighterScriptsToPage(page: Page): Promise<void>;
+export declare function removeMousePointerHighlighter(page: Page): Promise<void>;
 export declare function addMousePointerHighlighter(page: Page): void;
 //# sourceMappingURL=mouse-pointer.d.ts.map

package/dist/test/scripts/mouse-pointer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mouse-pointer.d.ts","sourceRoot":"","sources":["../../../src/test/scripts/mouse-pointer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,IAAI,QA0MpD"}
+{"version":3,"file":"mouse-pointer.d.ts","sourceRoot":"","sources":["../../../src/test/scripts/mouse-pointer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAmD7C,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,IAAI,iBAqD3D;AAED,wBAAsB,6BAA6B,CAAC,IAAI,EAAE,IAAI,iBA6B7D;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,IAAI,QAUpD"}

package/dist/test/scripts/mouse-pointer.js

@@ -1,166 +1,125 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addMousePointerHighlighter = void 0;
+exports.addMousePointerHighlighter = exports.removeMousePointerHighlighter = exports.addHighlighterScriptsToPage = void 0;
 const logger_1 = require("../../logger");
-function addMousePointerHighlighter(page) {
-    page.on("load", async () => {
-        try {
-            await page?.evaluate(() => {
-                const box = document.createElement("div");
-                box.classList.add("empirical-mouse-pointer");
-                const styleElement = document.createElement("style");
-                styleElement.textContent = `
-      .empirical-mouse-pointer {
-        pointer-events: none;
-        position: absolute;
-        top: 0;
-        z-index: 10000;
-        left: 0;
-        width: 20px;
-        height: 20px;
-        background: rgba(0,0,0,.4);
-        border: 1px dashed #FF000D;
-        border-radius: 10px;
-        margin: -10px 0 0 -10px;
-        padding: 0;
-        transition: background .2s, border-radius .2s, border-color .2s;
-      }
-      .empirical-mouse-pointer.button-1 {
-        transition: none;
-        background: rgba(0,0,0,0.9);
-      }
-      .empirical-mouse-pointer.button-2 {
-        transition: none;
-        border-color: rgba(0,0,255,0.9);
-      }
-      .empirical-mouse-pointer.button-3 {
-        transition: none;
-        border-radius: 4px;
-      }
-      .empirical-mouse-pointer.button-4 {
-        transition: none;
-        border-color: rgba(255,0,0,0.9);
-      }
-      .empirical-mouse-pointer.button-5 {
-        transition: none;
-        border-color: rgba(0,255,0,0.9);
-      }
-      .empirical-element-grab-highlight {
-        outline: 2px dashed cyan !important;
-      }
-      *:focus {
-        outline: 2px dashed #FF000D !important;
-      }
-      *:focus-visible {
-        outline: 2px dashed #FF000D !important;
-      }
-    `;
-                document.head.appendChild(styleElement);
-                document.body.appendChild(box);
-                document.addEventListener("mousemove", (event) => {
-                    box.style.left = `${event.pageX}px`;
-                    box.style.top = `${event.pageY}px`;
-                    updateButtons(event.buttons);
-                }, true);
-                document.addEventListener("mousedown", (event) => {
-                    updateButtons(event.buttons);
-                    box.classList.add(`button-${event.button + 1}`);
-                }, true);
-                document.addEventListener("mouseup", (event) => {
-                    updateButtons(event.buttons);
-                    box.classList.remove(`button-${event.button + 1}`);
-                }, true);
-                // @ts-ignore
-                function updateButtons(buttons) {
-                    for (let i = 0; i < 5; i++) {
-                        box.classList.toggle(`button-${i + 1}`, (buttons / Math.pow(2, i)) % 2 >= 1);
-                    }
+const STYLES_FOR_MOUSE_POINTER = `
+.empirical-mouse-pointer {
+  pointer-events: none;
+  position: absolute;
+  top: 0;
+  z-index: 10000;
+  left: 0;
+  width: 20px;
+  height: 20px;
+  background: rgba(0,0,0,.4);
+  border: 1px dashed #FF000D;
+  border-radius: 10px;
+  margin: -10px 0 0 -10px;
+  padding: 0;
+  transition: background .2s, border-radius .2s, border-color .2s;
+}
+.empirical-mouse-pointer.button-1 {
+  transition: none;
+  background: rgba(0,0,0,0.9);
+}
+.empirical-mouse-pointer.button-2 {
+  transition: none;
+  border-color: rgba(0,0,255,0.9);
+}
+.empirical-mouse-pointer.button-3 {
+  transition: none;
+  border-radius: 4px;
+}
+.empirical-mouse-pointer.button-4 {
+  transition: none;
+  border-color: rgba(255,0,0,0.9);
+}
+.empirical-mouse-pointer.button-5 {
+  transition: none;
+  border-color: rgba(0,255,0,0.9);
+}
+.empirical-element-grab-highlight {
+  outline: 2px dashed cyan !important;
+}
+*:focus {
+  outline: 2px dashed #FF000D !important;
+}
+*:focus-visible {
+  outline: 2px dashed #FF000D !important;
+}
+`;
+async function addHighlighterScriptsToPage(page) {
+    try {
+        await page.evaluate((stylesString) => {
+            const mouseBox = document.createElement("div");
+            mouseBox.classList.add("empirical-mouse-pointer");
+            const styleElement = document.createElement("style");
+            styleElement.textContent = stylesString;
+            document.head.appendChild(styleElement);
+            document.body.appendChild(mouseBox);
+            document.addEventListener("mousemove", (event) => {
+                mouseBox.style.left = `${event.pageX}px`;
+                mouseBox.style.top = `${event.pageY}px`;
+                updateButtons(event.buttons);
+            }, true);
+            document.addEventListener("mousedown", (event) => {
+                updateButtons(event.buttons);
+                mouseBox.classList.add(`button-${event.button + 1}`);
+            }, true);
+            document.addEventListener("mouseup", (event) => {
+                updateButtons(event.buttons);
+                mouseBox.classList.remove(`button-${event.button + 1}`);
+            }, true);
+            // @ts-ignore
+            function updateButtons(buttons) {
+                for (let i = 0; i < 5; i++) {
+                    mouseBox.classList.toggle(`button-${i + 1}`, (buttons / Math.pow(2, i)) % 2 >= 1);
+                }
+            }
+        }, STYLES_FOR_MOUSE_POINTER);
+    }
+    catch (e) {
+        logger_1.logger.debug(`Error adding mouse pointer highlighter`, e);
+    }
+}
+exports.addHighlighterScriptsToPage = addHighlighterScriptsToPage;
+async function removeMousePointerHighlighter(page) {
+    try {
+        await page.evaluate(() => {
+            // check if any element has the class empirical-element-grab-highlight
+            // if so, remove the class
+            const hasHighlight = document.querySelectorAll(".empirical-element-grab-highlight");
+            if (hasHighlight) {
+                hasHighlight.forEach((highlight) => {
+                    highlight.classList.remove("empirical-element-grab-highlight");
+                });
+            }
+            // find div.empirical-mouse-pointer and remove it
+            const mousePointer = document.querySelector(".empirical-mouse-pointer");
+            if (mousePointer) {
+                mousePointer.remove();
+            }
+            // find style element with text content of STYLE_FOR_MOUSE_POINTER
+            const styleElements = document.querySelectorAll("style");
+            styleElements.forEach((styleElement) => {
+                if (styleElement.textContent?.includes("empirical-mouse-pointer")) {
+                    styleElement.remove();
                 }
             });
-        }
-        catch (e) {
-            logger_1.logger.debug(`Error adding mouse pointer highlighter`, e);
-        }
+        });
+    }
+    catch (e) {
+        logger_1.logger.debug(`Error removing mouse pointer highlighter`, e);
+    }
+}
+exports.removeMousePointerHighlighter = removeMousePointerHighlighter;
+function addMousePointerHighlighter(page) {
+    page.on("load", async () => {
+        await addHighlighterScriptsToPage(page);
     });
     page.context().on("page", async (newPage) => {
         newPage?.on("load", async () => {
-            try {
-                await newPage?.evaluate(() => {
-                    const box = document.createElement("div");
-                    box.classList.add("empirical-mouse-pointer");
-                    const styleElement = document.createElement("style");
-                    styleElement.textContent = `
-        .empirical-mouse-pointer {
-          pointer-events: none;
-          position: absolute;
-          top: 0;
-          z-index: 10000;
-          left: 0;
-          width: 20px;
-          height: 20px;
-          background: rgba(0,0,0,.4);
-          border: 1px dashed #FF000D;
-          border-radius: 10px;
-          margin: -10px 0 0 -10px;
-          padding: 0;
-          transition: background .2s, border-radius .2s, border-color .2s;
-        }
-        .empirical-mouse-pointer.button-1 {
-          transition: none;
-          background: rgba(0,0,0,0.9);
-        }
-        .empirical-mouse-pointer.button-2 {
-          transition: none;
-          border-color: rgba(0,0,255,0.9);
-        }
-        .empirical-mouse-pointer.button-3 {
-          transition: none;
-          border-radius: 4px;
-        }
-        .empirical-mouse-pointer.button-4 {
-          transition: none;
-          border-color: rgba(255,0,0,0.9);
-        }
-        .empirical-mouse-pointer.button-5 {
-          transition: none;
-          border-color: rgba(0,255,0,0.9);
-        }
-        .empirical-element-grab-highlight {
-          outline: 2px dashed cyan !important;
-        }
-        *:focus {
-          outline: 2px dashed #FF000D !important;
-        }
-        *:focus-visible {
-          outline: 2px dashed #FF000D !important;
-        }
-      `;
-                    document.head.appendChild(styleElement);
-                    document.body.appendChild(box);
-                    document.addEventListener("mousemove", (event) => {
-                        box.style.left = `${event.pageX}px`;
-                        box.style.top = `${event.pageY}px`;
-                        updateButtons(event.buttons);
-                    }, true);
-                    document.addEventListener("mousedown", (event) => {
-                        updateButtons(event.buttons);
-                        box.classList.add(`button-${event.button + 1}`);
-                    }, true);
-                    document.addEventListener("mouseup", (event) => {
-                        updateButtons(event.buttons);
-                        box.classList.remove(`button-${event.button + 1}`);
-                    }, true);
-                    // @ts-ignore
-                    function updateButtons(buttons) {
-                        for (let i = 0; i < 5; i++) {
-                            box.classList.toggle(`button-${i + 1}`, (buttons / Math.pow(2, i)) % 2 >= 1);
-                        }
-                    }
-                });
-            }
-            catch (e) {
-                logger_1.logger.debug(`Error adding mouse pointer highlighter`, e);
-            }
+            await addHighlighterScriptsToPage(newPage);
         });
     });
 }

package/dist/test/scripts/pw-locator-patch/highlight/click.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"click.d.ts","sourceRoot":"","sources":["../../../../../src/test/scripts/pw-locator-patch/highlight/click.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA8BrC,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,SAAS,CAiC5B;AAkHD,wBAAgB,UAAU,CACxB,YAAY,EAAE,QAAQ,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,EAC/C,MAAM,EAAE,MAAM,QA+Df"}
+{"version":3,"file":"click.d.ts","sourceRoot":"","sources":["../../../../../src/test/scripts/pw-locator-patch/highlight/click.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA8BrC,KAAK,cAAc,GAAG;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,SAAS,CAiC5B;AA0HD,wBAAgB,UAAU,CACxB,YAAY,EAAE,QAAQ,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,EAC/C,MAAM,EAAE,MAAM,QA+Df"}

package/dist/test/scripts/pw-locator-patch/highlight/click.js

@@ -75,46 +75,51 @@ function overlayDescription(element) {
     }
 }
 async function textContent(pageRef, element) {
-    if (element) {
-        const { interceptor, parent } = element;
-        let startTag = parent ? parent : interceptor;
-        let endTag;
-        const match = startTag.match(/^<\s*([^\s>]+)/);
-        if (match) {
-            const tagName = match[1]; // "div"
-            endTag = `</${tagName}>`;
-        }
-        if (!startTag || !endTag) {
-            return undefined;
-        }
-        return await pageRef.evaluate((tags) => {
-            const [startTag, endTag] = tags;
-            const htmlString = `${startTag}temp${endTag}`;
-            const parser = new DOMParser();
-            const doc = parser.parseFromString(htmlString, "text/html");
-            const tempEl = doc.body.firstElementChild;
-            let selector = tempEl.tagName.toLowerCase(); // start with the tag name, e.g., 'div'
-            // If there's an id, add it (id is unique and very specific)
-            if (tempEl.id) {
-                selector += `#${tempEl.id}`;
+    try {
+        if (element) {
+            const { interceptor, parent } = element;
+            let startTag = parent ? parent : interceptor;
+            let endTag;
+            const match = startTag.match(/^<\s*([^\s>]+)/);
+            if (match) {
+                const tagName = match[1]; // "div"
+                endTag = `</${tagName}>`;
             }
-            // Add all classes (if any)
-            if (tempEl.classList.length > 0) {
-                tempEl.classList.forEach((cls) => {
-                    selector += `.${cls}`;
-                });
+            if (!startTag || !endTag) {
+                return undefined;
             }
-            // Add any other attributes that might help narrow it down.
-            // (Skip 'id' and 'class' because they are already included.)
-            Array.from(tempEl.attributes).forEach((attr) => {
-                if (attr.name === "id" || attr.name === "class")
-                    return;
-                // Note: if attribute values contain special characters, consider escaping them.
-                selector += `[${attr.name}="${attr.value}"]`;
-            });
-            const realElement = document.querySelector(selector);
-            return realElement?.textContent?.trim();
-        }, [startTag, endTag]);
+            return await pageRef.evaluate((tags) => {
+                const [startTag, endTag] = tags;
+                const htmlString = `${startTag}temp${endTag}`;
+                const parser = new DOMParser();
+                const doc = parser.parseFromString(htmlString, "text/html");
+                const tempEl = doc.body.firstElementChild;
+                let selector = tempEl.tagName.toLowerCase(); // start with the tag name, e.g., 'div'
+                // If there's an id, add it (id is unique and very specific)
+                if (tempEl.id) {
+                    selector += `#${CSS.escape(tempEl.id)}`;
+                }
+                // Add classes individually, escaping each one
+                if (tempEl.classList.length > 0) {
+                    Array.from(tempEl.classList).forEach((cls) => {
+                        selector += `.${CSS.escape(cls)}`;
+                    });
+                }
+                // Add other attributes, being careful with escaping
+                Array.from(tempEl.attributes).forEach((attr) => {
+                    if (attr.name === "id" || attr.name === "class")
+                        return;
+                    selector += `[${attr.name}="${attr.value.replace(/"/g, '\\"')}"]`;
+                });
+                console.log("Generated selector:", selector);
+                const realElement = document.querySelector(selector);
+                return realElement?.textContent?.trim();
+            }, [startTag, endTag]);
+        }
+    }
+    catch (err) {
+        console.error("Unable to determine text content for overlay:", err);
+        return undefined;
     }
 }
 function isProductFruitsOverlay(element) {
@@ -126,7 +131,11 @@ async function runAgentOnOverlay(pageRef, element) {
     const promptAddition = content
         ? `
 The popup can be identified with its text content:
-${content}`
+
+<popup_text_content>
+${content}
+</popup_text_content>
+`
         : ``;
     let task = isProductFruitsOverlay(element)
         ? `

package/docs/fixtures.md

@@ -4,20 +4,45 @@ The playwright-utils package provides fixtures that wrap around Playwright's bui
 `page`, `context` fixtures to provide a mouse highlighter (which makes it easier to
 see actions taken in a video).
 
-To use this, you probably just want to use the `baseTestFixture` import and use it in your
-fixtures file.
+To use this, you can use the `baseTestFixture` and `extendExpect` imports
+in your fixtures file.
 
 ```ts
-import { test as base, Page } from "@playwright/test";
-import { baseTestFixture } from "@empiricalrun/playwright-utils/test";
+import { test as base, expect as baseExpect } from "@playwright/test";
+import { baseTestFixture, extendExpect } from "@empiricalrun/playwright-utils/test";
 
 export const test = baseTestFixture(base);
-export const expect = test.expect;
+export const expect = extendExpect(baseExpect);
 ```
 
+## Highlighters and agentic behaviors
+
+`baseTestFixture` patches the playwright page object to add the following methods to add
+mouse highlights and locator highlights.
+
+These methods also enable agentic behaviors like dismissing overlays.
+
+## Custom Matchers
+
+The `extendExpect` method adds custom matchers that can be used with Playwright's expect:
+
+### Visual Testing
+
+The `toLookRight` matcher uses LLM to analyze screenshots for visual inconsistencies:
+
+```ts
+test('page looks visually correct', async ({ page }) => {
+  await page.goto('https://your-site.com');
+  const description = "A login page with email and password fields, and a submit button"
+  await expect(page).toLookRight(description);
+});
+```
+
+## Advanced Use Cases
+
 The packages also expose methods to enable advanced use-cases.
 
-## Get a new browser context
+### Get a new browser context
 
 This package provides a fixture `customContextPageProvider` which is a good way to create
 a fresh, new browser context, and a page inside it.
@@ -36,7 +61,7 @@ test("Example test", async ({ page: builtInPage, customContextPageProvider }) =>
 });
 ```
 
-## Inject mouse highlighter manually
+### Inject mouse highlighter manually
 
 In some cases, you want to inject mouse highlights to a page. This is useful if the test
 requires `launchPersistentContext`, which means the browser context is created manually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empiricalrun/playwright-utils",
-  "version": "0.20.14",
+  "version": "0.21.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"