From 906698809823372c16a7fc9486fa90c316192507 Mon Sep 17 00:00:00 2001
From: Simon Knott <info@simonknott.de>
Date: Tue, 17 Jun 2025 14:09:29 +0200
Subject: [PATCH] chore: improve "ref not found" error message (#561)

Helps the model better understand the error cause.
---
 src/tools/utils.ts |  8 +++++++-
 tests/core.spec.ts | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/src/tools/utils.ts b/src/tools/utils.ts
index 497b038..338c189 100644
--- a/src/tools/utils.ts
+++ b/src/tools/utils.ts
@@ -78,7 +78,13 @@ export function sanitizeForFilePath(s: string) {
 }
 
 export async function generateLocator(locator: playwright.Locator): Promise<string> {
-  return (locator as any)._generateLocatorString();
+  try {
+    return await (locator as any)._generateLocatorString();
+  } catch (e) {
+    if (e instanceof Error && /locator._generateLocatorString: Timeout .* exceeded/.test(e.message))
+      throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+    throw e;
+  }
 }
 
 export async function callOnPageNoTrace<T>(page: playwright.Page, callback: (page: playwright.Page) => Promise<T>): Promise<T> {
diff --git a/tests/core.spec.ts b/tests/core.spec.ts
index 003ea98..a35e7ed 100644
--- a/tests/core.spec.ts
+++ b/tests/core.spec.ts
@@ -237,3 +237,41 @@ await page.setViewportSize({ width: 390, height: 780 });
 \`\`\``);
   await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent('Window size: 390x780');
 });
+
+test('old locator error message', async ({ client, server }) => {
+  server.setContent('/', `
+    <button>Button 1</button>
+    <button>Button 2</button>
+    <script>
+      document.querySelector('button').addEventListener('click', () => {
+        document.querySelectorAll('button')[1].remove();
+      });
+    </script>
+  `, 'text/html');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toContainTextContent(`
+  - button "Button 1" [ref=e2]
+  - button "Button 2" [ref=e3]
+  `.trim());
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button 1',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button 2',
+      ref: 'e3',
+    },
+  })).toContainTextContent('Ref not found');
+});