Skip to content

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

feat(api): Page.hideHighlight, rename ref → target (#40219)

Pavel Feldman57888a502b41
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 09157a48aa..7b5916d418 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -1443,6 +1443,19 @@ Highlight the corresponding element(s) on the screen. Useful for debugging, don'
### option: Locator.highlight.style
* since: v1.60
+* langs: js
+- `style` <[string]|[Object]<[string], [any]>>
+
+Inline CSS applied to the highlight overlay, e.g.
+
+```js
+await locator.highlight('outline: 2px dashed red');
+await locator.highlight({ color: 'red' });
+```
+
+### option: Locator.highlight.style
+* since: v1.60
+* langs: java, python, csharp
- `style` <[string]>
Additional inline CSS applied to the highlight overlay, e.g. `"outline: 2px dashed red"`.
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 01b4f4f2b7..07af271bfd 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2451,6 +2451,11 @@ it gets merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/We
Referer header value. If provided it will take preference over the referer header value set by
[`method: Page.setExtraHTTPHeaders`].
+## async method: Page.hideHighlight
+* since: v1.60
+
+Hide all locator highlight overlays previously added by [`method: Locator.highlight`] on this page.
+
## async method: Page.hover
* since: v1.8
* discouraged: Use locator-based [`method: Locator.hover`] instead. Read more about [locators](../locators.md).
diff --git a/packages/isomorphic/protocolMetainfo.ts b/packages/isomorphic/protocolMetainfo.ts
index fa70041e4e..cda2daa7fd 100644
--- a/packages/isomorphic/protocolMetainfo.ts
+++ b/packages/isomorphic/protocolMetainfo.ts
@@ -146,6 +146,7 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([
['Page.bringToFront', { title: 'Bring to front', }],
['Page.pickLocator', { title: 'Pick locator', group: 'configuration', }],
['Page.cancelPickLocator', { title: 'Cancel pick locator', group: 'configuration', }],
+ ['Page.hideHighlight', { title: 'Hide all element highlights', group: 'configuration', }],
['Page.screencastShowOverlay', { title: 'Show overlay', group: 'configuration', }],
['Page.screencastRemoveOverlay', { title: 'Remove overlay', group: 'configuration', }],
['Page.screencastChapter', { title: 'Show chapter overlay', group: 'configuration', }],
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index eea0869050..a8cd0cf0dc 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -3247,6 +3247,12 @@ export interface Page {
waitUntil?: "load"|"domcontentloaded"|"networkidle"|"commit";
}): Promise<null|Response>;
+ /**
+ * Hide all locator highlight overlays previously added by
+ * [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight) on this page.
+ */
+ hideHighlight(): Promise<void>;
+
/**
* **NOTE** Use locator-based [locator.hover([options])](https://playwright.dev/docs/api/class-locator#locator-hover) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index 4ac5c7bc45..2a549895b7 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -300,6 +300,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
await this._channel.cancelPickLocator({});
}
+ async hideHighlight(): Promise<void> {
+ await this._channel.hideHighlight({});
+ }
+
async $(selector: string, options?: { strict?: boolean }): Promise<ElementHandle<SVGElement | HTMLElement> | null> {
return await this._mainFrame.$(selector, options);
}
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index b25ef82721..d090e28ad4 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -1544,6 +1544,8 @@ scheme.PagePickLocatorResult = tObject({
});
scheme.PageCancelPickLocatorParams = tOptional(tObject({}));
scheme.PageCancelPickLocatorResult = tOptional(tObject({}));
+scheme.PageHideHighlightParams = tOptional(tObject({}));
+scheme.PageHideHighlightResult = tOptional(tObject({}));
scheme.PageScreencastShowOverlayParams = tObject({
html: tString,
duration: tOptional(tFloat),
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index 5426544fd7..867476914d 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -360,6 +360,10 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
await progress.race(recorder.setMode('none'));
}
+ async hideHighlight(params: channels.PageHideHighlightParams, progress: Progress): Promise<void> {
+ await progress.race(this._page.hideHighlight());
+ }
+
async screencastShowOverlay(params: channels.PageScreencastShowOverlayParams): Promise<channels.PageScreencastShowOverlayResult> {
const id = await this._page.overlay.show(params.html, params.duration);
return { id };
diff --git a/packages/playwright-core/src/tools/backend/devtools.ts b/packages/playwright-core/src/tools/backend/devtools.ts
index 1858e64c70..28464fe6c2 100644
--- a/packages/playwright-core/src/tools/backend/devtools.ts
+++ b/packages/playwright-core/src/tools/backend/devtools.ts
@@ -16,7 +16,7 @@
import * as z from 'zod';
import { defineTabTool, defineTool } from './tool';
-import { elementSchema } from './snapshot';
+import { elementSchema, optionalElementSchema } from './snapshot';
const resume = defineTool({
capability: 'devtools',
@@ -98,9 +98,9 @@ const highlight = defineTabTool({
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator } = await tab.targetLocator(params);
await locator.highlight({ style: params.style });
- response.addTextResult(`Highlighted ${resolved}`);
+ response.addTextResult(`Highlighted ${locator}`);
},
});
@@ -110,14 +110,21 @@ const hideHighlight = defineTabTool({
name: 'browser_hide_highlight',
title: 'Hide element highlight',
description: 'Remove a highlight overlay previously added for the element.',
- inputSchema: elementSchema,
+ inputSchema: optionalElementSchema.extend({
+ element: z.string().optional().describe('Human-readable element description used when adding the highlight; must match the value passed to browser_highlight.'),
+ }),
type: 'readOnly',
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator(params);
- await locator.hideHighlight();
- response.addTextResult(`Hid highlight for ${resolved}`);
+ if (params.target) {
+ const { locator } = await tab.targetLocator({ target: params.target, element: params.element });
+ await locator.hideHighlight();
+ response.addTextResult(`Hid highlight for ${locator}`);
+ } else {
+ await tab.page.hideHighlight();
+ response.addTextResult(`Hid page highlight`);
+ }
},
});
diff --git a/packages/playwright-core/src/tools/backend/evaluate.ts b/packages/playwright-core/src/tools/backend/evaluate.ts
index 60f99faf84..df797b8b75 100644
--- a/packages/playwright-core/src/tools/backend/evaluate.ts
+++ b/packages/playwright-core/src/tools/backend/evaluate.ts
@@ -18,14 +18,12 @@ import * as z from 'zod';
import { escapeWithQuotes } from '@isomorphic/stringUtils';
import { defineTabTool } from './tool';
+import { optionalElementSchema } from './snapshot';
import type { Tab } from './tab';
-const evaluateSchema = z.object({
+const evaluateSchema = optionalElementSchema.extend({
function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
- element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
- ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
- selector: z.string().optional().describe('CSS or role selector for the target element, when "ref" is not available.'),
filename: z.string().optional().describe('Filename to save the result to. If not provided, result is returned as text.'),
});
@@ -40,10 +38,10 @@ const evaluate = defineTabTool({
},
handle: async (tab, params, response) => {
- let locator: Awaited<ReturnType<Tab['refLocator']>> | undefined;
+ let locator: Awaited<ReturnType<Tab['targetLocator']>> | undefined;
const expression = params.function;
- if (params.ref)
- locator = await tab.refLocator({ ref: params.ref, selector: params.selector, element: params.element || 'element' });
+ if (params.target)
+ locator = await tab.targetLocator({ target: params.target, element: params.element || 'element' });
await tab.waitForCompletion(async () => {
let evalResult: { result: unknown, isFunction: boolean };
diff --git a/packages/playwright-core/src/tools/backend/form.ts b/packages/playwright-core/src/tools/backend/form.ts
index bc5a7d5704..ffd0f3a389 100644
--- a/packages/playwright-core/src/tools/backend/form.ts
+++ b/packages/playwright-core/src/tools/backend/form.ts
@@ -18,6 +18,7 @@ import * as z from 'zod';
import { escapeWithQuotes } from '@isomorphic/stringUtils';
import { defineTabTool } from './tool';
+import { elementSchema } from './snapshot';
const fillForm = defineTabTool({
capability: 'core',
@@ -27,11 +28,9 @@ const fillForm = defineTabTool({
title: 'Fill form',
description: 'Fill multiple form fields',
inputSchema: z.object({
- fields: z.array(z.object({
+ fields: z.array(elementSchema.extend({
name: z.string().describe('Human-readable field name'),
type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the field'),
- ref: z.string().describe('Exact target field reference from the page snapshot'),
- selector: z.string().optional().describe('CSS or role selector for the field element, when "ref" is not available. Either "selector" or "ref" is required.'),
value: z.string().describe('Value to fill in the field. If the field is a checkbox, the value should be `true` or `false`. If the field is a combobox, the value should be the text of the option.'),
})).describe('Fields to fill in'),
}),
@@ -40,7 +39,7 @@ const fillForm = defineTabTool({
handle: async (tab, params, response) => {
for (const field of params.fields) {
- const { locator, resolved } = await tab.refLocator({ element: field.name, ref: field.ref, selector: field.selector });
+ const { locator, resolved } = await tab.targetLocator({ element: field.name, target: field.target });
const locatorSource = `await page.${resolved}`;
if (field.type === 'textbox' || field.type === 'slider') {
const secret = tab.context.lookupSecret(field.value);
diff --git a/packages/playwright-core/src/tools/backend/keyboard.ts b/packages/playwright-core/src/tools/backend/keyboard.ts
index 3e39d68179..da2554cf73 100644
--- a/packages/playwright-core/src/tools/backend/keyboard.ts
+++ b/packages/playwright-core/src/tools/backend/keyboard.ts
@@ -91,7 +91,7 @@ const type = defineTabTool({
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
const secret = tab.context.lookupSecret(params.text);
const action = async () => {
diff --git a/packages/playwright-core/src/tools/backend/screenshot.ts b/packages/playwright-core/src/tools/backend/screenshot.ts
index 01463714d0..71342abc9e 100644
--- a/packages/playwright-core/src/tools/backend/screenshot.ts
+++ b/packages/playwright-core/src/tools/backend/screenshot.ts
@@ -21,15 +21,13 @@ import { formatObject } from '@isomorphic/stringUtils';
import { scaleImageToSize } from '@isomorphic/imageUtils';
import { defineTabTool } from './tool';
+import { optionalElementSchema } from './snapshot';
import type * as playwright from '../../..';
-const screenshotSchema = z.object({
+const screenshotSchema = optionalElementSchema.extend({
type: z.enum(['png', 'jpeg']).default('png').describe('Image format for the screenshot. Default is png.'),
filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified. Prefer relative file names to stay within the output directory.'),
- element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
- ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
- selector: z.string().optional().describe('CSS or role selector for the target element, when "ref" is not available.'),
fullPage: z.boolean().optional().describe('When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.'),
});
@@ -44,7 +42,7 @@ const screenshot = defineTabTool({
},
handle: async (tab, params, response) => {
- if (params.fullPage && params.ref)
+ if (params.fullPage && params.target)
throw new Error('fullPage cannot be used with element screenshots.');
const fileType = params.type || 'png';
@@ -56,15 +54,15 @@ const screenshot = defineTabTool({
...(params.fullPage !== undefined && { fullPage: params.fullPage })
};
- const screenshotTarget = params.ref ? params.element || 'element' : (params.fullPage ? 'full page' : 'viewport');
- const ref = (params.ref || params.selector) ? await tab.refLocator({ element: params.element || '', ref: params.ref || '', selector: params.selector }) : null;
- const data = ref ? await ref.locator.screenshot(options) : await tab.page.screenshot(options);
+ const screenshotTargetLabel = params.target ? params.element || 'element' : (params.fullPage ? 'full page' : 'viewport');
+ const target = params.target ? await tab.targetLocator({ element: params.element, target: params.target }) : null;
+ const data = target ? await target.locator.screenshot(options) : await tab.page.screenshot(options);
- const resolvedFile = await response.resolveClientFile({ prefix: ref ? 'element' : 'page', ext: fileType, suggestedFilename: params.filename }, `Screenshot of ${screenshotTarget}`);
+ const resolvedFile = await response.resolveClientFile({ prefix: target ? 'element' : 'page', ext: fileType, suggestedFilename: params.filename }, `Screenshot of ${screenshotTargetLabel}`);
- response.addCode(`// Screenshot ${screenshotTarget} and save it as ${resolvedFile.relativeName}`);
- if (ref)
- response.addCode(`await page.${ref.resolved}.screenshot(${formatObject({ ...options, path: resolvedFile.relativeName })});`);
+ response.addCode(`// Screenshot ${screenshotTargetLabel} and save it as ${resolvedFile.relativeName}`);
+ if (target)
+ response.addCode(`await page.${target.resolved}.screenshot(${formatObject({ ...options, path: resolvedFile.relativeName })});`);
else
response.addCode(`await page.screenshot(${formatObject({ ...options, path: resolvedFile.relativeName })});`);
diff --git a/packages/playwright-core/src/tools/backend/snapshot.ts b/packages/playwright-core/src/tools/backend/snapshot.ts
index 96db219f97..30730b33b4 100644
--- a/packages/playwright-core/src/tools/backend/snapshot.ts
+++ b/packages/playwright-core/src/tools/backend/snapshot.ts
@@ -16,12 +16,20 @@
import * as z from 'zod';
import { formatObject, formatObjectOrVoid } from '@isomorphic/stringUtils';
-
import { defineTabTool } from './tool';
+import type * as playwright from '../../..';
+
+const elementTargetDescription = 'Exact target element reference from the page snapshot, or a unique element selector';
+
export const optionalElementSchema = z.object({
- ref: z.string().optional().describe('Element reference from the previous page snapshot to capture a partial snapshot instead of the whole page'),
- selector: z.string().optional().describe('Element selector of the root element to capture a partial snapshot instead of the whole page'),
+ element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+ target: z.string().optional().describe(elementTargetDescription),
+});
+
+export const elementSchema = z.object({
+ element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+ target: z.string().describe(elementTargetDescription),
});
const snapshot = defineTabTool({
@@ -30,7 +38,8 @@ const snapshot = defineTabTool({
name: 'browser_snapshot',
title: 'Page snapshot',
description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
- inputSchema: optionalElementSchema.extend({
+ inputSchema: z.object({
+ target: z.string().optional().describe(elementTargetDescription),
filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
depth: z.number().optional().describe('Limit the depth of the snapshot tree'),
}),
@@ -38,19 +47,13 @@ const snapshot = defineTabTool({
},
handle: async (tab, params, response) => {
- const root = (params.ref || params.selector)
- ? (await tab.refLocator({ ref: params.ref ?? '', selector: params.selector })).locator
- : undefined;
- response.setIncludeFullSnapshot(params.filename, root, params.depth);
+ let resolved: { locator: playwright.Locator | undefined, resolved: string } = { locator: undefined, resolved: '' };
+ if (params.target)
+ resolved = await tab.targetLocator({ target: params.target });
+ response.setIncludeFullSnapshot(params.filename, resolved.locator, params.depth);
},
});
-export const elementSchema = z.object({
- element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
- ref: z.string().describe('Exact target element reference from the page snapshot'),
- selector: z.string().optional().describe('CSS or role selector for the target element, when "ref" is not available'),
-});
-
const clickSchema = elementSchema.extend({
doubleClick: z.boolean().optional().describe('Whether to perform a double click instead of a single click'),
button: z.enum(['left', 'right', 'middle']).optional().describe('Button to click, defaults to left'),
@@ -70,7 +73,7 @@ const click = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
const options = {
button: params.button,
modifiers: params.modifiers,
@@ -100,11 +103,9 @@ const drag = defineTabTool({
description: 'Perform drag and drop between two elements',
inputSchema: z.object({
startElement: z.string().optional().describe('Human-readable source element description used to obtain the permission to interact with the element'),
- startRef: z.string().describe('Exact source element reference from the page snapshot'),
- startSelector: z.string().optional().describe('CSS or role selector for the source element, when ref is not available'),
+ startTarget: z.string().describe(elementTargetDescription),
endElement: z.string().optional().describe('Human-readable target element description used to obtain the permission to interact with the element'),
- endRef: z.string().describe('Exact target element reference from the page snapshot'),
- endSelector: z.string().optional().describe('CSS or role selector for the target element, when ref is not available'),
+ endTarget: z.string().describe(elementTargetDescription),
}),
type: 'input',
},
@@ -112,9 +113,9 @@ const drag = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const [start, end] = await tab.refLocators([
- { ref: params.startRef, selector: params.startSelector, element: params.startElement },
- { ref: params.endRef, selector: params.endSelector, element: params.endElement },
+ const [start, end] = await tab.targetLocators([
+ { target: params.startTarget, element: params.startElement },
+ { target: params.endTarget, element: params.endElement },
]);
await tab.waitForCompletion(async () => {
@@ -138,7 +139,7 @@ const hover = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
response.addCode(`await page.${resolved}.hover();`);
await locator.hover(tab.actionTimeoutOptions);
@@ -162,7 +163,7 @@ const selectOption = defineTabTool({
handle: async (tab, params, response) => {
response.setIncludeSnapshot();
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
response.addCode(`await page.${resolved}.selectOption(${formatObject(params.values)});`);
await locator.selectOption(params.values, tab.actionTimeoutOptions);
@@ -180,7 +181,7 @@ const generateLocator = defineTabTool({
},
handle: async (tab, params, response) => {
- const { resolved } = await tab.refLocator(params);
+ const { resolved } = await tab.targetLocator(params);
response.addTextResult(resolved);
},
});
@@ -198,7 +199,7 @@ const check = defineTabTool({
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
response.addCode(`await page.${resolved}.check();`);
await locator.check(tab.actionTimeoutOptions);
},
@@ -216,7 +217,7 @@ const uncheck = defineTabTool({
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator(params);
+ const { locator, resolved } = await tab.targetLocator(params);
response.addCode(`await page.${resolved}.uncheck();`);
await locator.uncheck(tab.actionTimeoutOptions);
},
diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.ts
index f5a1f1077d..b4c23fec06 100644
--- a/packages/playwright-core/src/tools/backend/tab.ts
+++ b/packages/playwright-core/src/tools/backend/tab.ts
@@ -435,30 +435,30 @@ export class Tab extends EventEmitter<TabEventsInterface> {
await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
}
- async refLocator(params: { element?: string, ref: string, selector?: string }): Promise<{ locator: playwright.Locator, resolved: string }> {
+ async targetLocator(params: { element?: string, target: string }): Promise<{ locator: playwright.Locator, resolved: string }> {
await this._initializedPromise;
- return (await this.refLocators([params]))[0];
+ return (await this.targetLocators([params]))[0];
}
- async refLocators(params: { element?: string, ref: string, selector?: string }[]): Promise<{ locator: playwright.Locator, resolved: string }[]> {
+ async targetLocators(params: { element?: string, target: string }[]): Promise<{ locator: playwright.Locator, resolved: string }[]> {
await this._initializedPromise;
return Promise.all(params.map(async param => {
- if (param.selector) {
- const selector = locatorOrSelectorAsSelector('javascript', param.selector, this.context.config.testIdAttribute || 'data-testid');
+ if (!param.target.match(/(f\d+)?(e\d+)/)) {
+ const selector = locatorOrSelectorAsSelector('javascript', param.target, this.context.config.testIdAttribute || 'data-testid');
const handle = await this.page.$(selector);
if (!handle)
- throw new Error(`"${param.selector}" does not match any elements.`);
+ throw new Error(`"${param.target}" does not match any elements.`);
handle.dispose().catch(() => {});
return { locator: this.page.locator(selector), resolved: asLocator('javascript', selector) };
} else {
try {
- let locator = this.page.locator(`aria-ref=${param.ref}`);
+ let locator = this.page.locator(`aria-ref=${param.target}`);
if (param.element)
locator = locator.describe(param.element);
const resolved = await locator.normalize();
return { locator, resolved: resolved.toString() };
} catch (e) {
- throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
+ throw new Error(`Ref ${param.target} not found in the current page snapshot. Try capturing new snapshot.`);
}
}
}));
diff --git a/packages/playwright-core/src/tools/backend/verify.ts b/packages/playwright-core/src/tools/backend/verify.ts
index 99daa45337..29fd7f5977 100644
--- a/packages/playwright-core/src/tools/backend/verify.ts
+++ b/packages/playwright-core/src/tools/backend/verify.ts
@@ -81,15 +81,14 @@ const verifyList = defineTabTool({
description: 'Verify list is visible on the page',
inputSchema: z.object({
element: z.string().describe('Human-readable list description'),
- ref: z.string().describe('Exact target element reference that points to the list'),
- selector: z.string().optional().describe('CSS or role selector for the target list, when "ref" is not available.'),
+ target: z.string().describe('Exact target element reference that points to the list'),
items: z.array(z.string()).describe('Items to verify'),
}),
type: 'assertion',
},
handle: async (tab, params, response) => {
- const { locator } = await tab.refLocator({ ref: params.ref, selector: params.selector, element: params.element });
+ const { locator } = await tab.targetLocator(params);
const itemTexts: string[] = [];
for (const item of params.items) {
const itemLocator = locator.getByText(item);
@@ -117,15 +116,14 @@ const verifyValue = defineTabTool({
inputSchema: z.object({
type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the element'),
element: z.string().describe('Human-readable element description'),
- ref: z.string().describe('Exact target element reference from the page snapshot'),
- selector: z.string().optional().describe('CSS or role selector for the target element, when "ref" is not available'),
+ target: z.string().describe('Exact target element reference from the page snapshot'),
value: z.string().describe('Value to verify. For checkbox, use "true" or "false".'),
}),
type: 'assertion',
},
handle: async (tab, params, response) => {
- const { locator, resolved } = await tab.refLocator({ ref: params.ref, selector: params.selector, element: params.element });
+ const { locator, resolved } = await tab.targetLocator(params);
const locatorSource = `page.${resolved}`;
if (params.type === 'textbox' || params.type === 'slider' || params.type === 'combobox') {
const value = await locator.inputValue(tab.expectTimeoutOptions);
diff --git a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
index fac8c80391..c38e2ed07c 100644
--- a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
+++ b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
@@ -162,9 +162,12 @@ playwright-cli video-stop
# wait for the user to pick an element in the browser, print its ref and locator
playwright-cli pick
-# show a persistent highlight overlay for an element, or remove it with --hide
+# show a persistent highlight overlay for an element, optionally with a custom style
playwright-cli highlight e5
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+# hide a single element highlight, or all page highlights when no target is given
playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
```
## Raw output
@@ -353,10 +356,13 @@ Ask the user to point at an element in the browser, then keep it visible while y
playwright-cli open https://example.com
# blocks until the user clicks an element; prints `ref: eN` and the locator
playwright-cli pick
-# keep the picked element highlighted while iterating
-playwright-cli highlight e5
+# keep the picked element highlighted while iterating; style is optional
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+playwright-cli highlight e7
# ... inspect, generate code, etc. ...
+# hide a single highlight, or drop them all in one shot
playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
playwright-cli close
```
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index 7a02b86c26..780b7fe17b 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -19,6 +19,8 @@ import { declareCommand } from './command';
import type { AnyCommandSchema } from './command';
+const elementTargetDescription = 'Exact target element reference from the page snapshot, or a unique element selector';
+
const numberArg = z.preprocess((val, ctx) => {
const number = Number(val);
if (Number.isNaN(number)) {
@@ -31,14 +33,6 @@ const numberArg = z.preprocess((val, ctx) => {
return number;
}, z.number());
-function asRef(refOrSelector: string | undefined): { ref?: string, selector?: string } {
- if (refOrSelector === undefined)
- return {};
- if (refOrSelector.match(/^(f\d+)?e\d+$/))
- return { ref: refOrSelector };
- return { ref: '', selector: refOrSelector };
-}
-
// Navigation commands
const open = declareCommand({
@@ -228,14 +222,14 @@ const click = declareCommand({
description: 'Perform click on a web page',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
button: z.string().optional().describe('Button to click, defaults to left'),
}),
options: z.object({
modifiers: z.array(z.string()).optional().describe('Modifier keys to press'),
}),
toolName: 'browser_click',
- toolParams: ({ target, button, modifiers }) => ({ ...asRef(target), button, modifiers }),
+ toolParams: ({ target, button, modifiers }) => ({ target, button, modifiers }),
});
const doubleClick = declareCommand({
@@ -243,14 +237,14 @@ const doubleClick = declareCommand({
description: 'Perform double click on a web page',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
button: z.string().optional().describe('Button to click, defaults to left'),
}),
options: z.object({
modifiers: z.array(z.string()).optional().describe('Modifier keys to press'),
}),
toolName: 'browser_click',
- toolParams: ({ target, button, modifiers }) => ({ ...asRef(target), button, modifiers, doubleClick: true }),
+ toolParams: ({ target, button, modifiers }) => ({ target, button, modifiers, doubleClick: true }),
});
const drag = declareCommand({
@@ -258,15 +252,11 @@ const drag = declareCommand({
description: 'Perform drag and drop between two elements',
category: 'core',
args: z.object({
- startElement: z.string().describe('Exact source element reference from the page snapshot, or a unique element selector'),
- endElement: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ startTarget: z.string().describe('Exact source element reference from the page snapshot, or a unique element selector'),
+ endTarget: z.string().describe(elementTargetDescription),
}),
toolName: 'browser_drag',
- toolParams: ({ startElement, endElement }) => {
- const start = asRef(startElement);
- const end = asRef(endElement);
- return { startElement, startRef: start.ref, startSelector: start.selector, endElement, endRef: end.ref, endSelector: end.selector };
- },
+ toolParams: ({ startTarget, endTarget }) => ({ startTarget, endTarget }),
});
const fill = declareCommand({
@@ -274,14 +264,14 @@ const fill = declareCommand({
description: 'Fill text into editable element',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
text: z.string().describe('Text to fill into the element'),
}),
options: z.object({
submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
}),
toolName: 'browser_type',
- toolParams: ({ target, text, submit }) => ({ ...asRef(target), text, submit }),
+ toolParams: ({ target, text, submit }) => ({ target, text, submit }),
});
const hover = declareCommand({
@@ -289,10 +279,10 @@ const hover = declareCommand({
description: 'Hover over element on page',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
}),
toolName: 'browser_hover',
- toolParams: ({ target }) => ({ ...asRef(target) }),
+ toolParams: ({ target }) => ({ target }),
});
const select = declareCommand({
@@ -300,11 +290,11 @@ const select = declareCommand({
description: 'Select an option in a dropdown',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
val: z.string().describe('Value to select in the dropdown'),
}),
toolName: 'browser_select_option',
- toolParams: ({ target, val: value }) => ({ ...asRef(target), values: [value] }),
+ toolParams: ({ target, val: value }) => ({ target, values: [value] }),
});
const fileUpload = declareCommand({
@@ -323,10 +313,10 @@ const check = declareCommand({
description: 'Check a checkbox or radio button',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
}),
toolName: 'browser_check',
- toolParams: ({ target }) => ({ ...asRef(target) }),
+ toolParams: ({ target }) => ({ target }),
});
const uncheck = declareCommand({
@@ -334,10 +324,10 @@ const uncheck = declareCommand({
description: 'Uncheck a checkbox or radio button',
category: 'core',
args: z.object({
- target: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().describe(elementTargetDescription),
}),
toolName: 'browser_uncheck',
- toolParams: ({ target }) => ({ ...asRef(target) }),
+ toolParams: ({ target }) => ({ target }),
});
const snapshot = declareCommand({
@@ -345,14 +335,14 @@ const snapshot = declareCommand({
description: 'Capture page snapshot to obtain element ref',
category: 'core',
args: z.object({
- element: z.string().optional().describe('Element reference from the previous page snapshot, or a unique element selector for the root element to capture a partial snapshot instead of the whole page'),
+ target: z.string().optional().describe('Element reference from the previous page snapshot, or a unique element selector for the root element to capture a partial snapshot instead of the whole page'),
}),
options: z.object({
filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
depth: numberArg.optional().describe('Limit snapshot depth, unlimited by default.'),
}),
toolName: 'browser_snapshot',
- toolParams: ({ filename, element, depth }) => ({ filename, ...asRef(element), depth }),
+ toolParams: ({ filename, target, depth }) => ({ filename, target, depth }),
});
const pick = declareCommand({
@@ -366,17 +356,17 @@ const pick = declareCommand({
const highlight = declareCommand({
name: 'highlight',
- description: 'Show (or with --hide, remove) a highlight overlay for an element',
+ description: 'Show (or with --hide, remove) a highlight overlay for an element; `--hide` without a target hides all page highlights.',
category: 'devtools',
args: z.object({
- element: z.string().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().optional().describe(elementTargetDescription),
}),
options: z.object({
- hide: z.boolean().optional().describe('Hide a previously added highlight for this element'),
+ hide: z.boolean().optional().describe('Hide a previously added highlight for this element, or all page highlights when no element is given'),
style: z.string().optional().describe('Additional inline CSS applied to the highlight overlay, e.g. "outline: 2px dashed red"'),
}),
toolName: ({ hide }) => hide ? 'browser_hide_highlight' : 'browser_highlight',
- toolParams: ({ element, style }) => ({ ...asRef(element), style }),
+ toolParams: ({ target, style }) => ({ target, style }),
});
const evaluate = declareCommand({
@@ -385,13 +375,13 @@ const evaluate = declareCommand({
category: 'core',
args: z.object({
func: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
- element: z.string().optional().describe('Exact target element reference from the page snapshot, or a unique element selector'),
+ target: z.string().optional().describe(elementTargetDescription),
}),
options: z.object({
filename: z.string().optional().describe('Save evaluation result to a file instead of returning it in the response.'),
}),
toolName: 'browser_evaluate',
- toolParams: ({ func, element, filename }) => ({ function: func, filename, ...asRef(element) }),
+ toolParams: ({ func, target, filename }) => ({ function: func, filename, target }),
});
const dialogAccept = declareCommand({
@@ -747,14 +737,14 @@ const screenshot = declareCommand({
description: 'screenshot of the current page or element',
category: 'export',
args: z.object({
- target: z.string().optional().describe('Exact target element reference from the page snapshot, or a unique element selector.'),
+ target: z.string().optional().describe(elementTargetDescription),
}),
options: z.object({
filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
['full-page']: z.boolean().optional().describe('When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport.'),
}),
toolName: 'browser_take_screenshot',
- toolParams: ({ target, filename, ['full-page']: fullPage }) => ({ filename, ...asRef(target), fullPage }),
+ toolParams: ({ target, filename, ['full-page']: fullPage }) => ({ filename, target, fullPage }),
});
const pdfSave = declareCommand({
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index eea0869050..a8cd0cf0dc 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -3247,6 +3247,12 @@ export interface Page {
waitUntil?: "load"|"domcontentloaded"|"networkidle"|"commit";
}): Promise<null|Response>;
+ /**
+ * Hide all locator highlight overlays previously added by
+ * [locator.highlight([options])](https://playwright.dev/docs/api/class-locator#locator-highlight) on this page.
+ */
+ hideHighlight(): Promise<void>;
+
/**
* **NOTE** Use locator-based [locator.hover([options])](https://playwright.dev/docs/api/class-locator#locator-hover) instead.
* Read more about [locators](https://playwright.dev/docs/locators).
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 57b97c55bf..4f0613005c 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -2160,6 +2160,7 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
bringToFront(params?: PageBringToFrontParams, progress?: Progress): Promise<PageBringToFrontResult>;
pickLocator(params?: PagePickLocatorParams, progress?: Progress): Promise<PagePickLocatorResult>;
cancelPickLocator(params?: PageCancelPickLocatorParams, progress?: Progress): Promise<PageCancelPickLocatorResult>;
+ hideHighlight(params?: PageHideHighlightParams, progress?: Progress): Promise<PageHideHighlightResult>;
screencastShowOverlay(params: PageScreencastShowOverlayParams, progress?: Progress): Promise<PageScreencastShowOverlayResult>;
screencastRemoveOverlay(params: PageScreencastRemoveOverlayParams, progress?: Progress): Promise<PageScreencastRemoveOverlayResult>;
screencastChapter(params: PageScreencastChapterParams, progress?: Progress): Promise<PageScreencastChapterResult>;
@@ -2682,6 +2683,9 @@ export type PagePickLocatorResult = {
export type PageCancelPickLocatorParams = {};
export type PageCancelPickLocatorOptions = {};
export type PageCancelPickLocatorResult = void;
+export type PageHideHighlightParams = {};
+export type PageHideHighlightOptions = {};
+export type PageHideHighlightResult = void;
export type PageScreencastShowOverlayParams = {
html: string,
duration?: number,
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 9060ef4cf8..0cdaf38f6d 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -2095,6 +2095,10 @@ Page:
title: Cancel pick locator
group: configuration
+ hideHighlight:
+ title: Hide all element highlights
+ group: configuration
+
screencastShowOverlay:
title: Show overlay
group: configuration
diff --git a/tests/library/locator-highlight.spec.ts b/tests/library/locator-highlight.spec.ts
index 7cc7a33866..4024ef628e 100644
--- a/tests/library/locator-highlight.spec.ts
+++ b/tests/library/locator-highlight.spec.ts
@@ -75,3 +75,18 @@ test('hideHighlight removes a styled highlight', async ({ browser, server }) =>
await context.close();
});
+
+test('Page.hideHighlight clears all locator highlights', async ({ browser, server }) => {
+ const context = await browser.newContext();
+ const page = await context.newPage();
+ await page.setContent(`<button>One</button><button>Two</button>`);
+
+ await page.getByRole('button', { name: 'One' }).highlight();
+ await page.getByRole('button', { name: 'Two' }).highlight();
+ await expect(page.locator('x-pw-highlight')).toHaveCount(2);
+
+ await page.hideHighlight();
+ await expect(page.locator('x-pw-highlight')).toHaveCount(0);
+
+ await context.close();
+});
diff --git a/tests/mcp/autowait.spec.ts b/tests/mcp/autowait.spec.ts
index d5d13c16e5..a631b70925 100644
--- a/tests/mcp/autowait.spec.ts
+++ b/tests/mcp/autowait.spec.ts
@@ -30,7 +30,7 @@ test('racy navigation destroys context', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Submit' }).click();`,
diff --git a/tests/mcp/cdp.spec.ts b/tests/mcp/cdp.spec.ts
index edd3261c68..0fbada3211 100644
--- a/tests/mcp/cdp.spec.ts
+++ b/tests/mcp/cdp.spec.ts
@@ -43,10 +43,10 @@ test('cdp server reuse tab', async ({ cdpServer, startClient, server }) => {
name: 'browser_click',
arguments: {
element: 'Hello, world!',
- ref: 'f0',
+ target: 'f0',
},
})).toHaveResponse({
- error: `Error: Ref f0 not found in the current page snapshot. Try capturing new snapshot.`,
+ error: `Error: "f0" does not match any elements.`,
isError: true,
});
diff --git a/tests/mcp/cli-devtools.spec.ts b/tests/mcp/cli-devtools.spec.ts
index 246bcee70e..467b2a8bdc 100644
--- a/tests/mcp/cli-devtools.spec.ts
+++ b/tests/mcp/cli-devtools.spec.ts
@@ -191,7 +191,7 @@ test('highlight', async ({ cdpServer, cli, server }) => {
await cli('snapshot');
const { output } = await cli('highlight', 'e2');
- expect(output).toContain(`Highlighted getByRole('button', { name: 'Submit' })`);
+ expect(output).toContain(`Highlighted locator('aria-ref=e2')`);
const highlight = page.locator('x-pw-highlight');
const tooltip = page.locator('x-pw-tooltip-line');
@@ -213,7 +213,25 @@ test('highlight --hide', async ({ cdpServer, cli, server }) => {
await expect(page.locator('x-pw-highlight')).toBeVisible();
const { output } = await cli('highlight', 'e2', '--hide');
- expect(output).toContain(`Hid highlight for getByRole('button', { name: 'Submit' })`);
+ expect(output).toContain(`Hid highlight for locator('aria-ref=e2')`);
+ await expect(page.locator('x-pw-highlight')).toHaveCount(0);
+});
+
+test('highlight --hide all', async ({ cdpServer, cli, server }) => {
+ server.setContent('/', `<button>Submit</button><a href="#">Go</a>`, 'text/html');
+ const browserContext = await cdpServer.start();
+ const [page] = browserContext.pages();
+ await page.goto(server.PREFIX);
+
+ await cli('attach', `--cdp=${cdpServer.endpoint}`);
+ await cli('snapshot');
+
+ await cli('highlight', 'e2');
+ await cli('highlight', 'e3');
+ await expect(page.locator('x-pw-highlight')).toHaveCount(2);
+
+ const { output } = await cli('highlight', '--hide');
+ expect(output).toContain('Hid page highlight');
await expect(page.locator('x-pw-highlight')).toHaveCount(0);
});
diff --git a/tests/mcp/click.spec.ts b/tests/mcp/click.spec.ts
index e140669c12..dcb7acf156 100644
--- a/tests/mcp/click.spec.ts
+++ b/tests/mcp/click.spec.ts
@@ -37,7 +37,7 @@ test('browser_click', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Submit' }).click();`,
@@ -65,7 +65,7 @@ test('browser_click (double)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Click me',
- ref: 'e2',
+ target: 'e2',
doubleClick: true,
},
})).toHaveResponse({
@@ -94,7 +94,7 @@ test('browser_click (right)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Menu',
- ref: 'e2',
+ target: 'e2',
button: 'right',
},
});
@@ -130,7 +130,7 @@ test('browser_click (modifiers)', async ({ client, server, mcpBrowser }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
modifiers: ['Control'],
},
})).toHaveResponse({
@@ -147,7 +147,7 @@ test('browser_click (modifiers)', async ({ client, server, mcpBrowser }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
modifiers: ['Shift'],
},
})).toHaveResponse({
@@ -163,7 +163,7 @@ test('browser_click (modifiers)', async ({ client, server, mcpBrowser }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
modifiers: ['Shift', 'Alt'],
},
})).toHaveResponse({
@@ -196,7 +196,7 @@ test('browser_click (test id attribute)', async ({ startClient, server, mcpBrows
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByTestId('submit').click();`,
diff --git a/tests/mcp/console.spec.ts b/tests/mcp/console.spec.ts
index c3b49ea86b..ee3e030301 100644
--- a/tests/mcp/console.spec.ts
+++ b/tests/mcp/console.spec.ts
@@ -97,7 +97,7 @@ test('recent console messages', async ({ client, server }, testInfo) => {
name: 'browser_click',
arguments: {
element: 'Click me',
- ref: 'e2',
+ target: 'e2',
},
}));
@@ -355,13 +355,13 @@ test('console log file appends on multiple snapshots', async ({ startClient, ser
// Click button to generate console message
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Click me', ref: 'e2' },
+ arguments: { element: 'Click me', target: 'e2' },
});
// Click again
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Click me', ref: 'e2' },
+ arguments: { element: 'Click me', target: 'e2' },
});
// Verify only one log file exists (same page, appended)
diff --git a/tests/mcp/core.spec.ts b/tests/mcp/core.spec.ts
index 9a6e3fa409..15c57d21b7 100644
--- a/tests/mcp/core.spec.ts
+++ b/tests/mcp/core.spec.ts
@@ -104,7 +104,7 @@ test('browser_select_option', async ({ client, server }) => {
name: 'browser_select_option',
arguments: {
element: 'Select',
- ref: 'e2',
+ target: 'e2',
values: ['bar'],
},
})).toHaveResponse({
@@ -133,7 +133,7 @@ test('browser_select_option (multiple)', async ({ client, server }) => {
name: 'browser_select_option',
arguments: {
element: 'Select',
- ref: 'e2',
+ target: 'e2',
values: ['bar', 'baz'],
},
})).toHaveResponse({
@@ -200,7 +200,7 @@ test('old locator error message', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button 1',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -208,7 +208,7 @@ test('old locator error message', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button 2',
- ref: 'e3',
+ target: 'e3',
},
})).toHaveResponse({
error: expect.stringContaining(`Ref e3 not found in the current page snapshot. Try capturing new snapshot.`),
@@ -294,7 +294,7 @@ test('snapshot by ref', { annotation: { type: 'issue', description: 'https://git
expect(await client.callTool({
name: 'browser_snapshot',
arguments: {
- ref: 'e2',
+ target: 'e2',
}
})).toHaveResponse({
inlineSnapshot: `- list [ref=e2]:
@@ -306,7 +306,7 @@ test('snapshot by ref', { annotation: { type: 'issue', description: 'https://git
expect(await client.callTool({
name: 'browser_snapshot',
arguments: {
- ref: 'e999',
+ target: 'e999',
}
})).toHaveResponse({
error: expect.stringContaining(`Ref e999 not found in the current page snapshot. Try capturing new snapshot.`),
diff --git a/tests/mcp/devtools.spec.ts b/tests/mcp/devtools.spec.ts
index 51ab6c0c93..f80b1718af 100644
--- a/tests/mcp/devtools.spec.ts
+++ b/tests/mcp/devtools.spec.ts
@@ -50,9 +50,9 @@ test('browser_highlight', async ({ cdpServer, startClient, server }) => {
expect(await client.callTool({
name: 'browser_highlight',
- arguments: { element: 'Submit button', ref: 'e2' },
+ arguments: { element: 'Submit button', target: 'e2' },
})).toHaveResponse({
- result: `Highlighted getByRole('button', { name: 'Submit' })`,
+ result: `Highlighted Submit button`,
});
const highlight = page.locator('x-pw-highlight');
@@ -75,11 +75,11 @@ test('browser_highlight with style', async ({ cdpServer, startClient, server })
name: 'browser_highlight',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
style: 'outline: 3px solid rgb(255, 0, 0); background-color: rgba(0, 255, 0, 0.25)',
},
})).toHaveResponse({
- result: `Highlighted getByRole('button', { name: 'Submit' })`,
+ result: `Highlighted Submit button`,
});
const highlight = page.locator('x-pw-highlight');
@@ -104,15 +104,37 @@ test('browser_hide_highlight', async ({ cdpServer, startClient, server }) => {
await client.callTool({
name: 'browser_highlight',
- arguments: { element: 'Submit button', ref: 'e2' },
+ arguments: { element: 'Submit button', target: 'e2' },
});
await expect(page.locator('x-pw-highlight')).toBeVisible();
expect(await client.callTool({
name: 'browser_hide_highlight',
- arguments: { element: 'Submit button', ref: 'e2' },
+ arguments: { element: 'Submit button', target: 'e2' },
})).toHaveResponse({
- result: `Hid highlight for getByRole('button', { name: 'Submit' })`,
+ result: `Hid highlight for Submit button`,
+ });
+ await expect(page.locator('x-pw-highlight')).toHaveCount(0);
+});
+
+test('browser_hide_highlight all', async ({ cdpServer, startClient, server }) => {
+ server.setContent('/', `<button>Submit</button><a href="#">Go</a>`, 'text/html');
+ const browserContext = await cdpServer.start();
+ const [page] = browserContext.pages();
+ await page.goto(server.PREFIX);
+
+ const { client } = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
+ await client.callTool({ name: 'browser_snapshot' });
+
+ await client.callTool({ name: 'browser_highlight', arguments: { element: 'Submit button', target: 'e2' } });
+ await client.callTool({ name: 'browser_highlight', arguments: { element: 'Go link', target: 'e3' } });
+ await expect(page.locator('x-pw-highlight')).toHaveCount(2);
+
+ expect(await client.callTool({
+ name: 'browser_hide_highlight',
+ arguments: {},
+ })).toHaveResponse({
+ result: 'Hid page highlight',
});
await expect(page.locator('x-pw-highlight')).toHaveCount(0);
});
diff --git a/tests/mcp/dialogs.spec.ts b/tests/mcp/dialogs.spec.ts
index 4c876e9e0c..57d3d39a18 100644
--- a/tests/mcp/dialogs.spec.ts
+++ b/tests/mcp/dialogs.spec.ts
@@ -29,7 +29,7 @@ test('alert dialog', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Button' }).click();`,
@@ -40,7 +40,7 @@ test('alert dialog', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: undefined,
@@ -77,7 +77,7 @@ test('two alert dialogs', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Button' }).click();`,
@@ -126,7 +126,7 @@ test('confirm dialog (true)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
modalState: expect.stringContaining(`- ["confirm" dialog with message "Confirm"]: can be handled by browser_handle_dialog`),
@@ -161,7 +161,7 @@ test('confirm dialog (false)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
modalState: expect.stringContaining(`- ["confirm" dialog with message "Confirm"]: can be handled by browser_handle_dialog`),
@@ -196,7 +196,7 @@ test('prompt dialog', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
modalState: expect.stringContaining(`- ["prompt" dialog with message "Prompt"]: can be handled by browser_handle_dialog`),
@@ -228,7 +228,7 @@ test('alert dialog w/ race', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Button' }).click();`,
diff --git a/tests/mcp/evaluate.spec.ts b/tests/mcp/evaluate.spec.ts
index 3c0b7a5b60..25ffd5a597 100644
--- a/tests/mcp/evaluate.spec.ts
+++ b/tests/mcp/evaluate.spec.ts
@@ -49,7 +49,7 @@ test('browser_evaluate (element)', async ({ client, server }) => {
arguments: {
function: 'element => element.style.backgroundColor',
element: 'body',
- ref: 'e1',
+ target: 'e1',
},
})).toHaveResponse({
result: `"red"`,
diff --git a/tests/mcp/files.spec.ts b/tests/mcp/files.spec.ts
index c922151cb0..8ab29670c2 100644
--- a/tests/mcp/files.spec.ts
+++ b/tests/mcp/files.spec.ts
@@ -49,7 +49,7 @@ test('browser_file_upload', async ({ client, server }, testInfo) => {
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
modalState: expect.stringContaining(`- [File chooser]: can be handled by browser_file_upload`),
@@ -77,7 +77,7 @@ test('browser_file_upload', async ({ client, server }, testInfo) => {
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -91,7 +91,7 @@ test('browser_file_upload', async ({ client, server }, testInfo) => {
name: 'browser_click',
arguments: {
element: 'Button',
- ref: 'e3',
+ target: 'e3',
},
});
@@ -122,7 +122,7 @@ test('clicking on download link emits download', async ({ startClient, server },
name: 'browser_click',
arguments: {
element: 'Download link',
- ref: 'e2',
+ target: 'e2',
},
});
const parsed = parseResponse(response);
@@ -186,7 +186,7 @@ test('file upload restricted to roots by default', async ({ startClient, server
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -209,7 +209,7 @@ test('file upload restricted to roots by default', async ({ startClient, server
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -249,7 +249,7 @@ test('file upload is restricted to cwd if no roots are configured', async ({ sta
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -272,7 +272,7 @@ test('file upload is restricted to cwd if no roots are configured', async ({ sta
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -318,7 +318,7 @@ test('file upload unrestricted when flag is set', async ({ startClient, server }
name: 'browser_click',
arguments: {
element: 'Textbox',
- ref: 'e2',
+ target: 'e2',
},
});
diff --git a/tests/mcp/form.spec.ts b/tests/mcp/form.spec.ts
index ecbffd82ed..46e5c6a8bc 100644
--- a/tests/mcp/form.spec.ts
+++ b/tests/mcp/form.spec.ts
@@ -63,31 +63,31 @@ test('browser_fill_form (textbox)', async ({ client, server }) => {
{
name: 'Name textbox',
type: 'textbox',
- ref: 'e4',
+ target: 'e4',
value: 'John Doe'
},
{
name: 'Email textbox',
type: 'textbox',
- ref: 'e6',
+ target: 'e6',
},
{
name: 'Age textbox',
type: 'slider',
- ref: 'e8',
+ target: 'e8',
value: '25'
},
{
name: 'Country select',
type: 'combobox',
- ref: 'e10',
+ target: 'e10',
value: 'United States'
},
{
name: 'Subscribe checkbox',
type: 'checkbox',
- ref: 'e12',
+ target: 'e12',
value: 'true'
},
]
diff --git a/tests/mcp/generator.spec.ts b/tests/mcp/generator.spec.ts
index 81bac70222..b163ac4992 100644
--- a/tests/mcp/generator.spec.ts
+++ b/tests/mcp/generator.spec.ts
@@ -87,7 +87,7 @@ test('generator_setup_page', async ({ startClient }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
intent: 'Click submit button',
},
});
@@ -151,7 +151,7 @@ test('click after generator_log_action', async ({ startClient }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
intent: 'Click submit button',
},
})).toHaveResponse({
@@ -304,7 +304,7 @@ test('should respect custom test id', async ({ startClient }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
intent: 'Click submit button',
},
})).toHaveResponse({
diff --git a/tests/mcp/iframes.spec.ts b/tests/mcp/iframes.spec.ts
index b8ca950913..bd2bbe46cc 100644
--- a/tests/mcp/iframes.spec.ts
+++ b/tests/mcp/iframes.spec.ts
@@ -37,7 +37,7 @@ test('stitched aria frames', async ({ client }) => {
name: 'browser_click',
arguments: {
element: 'World',
- ref: 'f1e2',
+ target: 'f1e2',
},
})).toHaveResponse({
code: `await page.locator('iframe').first().contentFrame().getByRole('button', { name: 'World' }).click();`,
diff --git a/tests/mcp/network.spec.ts b/tests/mcp/network.spec.ts
index 94ee4cad6e..00a0129694 100644
--- a/tests/mcp/network.spec.ts
+++ b/tests/mcp/network.spec.ts
@@ -35,7 +35,7 @@ test('browser_network_requests', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Click me button',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -95,7 +95,7 @@ test('browser_network_requests includes request headers', async ({ client, serve
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Click me button', ref: 'e2' },
+ arguments: { element: 'Click me button', target: 'e2' },
});
{
@@ -134,7 +134,7 @@ test('browser_network_requests includes request payload', async ({ client, serve
name: 'browser_click',
arguments: {
element: 'Click me button',
- ref: 'e2',
+ target: 'e2',
},
});
diff --git a/tests/mcp/planner.spec.ts b/tests/mcp/planner.spec.ts
index 736b56b61d..2e68d64780 100644
--- a/tests/mcp/planner.spec.ts
+++ b/tests/mcp/planner.spec.ts
@@ -57,7 +57,7 @@ test('planner_setup_page', async ({ startClient }) => {
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
intent: 'Click on the "Submit" button',
},
})).toHaveResponse({
diff --git a/tests/mcp/route.spec.ts b/tests/mcp/route.spec.ts
index f0904893fd..6c1b5267a3 100644
--- a/tests/mcp/route.spec.ts
+++ b/tests/mcp/route.spec.ts
@@ -45,7 +45,7 @@ test('browser_route mocks response with JSON body', async ({ client, server }) =
// Click the button to trigger the fetch
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Fetch button', ref: 'e2' },
+ arguments: { element: 'Fetch button', target: 'e2' },
});
// Wait for the mocked response to be rendered
@@ -84,7 +84,7 @@ test('browser_route mocks response with custom status', async ({ client, server
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Fetch button', ref: 'e2' },
+ arguments: { element: 'Fetch button', target: 'e2' },
});
// Wait for the status to be rendered
@@ -129,7 +129,7 @@ test('browser_route modifies request headers', async ({ client, server }) => {
const requestPromise = server.waitForRequest('/api/check');
await client.callTool({
name: 'browser_click',
- arguments: { element: 'Fetch button', ref: 'e2' },
+ arguments: { element: 'Fetch button', target: 'e2' },
});
await requestPromise;
diff --git a/tests/mcp/screenshot.spec.ts b/tests/mcp/screenshot.spec.ts
index f233eeb3f1..bbe3c74d79 100644
--- a/tests/mcp/screenshot.spec.ts
+++ b/tests/mcp/screenshot.spec.ts
@@ -57,7 +57,7 @@ test('browser_take_screenshot (element)', async ({ startClient, server }, testIn
name: 'browser_take_screenshot',
arguments: {
element: 'hello button',
- ref: 'e1',
+ target: 'e1',
},
})).toEqual({
content: [
@@ -365,7 +365,7 @@ test('browser_take_screenshot (fullPage with element should error)', async ({ st
arguments: {
fullPage: true,
element: 'hello button',
- ref: 'e1',
+ target: 'e1',
},
});
diff --git a/tests/mcp/secrets.spec.ts b/tests/mcp/secrets.spec.ts
index 5d4e55a5d0..eeae81a5be 100644
--- a/tests/mcp/secrets.spec.ts
+++ b/tests/mcp/secrets.spec.ts
@@ -45,7 +45,7 @@ test('browser_type', async ({ startClient, server }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'X-PASSWORD',
submit: true,
},
@@ -103,13 +103,13 @@ test('browser_fill_form', async ({ startClient, server }) => {
{
name: 'Email textbox',
type: 'textbox',
- ref: 'e4',
+ target: 'e4',
value: 'John Doe'
},
{
name: 'Password textbox',
type: 'textbox',
- ref: 'e6',
+ target: 'e6',
value: 'X-PASSWORD'
},
]
diff --git a/tests/mcp/session-log.spec.ts b/tests/mcp/session-log.spec.ts
index 78c9b4a60b..8fac3c6296 100644
--- a/tests/mcp/session-log.spec.ts
+++ b/tests/mcp/session-log.spec.ts
@@ -40,7 +40,7 @@ test('session log should record tool calls', async ({ startClient, server, mcpBr
name: 'browser_click',
arguments: {
element: 'Submit button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
code: `await page.getByRole('button', { name: 'Submit' }).click();`,
@@ -70,7 +70,7 @@ test('session log should record tool calls', async ({ startClient, server, mcpBr
\\\`\\\`\\\`json
\\{
"element": "Submit button",
- "ref": "e2"
+ "target": "e2"
\\}
\\\`\\\`\\\`
- Result
diff --git a/tests/mcp/test-debug.spec.ts b/tests/mcp/test-debug.spec.ts
index 2ce3342655..c81ed7825e 100644
--- a/tests/mcp/test-debug.spec.ts
+++ b/tests/mcp/test-debug.spec.ts
@@ -285,7 +285,7 @@ test('test_debug / evaluate (with element)', async ({ startClient }) => {
arguments: {
function: 'element => element.textContent',
element: 'button',
- ref: 'e2',
+ target: 'e2',
intent: 'Get button text',
},
})).toHaveResponse({
@@ -305,7 +305,7 @@ test('test_debug / generate_locator', async ({ startClient }) => {
name: 'browser_generate_locator',
arguments: {
element: 'button',
- ref: 'e2',
+ target: 'e2',
},
})).toHaveResponse({
result: `getByRole('button', { name: 'Submit' })`,
diff --git a/tests/mcp/timeouts.spec.ts b/tests/mcp/timeouts.spec.ts
index 4f99cb5ffe..6038db5b42 100644
--- a/tests/mcp/timeouts.spec.ts
+++ b/tests/mcp/timeouts.spec.ts
@@ -36,7 +36,7 @@ test('action timeout (default)', async ({ server, startClient }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'Hi!',
submit: true,
},
@@ -66,7 +66,7 @@ test('action timeout (custom)', async ({ startClient, server }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'Hi!',
submit: true,
},
diff --git a/tests/mcp/type.spec.ts b/tests/mcp/type.spec.ts
index 1932e8c4f7..c128346e2f 100644
--- a/tests/mcp/type.spec.ts
+++ b/tests/mcp/type.spec.ts
@@ -36,7 +36,7 @@ test('browser_type', async ({ client, server }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'Hi!',
submit: true,
},
@@ -71,7 +71,7 @@ test('browser_type (slowly)', async ({ client, server }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'Hi!',
slowly: true,
},
@@ -117,7 +117,7 @@ test('browser_type (no submit)', async ({ client, server }) => {
name: 'browser_type',
arguments: {
element: 'textbox',
- ref: 'e2',
+ target: 'e2',
text: 'Hi!',
},
});
diff --git a/tests/mcp/verify.spec.ts b/tests/mcp/verify.spec.ts
index ceb2b0e717..a98a00fa6f 100644
--- a/tests/mcp/verify.spec.ts
+++ b/tests/mcp/verify.spec.ts
@@ -255,7 +255,7 @@ test('browser_verify_list_visible', async ({ client, server }) => {
name: 'browser_verify_list_visible',
arguments: {
element: 'Fruit list',
- ref: 'e2',
+ target: 'e2',
items: ['Apple', 'Banana', 'Cherry'],
},
})).toHaveResponse({
@@ -289,7 +289,7 @@ test('browser_verify_list_visible (partial items)', async ({ client, server }) =
name: 'browser_verify_list_visible',
arguments: {
element: 'Fruit list',
- ref: 'e2',
+ target: 'e2',
items: ['Apple', 'Cherry'],
},
})).toHaveResponse({
@@ -320,7 +320,7 @@ test('browser_verify_list_visible (item not found)', async ({ client, server })
name: 'browser_verify_list_visible',
arguments: {
element: 'Fruit list',
- ref: 'e2',
+ target: 'e2',
items: ['Apple', 'Cherry'],
},
})).toHaveResponse({
@@ -348,7 +348,7 @@ test('browser_verify_value (textbox)', async ({ client, server }) => {
arguments: {
type: 'textbox',
element: 'Name textbox',
- ref: 'e3',
+ target: 'e3',
value: 'John Doe',
},
})).toHaveResponse({
@@ -361,7 +361,7 @@ test('browser_verify_value (textbox)', async ({ client, server }) => {
arguments: {
type: 'textbox',
element: 'Email textbox',
- ref: 'e4',
+ target: 'e4',
},
})).toHaveResponse({
@@ -388,7 +388,7 @@ test('browser_verify_value (textbox wrong value)', async ({ client, server }) =>
arguments: {
type: 'textbox',
element: 'Name textbox',
- ref: 'e3',
+ target: 'e3',
value: 'Jane Smith',
},
})).toHaveResponse({
@@ -416,7 +416,7 @@ test('browser_verify_value (checkbox checked)', async ({ client, server }) => {
arguments: {
type: 'checkbox',
element: 'Subscribe checkbox',
- ref: 'e3',
+ target: 'e3',
value: 'true',
},
})).toHaveResponse({
@@ -444,7 +444,7 @@ test('browser_verify_value (checkbox unchecked)', async ({ client, server }) =>
arguments: {
type: 'checkbox',
element: 'Subscribe checkbox',
- ref: 'e3',
+ target: 'e3',
value: 'false',
},
})).toHaveResponse({
@@ -472,7 +472,7 @@ test('browser_verify_value (checkbox wrong value)', async ({ client, server }) =
arguments: {
type: 'checkbox',
element: 'Subscribe checkbox',
- ref: 'e3',
+ target: 'e3',
value: 'false',
},
})).toHaveResponse({
@@ -502,7 +502,7 @@ test('browser_verify_value (radio checked)', async ({ client, server }) => {
arguments: {
type: 'radio',
element: 'Color radio',
- ref: 'e3',
+ target: 'e3',
value: 'true',
},
})).toHaveResponse({
@@ -530,7 +530,7 @@ test('browser_verify_value (slider)', async ({ client, server }) => {
arguments: {
type: 'slider',
element: 'Volume slider',
- ref: 'e3',
+ target: 'e3',
value: '75',
},
})).toHaveResponse({
@@ -561,7 +561,7 @@ test('browser_verify_value (combobox)', async ({ client, server }) => {
arguments: {
type: 'combobox',
element: 'Country select',
- ref: 'e3',
+ target: 'e3',
value: 'United States',
},
})).toHaveResponse({
diff --git a/tests/mcp/wait.spec.ts b/tests/mcp/wait.spec.ts
index 7608cb19cc..561f375e51 100644
--- a/tests/mcp/wait.spec.ts
+++ b/tests/mcp/wait.spec.ts
@@ -42,7 +42,7 @@ test('browser_wait_for(text)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Click me',
- ref: 'e2',
+ target: 'e2',
},
});
@@ -84,7 +84,7 @@ test('browser_wait_for(textGone)', async ({ client, server }) => {
name: 'browser_click',
arguments: {
element: 'Click me',
- ref: 'e2',
+ target: 'e2',
},
});