Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore(mcp): merge refLocator and generateSelector (#37781)

Dmitry Gozmane396b9f6beee
diff --git a/packages/playwright/src/mcp/browser/tab.ts b/packages/playwright/src/mcp/browser/tab.ts
index e655dffc89..2831c68491 100644
--- a/packages/playwright/src/mcp/browser/tab.ts
+++ b/packages/playwright/src/mcp/browser/tab.ts
@@ -16,7 +16,7 @@
import { EventEmitter } from 'events';
import * as playwright from 'playwright-core';
-import { ManualPromise } from 'playwright-core/lib/utils';
+import { asLocator, ManualPromise } from 'playwright-core/lib/utils';
import { callOnPageNoTrace, waitForCompletion } from './tools/utils';
import { logUnhandledError } from '../log';
@@ -25,10 +25,8 @@ import { handleDialog } from './tools/dialogs';
import { uploadFile } from './tools/files';
import type { Context } from './context';
-
-type PageEx = playwright.Page & {
- _snapshotForAI: () => Promise<string>;
-};
+import type { Page } from '../../../../playwright-core/src/client/page';
+import type { Locator } from '../../../../playwright-core/src/client/locator';
export const TabEvents = {
modalState: 'modalState'
@@ -49,7 +47,7 @@ export type TabSnapshot = {
export class Tab extends EventEmitter<TabEventsInterface> {
readonly context: Context;
- readonly page: playwright.Page;
+ readonly page: Page;
private _lastTitle = 'about:blank';
private _consoleMessages: ConsoleMessage[] = [];
private _recentConsoleMessages: ConsoleMessage[] = [];
@@ -62,7 +60,7 @@ export class Tab extends EventEmitter<TabEventsInterface> {
constructor(context: Context, page: playwright.Page, onPageClose: (tab: Tab) => void) {
super();
this.context = context;
- this.page = page;
+ this.page = page as Page;
this._onPageClose = onPageClose;
page.on('console', event => this._handleConsoleMessage(messageToConsoleMessage(event)));
page.on('pageerror', error => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
@@ -222,7 +220,7 @@ export class Tab extends EventEmitter<TabEventsInterface> {
async captureSnapshot(): Promise<TabSnapshot> {
let tabSnapshot: TabSnapshot | undefined;
const modalStates = await this._raceAgainstModalStates(async () => {
- const snapshot = await (this.page as PageEx)._snapshotForAI();
+ const snapshot = await this.page._snapshotForAI();
tabSnapshot = {
url: this.page.url(),
title: await this.page.title(),
@@ -272,17 +270,20 @@ export class Tab extends EventEmitter<TabEventsInterface> {
await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
}
- async refLocator(params: { element: string, ref: string }): Promise<playwright.Locator> {
+ async refLocator(params: { element: string, ref: string }): Promise<{ locator: Locator, resolved: string }> {
return (await this.refLocators([params]))[0];
}
- async refLocators(params: { element: string, ref: string }[]): Promise<playwright.Locator[]> {
- const snapshot = await (this.page as PageEx)._snapshotForAI();
- return params.map(param => {
- if (!snapshot.includes(`[ref=${param.ref}]`))
+ async refLocators(params: { element: string, ref: string }[]): Promise<{ locator: Locator, resolved: string }[]> {
+ return Promise.all(params.map(async param => {
+ try {
+ const locator = this.page.locator(`aria-ref=${param.ref}`).describe(param.element) as Locator;
+ const { resolvedSelector } = await locator._resolveSelector();
+ return { locator, resolved: asLocator('javascript', resolvedSelector) };
+ } catch (e) {
throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
- return this.page.locator(`aria-ref=${param.ref}`).describe(param.element);
- });
+ }
+ }));
}
async waitForTimeout(time: number) {
diff --git a/packages/playwright/src/mcp/browser/tools/evaluate.ts b/packages/playwright/src/mcp/browser/tools/evaluate.ts
index f952230ecd..416a2eeb1c 100644
--- a/packages/playwright/src/mcp/browser/tools/evaluate.ts
+++ b/packages/playwright/src/mcp/browser/tools/evaluate.ts
@@ -17,9 +17,8 @@
import { z } from '../../sdk/bundle';
import { defineTabTool } from './tool';
import * as javascript from '../codegen';
-import { generateLocator } from './utils';
-import type * as playwright from 'playwright-core';
+import type { Tab } from '../tab';
const evaluateSchema = z.object({
function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
@@ -40,16 +39,16 @@ const evaluate = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- let locator: playwright.Locator | undefined;
+ let locator: Awaited<ReturnType<Tab['refLocator']>> | undefined;
if (params.ref && params.element) {
locator = await tab.refLocator({ ref: params.ref, element: params.element });
- response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+ response.addCode(`await page.${locator.resolved}.evaluate(${javascript.quote(params.function)});`);
} else {
response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
}
await tab.waitForCompletion(async () => {
- const receiver = locator ?? tab.page as any;
+ const receiver = locator?.locator ?? tab.page;
const result = await receiver._evaluateFunction(params.function);
response.addResult(JSON.stringify(result, null, 2) || 'undefined');
});
diff --git a/packages/playwright/src/mcp/browser/tools/form.ts b/packages/playwright/src/mcp/browser/tools/form.ts
index b2d957e99f..f128789d6a 100644
--- a/packages/playwright/src/mcp/browser/tools/form.ts
+++ b/packages/playwright/src/mcp/browser/tools/form.ts
@@ -16,7 +16,6 @@
import { z } from '../../sdk/bundle';
import { defineTabTool } from './tool';
-import { generateLocator } from './utils';
import * as codegen from '../codegen';
const fillForm = defineTabTool({
@@ -39,8 +38,8 @@ const fillForm = defineTabTool({
handle: async (tab, params, response) => {
for (const field of params.fields) {
- const locator = await tab.refLocator({ element: field.name, ref: field.ref });
- const locatorSource = `await page.${await generateLocator(locator)}`;
+ const { locator, resolved } = await tab.refLocator({ element: field.name, ref: field.ref });
+ const locatorSource = `await page.${resolved}`;
if (field.type === 'textbox' || field.type === 'slider') {
const secret = tab.context.lookupSecret(field.value);
await locator.fill(secret.value);
diff --git a/packages/playwright/src/mcp/browser/tools/keyboard.ts b/packages/playwright/src/mcp/browser/tools/keyboard.ts
index 898e18c467..0010863bc3 100644
--- a/packages/playwright/src/mcp/browser/tools/keyboard.ts
+++ b/packages/playwright/src/mcp/browser/tools/keyboard.ts
@@ -17,7 +17,6 @@
import { z } from '../../sdk/bundle';
import { defineTabTool } from './tool';
import { elementSchema } from './snapshot';
-import { generateLocator } from './utils';
const pressKey = defineTabTool({
capability: 'core',
@@ -60,22 +59,22 @@ const type = defineTabTool({
},
handle: async (tab, params, response) => {
- const locator = await tab.refLocator(params);
+ const { locator, resolved } = await tab.refLocator(params);
const secret = tab.context.lookupSecret(params.text);
await tab.waitForCompletion(async () => {
if (params.slowly) {
response.setIncludeSnapshot();
- response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${secret.code});`);
+ response.addCode(`await page.${resolved}.pressSequentially(${secret.code});`);
await locator.pressSequentially(secret.value);
} else {
- response.addCode(`await page.${await generateLocator(locator)}.fill(${secret.code});`);
+ response.addCode(`await page.${resolved}.fill(${secret.code});`);
await locator.fill(secret.value);
}
if (params.submit) {
response.setIncludeSnapshot();
- response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+ response.addCode(`await page.${resolved}.press('Enter');`);
await locator.press('Enter');
}
});
diff --git a/packages/playwright/src/mcp/browser/tools/screenshot.ts b/packages/playwright/src/mcp/browser/tools/screenshot.ts
index 7aa37db998..51f51a5e80 100644
--- a/packages/playwright/src/mcp/browser/tools/screenshot.ts
+++ b/packages/playwright/src/mcp/browser/tools/screenshot.ts
@@ -17,7 +17,7 @@
import { z } from '../../sdk/bundle';
import { defineTabTool } from './tool';
import * as javascript from '../codegen';
-import { generateLocator, dateAsFileName } from './utils';
+import { dateAsFileName } from './utils';
import type * as playwright from 'playwright-core';
@@ -60,14 +60,14 @@ const screenshot = defineTabTool({
response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);
// Only get snapshot when element screenshot is needed
- const locator = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;
+ const ref = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;
- if (locator)
- response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+ if (ref)
+ response.addCode(`await page.${ref.resolved}.screenshot(${javascript.formatObject(options)});`);
else
response.addCode(`await page.screenshot(${javascript.formatObject(options)});`);
- const buffer = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+ const buffer = ref ? await ref.locator.screenshot(options) : await tab.page.screenshot(options);
response.addResult(`Took the ${screenshotTarget} screenshot and saved it as ${fileName}`);
// https://github.com/microsoft/playwright-mcp/issues/817
diff --git a/packages/playwright/src/mcp/browser/tools/snapshot.ts b/packages/playwright/src/mcp/browser/tools/snapshot.ts
index 5900ada32b..e944bc4034 100644
--- a/packages/playwright/src/mcp/browser/tools/snapshot.ts
+++ b/packages/playwright/src/mcp/browser/tools/snapshot.ts
@@ -17,7 +17,6 @@
import { z } from '../../sdk/bundle';
import { defineTabTool, defineTool } from './tool';
import * as javascript from '../codegen';
-import { generateLocator } from './utils';
const snapshot = defineTool({
capability: 'core',
@@ -59,7 +58,7 @@ const click = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const locator = await tab.refLocator(params);
+ const { locator, resolved } = await tab.refLocator(params);
const options = {
button: params.button,
modifiers: params.modifiers,
@@ -68,9 +67,9 @@ const click = defineTabTool({
const optionsAttr = formatted !== '{}' ? formatted : '';
if (params.doubleClick)
- response.addCode(`await page.${await generateLocator(locator)}.dblclick(${optionsAttr});`);
+ response.addCode(`await page.${resolved}.dblclick(${optionsAttr});`);
else
- response.addCode(`await page.${await generateLocator(locator)}.click(${optionsAttr});`);
+ response.addCode(`await page.${resolved}.click(${optionsAttr});`);
await tab.waitForCompletion(async () => {
if (params.doubleClick)
@@ -99,16 +98,16 @@ const drag = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const [startLocator, endLocator] = await tab.refLocators([
+ const [start, end] = await tab.refLocators([
{ ref: params.startRef, element: params.startElement },
{ ref: params.endRef, element: params.endElement },
]);
await tab.waitForCompletion(async () => {
- await startLocator.dragTo(endLocator);
+ await start.locator.dragTo(end.locator);
});
- response.addCode(`await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`);
+ response.addCode(`await page.${start.resolved}.dragTo(page.${end.resolved});`);
},
});
@@ -125,8 +124,8 @@ const hover = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const locator = await tab.refLocator(params);
- response.addCode(`await page.${await generateLocator(locator)}.hover();`);
+ const { locator, resolved } = await tab.refLocator(params);
+ response.addCode(`await page.${resolved}.hover();`);
await tab.waitForCompletion(async () => {
await locator.hover();
@@ -151,8 +150,8 @@ const selectOption = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const locator = await tab.refLocator(params);
- response.addCode(`await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`);
+ const { locator, resolved } = await tab.refLocator(params);
+ response.addCode(`await page.${resolved}.selectOption(${javascript.formatObject(params.values)});`);
await tab.waitForCompletion(async () => {
await locator.selectOption(params.values);
@@ -171,8 +170,8 @@ const pickLocator = defineTabTool({
},
handle: async (tab, params, response) => {
- const locator = await tab.refLocator(params);
- response.addResult(await generateLocator(locator));
+ const { resolved } = await tab.refLocator(params);
+ response.addResult(resolved);
},
});
diff --git a/packages/playwright/src/mcp/browser/tools/utils.ts b/packages/playwright/src/mcp/browser/tools/utils.ts
index e68aa6990b..170bc06dfc 100644
--- a/packages/playwright/src/mcp/browser/tools/utils.ts
+++ b/packages/playwright/src/mcp/browser/tools/utils.ts
@@ -14,8 +14,6 @@
* limitations under the License.
*/
-import { asLocator } from 'playwright-core/lib/utils';
-
import type * as playwright from 'playwright-core';
import type { Tab } from '../tab';
@@ -74,15 +72,6 @@ export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>)
}
}
-export async function generateLocator(locator: playwright.Locator): Promise<string> {
- try {
- const { resolvedSelector } = await (locator as any)._resolveSelector();
- return asLocator('javascript', resolvedSelector);
- } catch (e) {
- throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
- }
-}
-
export async function callOnPageNoTrace<T>(page: playwright.Page, callback: (page: playwright.Page) => Promise<T>): Promise<T> {
return await (page as any)._wrapApiCall(() => callback(page), { internal: true });
}
diff --git a/packages/playwright/src/mcp/browser/tools/verify.ts b/packages/playwright/src/mcp/browser/tools/verify.ts
index fa4d0ba0da..1da87d5afa 100644
--- a/packages/playwright/src/mcp/browser/tools/verify.ts
+++ b/packages/playwright/src/mcp/browser/tools/verify.ts
@@ -17,7 +17,6 @@
import { z } from '../../sdk/bundle';
import { defineTabTool } from './tool';
import * as javascript from '../codegen';
-import { generateLocator } from './utils';
const verifyElement = defineTabTool({
capability: 'testing',
@@ -83,7 +82,7 @@ const verifyList = defineTabTool({
},
handle: async (tab, params, response) => {
- const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+ const { locator } = await tab.refLocator({ ref: params.ref, element: params.element });
const itemTexts: string[] = [];
for (const item of params.items) {
const itemLocator = locator.getByText(item);
@@ -118,8 +117,8 @@ const verifyValue = defineTabTool({
},
handle: async (tab, params, response) => {
- const locator = await tab.refLocator({ ref: params.ref, element: params.element });
- const locatorSource = `page.${await generateLocator(locator)}`;
+ const { locator, resolved } = await tab.refLocator({ ref: params.ref, element: params.element });
+ const locatorSource = `page.${resolved}`;
if (params.type === 'textbox' || params.type === 'slider' || params.type === 'combobox') {
const value = await locator.inputValue();
if (value !== params.value) {