Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.mdindex 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.mdindex 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/WeReferer 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.tsindex 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.tsindex 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.tsindex 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.Pageawait 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.tsindex 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.tsindex 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, Browsawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 })});`);elseresponse.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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 locatorplaywright-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 styleplaywright-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 givenplaywright-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 yplaywright-cli open https://example.com# blocks until the user clicks an element; prints `ref: eN` and the locatorplaywright-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 shotplaywright-cli highlight e5 --hide+playwright-cli highlight --hideplaywright-cli close```diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.tsindex 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 commandsconst 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.tsindex 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.tsindex 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.ymlindex 9060ef4cf8..0cdaf38f6d 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -2095,6 +2095,10 @@ Page:title: Cancel pick locatorgroup: configuration+ hideHighlight:+ title: Hide all element highlights+ group: configuration+screencastShowOverlay:title: Show overlaygroup: configurationdiff --git a/tests/library/locator-highlight.spec.ts b/tests/library/locator-highlight.spec.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, mcpBrowsname: '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.tsindex 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 messageawait client.callTool({name: 'browser_click',- arguments: { element: 'Click me', ref: 'e2' },+ arguments: { element: 'Click me', target: 'e2' },});// Click againawait 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.tsindex 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://gitexpect(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://gitexpect(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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, servername: 'browser_click',arguments: {element: 'Textbox',- ref: 'e2',+ target: 'e2',},});@@ -209,7 +209,7 @@ test('file upload restricted to roots by default', async ({ startClient, servername: '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 ({ staname: '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 ({ staname: '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.tsindex 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',value: '[email protected]'},{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.tsindex 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.tsindex 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.tsindex 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, serveawait 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, servename: 'browser_click',arguments: {element: 'Click me button',- ref: 'e2',+ target: 'e2',},});diff --git a/tests/mcp/planner.spec.ts b/tests/mcp/planner.spec.tsindex 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.tsindex 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 fetchawait 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, serverawait 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.tsindex 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 }, testInname: '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 ({ starguments: {fullPage: true,element: 'hello button',- ref: 'e1',+ target: 'e1',},});diff --git a/tests/mcp/secrets.spec.ts b/tests/mcp/secrets.spec.tsindex 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.tsindex 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, mcpBrname: '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"\\}\\\`\\\`\\\`- Resultdiff --git a/tests/mcp/test-debug.spec.ts b/tests/mcp/test-debug.spec.tsindex 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.tsindex 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.tsindex 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.tsindex 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',value: '[email protected]',},})).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.tsindex 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',},});