diff --git a/mcp/installation.mdx b/mcp/installation.mdx index cd561ffd60..c08f8baa5f 100644 --- a/mcp/installation.mdx +++ b/mcp/installation.mdx @@ -43,7 +43,7 @@ The assistant calls MCP tools to open the browser, navigate, and interact — re - heading "todos" [level=1] - textbox "What needs to be done?" [ref=e5] -→ browser_type { ref: "e5", text: "Buy groceries", submit: true } +→ browser_type { target: "e5", text: "Buy groceries", submit: true } → browser_snapshot - heading "todos" [level=1] diff --git a/mcp/introduction.mdx b/mcp/introduction.mdx index 097fb233c2..2c46ce95c3 100644 --- a/mcp/introduction.mdx +++ b/mcp/introduction.mdx @@ -17,7 +17,7 @@ You: Navigate to https://demo.playwright.dev/todomvc and add "Buy groceries". - heading "todos" [level=1] - textbox "What needs to be done?" [ref=e5] -→ browser_type { ref: "e5", text: "Buy groceries", submit: true } +→ browser_type { target: "e5", text: "Buy groceries", submit: true } → browser_snapshot - heading "todos" [level=1] diff --git a/mcp/snapshots.mdx b/mcp/snapshots.mdx index dfa0e1e78a..a3e2619d4c 100644 --- a/mcp/snapshots.mdx +++ b/mcp/snapshots.mdx @@ -27,9 +27,9 @@ Playwright MCP uses accessibility snapshots instead of screenshots. Every tool t Each interactive element gets a unique **ref** (e.g., `ref=e5`). The LLM uses these refs to interact: ``` -browser_type { ref: "e5", text: "headphones" } → type into search -browser_click { ref: "e10" } → check the checkbox -browser_click { ref: "e20" } → click the "All" link +browser_type { target: "e5", text: "headphones" } → type into search +browser_click { target: "e10" } → check the checkbox +browser_click { target: "e20" } → click the "All" link ``` ## Element refs diff --git a/mcp/tools/assertions.mdx b/mcp/tools/assertions.mdx index 7f87658c1a..a37359a903 100644 --- a/mcp/tools/assertions.mdx +++ b/mcp/tools/assertions.mdx @@ -64,11 +64,11 @@ Verify page state and generate Playwright test code. Requires the **testing** [c | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference | +| `target` | string | yes | Exact target element reference from the page snapshot | | `value` | string | yes | Expected value | ```txt -→ browser_verify_value { ref: "e3", value: "alice@example.com" } +→ browser_verify_value { target: "e3", value: "alice@example.com" } ✓ Value matches: "alice@example.com" ``` @@ -80,13 +80,13 @@ Generate a Playwright locator for an element, useful when converting exploratory | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference | +| `target` | string | yes | Exact target element reference from the page snapshot | ```txt -→ browser_generate_locator { ref: "e15" } +→ browser_generate_locator { target: "e15" } page.getByRole('button', { name: 'Submit' }) -→ browser_generate_locator { ref: "e3" } +→ browser_generate_locator { target: "e3" } page.getByLabel('Email') ``` @@ -94,14 +94,14 @@ Generate a Playwright locator for an element, useful when converting exploratory ```txt → browser_navigate { url: "https://demo.playwright.dev/todomvc" } -→ browser_type { ref: "e5", text: "Buy groceries", submit: true } +→ browser_type { target: "e5", text: "Buy groceries", submit: true } // Generated: await page.getByPlaceholder('What needs to be done?').fill('Buy groceries'); // Generated: await page.getByPlaceholder('What needs to be done?').press('Enter'); → browser_verify_text_visible { text: "Buy groceries" } // Generated: await expect(page.getByText('Buy groceries')).toBeVisible(); -→ browser_click { ref: "e10" } +→ browser_click { target: "e10" } // Generated: await page.getByRole('checkbox', { name: 'Toggle Todo' }).click(); → browser_verify_text_visible { text: "0 items left" } @@ -125,19 +125,19 @@ test('add and complete todo', async ({ page }) => { ```txt → browser_navigate { url: "https://app.example.com/register" } -→ browser_click { ref: "e9" } // Submit empty form +→ browser_click { target: "e9" } // Submit empty form → browser_verify_text_visible { text: "Email is required" } ✓ Text visible -→ browser_type { ref: "e3", text: "not-an-email" } -→ browser_click { ref: "e9" } +→ browser_type { target: "e3", text: "not-an-email" } +→ browser_click { target: "e9" } → browser_verify_text_visible { text: "Please enter a valid email" } ✓ Text visible -→ browser_type { ref: "e3", text: "alice@example.com" } -→ browser_type { ref: "e5", text: "password123" } -→ browser_type { ref: "e7", text: "password456" } -→ browser_click { ref: "e9" } +→ browser_type { target: "e3", text: "alice@example.com" } +→ browser_type { target: "e5", text: "password123" } +→ browser_type { target: "e7", text: "password456" } +→ browser_click { target: "e9" } → browser_verify_text_visible { text: "Passwords do not match" } ✓ Text visible ``` diff --git a/mcp/tools/code-execution.mdx b/mcp/tools/code-execution.mdx index abc400a3d2..cc5784409b 100644 --- a/mcp/tools/code-execution.mdx +++ b/mcp/tools/code-execution.mdx @@ -63,17 +63,17 @@ Evaluate JavaScript directly on the page or a specific element. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `expression` | string | yes | JavaScript to evaluate | -| `ref` | string | no | Element ref to evaluate on | +| `function` | string | yes | JavaScript to evaluate | +| `target` | string | no | Exact target element reference from the page snapshot | ```txt -→ browser_evaluate { expression: "document.title" } +→ browser_evaluate { function: "document.title" } "TodoMVC - React" -→ browser_evaluate { expression: "el => el.getAttribute('data-testid')", ref: "e15" } +→ browser_evaluate { function: "el => el.getAttribute('data-testid')", target: "e15" } "submit-button" -→ browser_evaluate { expression: "window.innerWidth + 'x' + window.innerHeight" } +→ browser_evaluate { function: "window.innerWidth + 'x' + window.innerHeight" } "1280x720" ``` diff --git a/mcp/tools/dialogs.mdx b/mcp/tools/dialogs.mdx index b72fff875b..ec432237af 100644 --- a/mcp/tools/dialogs.mdx +++ b/mcp/tools/dialogs.mdx @@ -18,7 +18,7 @@ When a dialog appears, other tools will report it in their response. Handle the ### Alert dialog ```txt -→ browser_click { ref: "e5" } +→ browser_click { target: "e5" } ⚠ Dialog appeared: [alert] "Are you sure you want to delete this?" → browser_handle_dialog { accept: true } @@ -27,7 +27,7 @@ When a dialog appears, other tools will report it in their response. Handle the ### Confirm dialog ```txt -→ browser_click { ref: "e10" } +→ browser_click { target: "e10" } ⚠ Dialog appeared: [confirm] "Are you sure you want to delete this?" → browser_handle_dialog { accept: true } // click OK @@ -37,7 +37,7 @@ When a dialog appears, other tools will report it in their response. Handle the ### Prompt dialog ```txt -→ browser_click { ref: "e8" } +→ browser_click { target: "e8" } ⚠ Dialog appeared: [prompt] "Enter your name:" → browser_handle_dialog { accept: true, promptText: "My new name" } @@ -48,7 +48,7 @@ When a dialog appears, other tools will report it in their response. Handle the When a dialog appears, other tools will report it in their response. Handle the dialog before continuing: ```txt -→ browser_click { ref: "e12" } +→ browser_click { target: "e12" } ⚠ Dialog appeared: [confirm] "Discard unsaved changes?" → browser_handle_dialog { accept: true } diff --git a/mcp/tools/file-upload.mdx b/mcp/tools/file-upload.mdx index 0263517fb5..10308d0e9e 100644 --- a/mcp/tools/file-upload.mdx +++ b/mcp/tools/file-upload.mdx @@ -13,7 +13,7 @@ Handle file chooser dialogs. When a page opens a file picker, provide file paths | `paths` | string[] | yes | Absolute file paths to upload. Omit to cancel. | ```txt -→ browser_click { ref: "e8" } // clicks "Choose file" button +→ browser_click { target: "e8" } // clicks "Choose file" button ⚠ File chooser opened → browser_file_upload { paths: ["/home/user/documents/report.pdf"] } @@ -21,7 +21,7 @@ Handle file chooser dialogs. When a page opens a file picker, provide file paths - text: "report.pdf selected" - button "Upload" [ref=e12] -→ browser_click { ref: "e12" } +→ browser_click { target: "e12" } ``` ### Multiple files diff --git a/mcp/tools/forms.mdx b/mcp/tools/forms.mdx index 1313cff70e..9bd2323918 100644 --- a/mcp/tools/forms.mdx +++ b/mcp/tools/forms.mdx @@ -10,15 +10,15 @@ Type text into an editable element (input, textarea, contenteditable). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference | +| `target` | string | yes | Exact target element reference from the page snapshot | | `text` | string | yes | Text to type | | `submit` | boolean | no | Press Enter after typing | | `slowly` | boolean | no | Type one character at a time (triggers key handlers) | ```txt -→ browser_type { ref: "e5", text: "Buy groceries" } -→ browser_type { ref: "e5", text: "Buy groceries", submit: true } // types + Enter -→ browser_type { ref: "e8", text: "search query", slowly: true } // triggers autocomplete +→ browser_type { target: "e5", text: "Buy groceries" } +→ browser_type { target: "e5", text: "Buy groceries", submit: true } // types + Enter +→ browser_type { target: "e8", text: "search query", slowly: true } // triggers autocomplete ``` ## browser_fill_form @@ -37,12 +37,12 @@ Fill multiple form fields at once. Supports textboxes, checkboxes, radio buttons → browser_fill_form { fields: [ - { ref: "e3", value: "Alice" }, - { ref: "e5", value: "Smith" }, - { ref: "e7", value: "alice@example.com" }, - { ref: "e9", value: true }, - { ref: "e11", value: "United States" }, - { ref: "e15", value: true } + { target: "e3", value: "Alice" }, + { target: "e5", value: "Smith" }, + { target: "e7", value: "alice@example.com" }, + { target: "e9", value: true }, + { target: "e11", value: "United States" }, + { target: "e15", value: true } ] } ``` @@ -55,11 +55,11 @@ Check or uncheck a checkbox or radio button. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference | +| `target` | string | yes | Exact target element reference from the page snapshot | ```txt -→ browser_check { ref: "e9" } // check the "Accept terms" checkbox -→ browser_uncheck { ref: "e9" } // uncheck it +→ browser_check { target: "e9" } // check the "Accept terms" checkbox +→ browser_uncheck { target: "e9" } // uncheck it ``` ## Workflow: completing a multi-step form @@ -73,9 +73,9 @@ You: Fill out the registration form on this page. - textbox "Password" [ref=e5] - button "Next" [ref=e7] -→ browser_type { ref: "e3", text: "alice@example.com" } -→ browser_type { ref: "e5", text: "s3cureP@ss!" } -→ browser_click { ref: "e7" } +→ browser_type { target: "e3", text: "alice@example.com" } +→ browser_type { target: "e5", text: "s3cureP@ss!" } +→ browser_click { target: "e7" } → browser_snapshot // Page 2: Profile @@ -86,10 +86,10 @@ You: Fill out the registration form on this page. → browser_fill_form { fields: [ - { ref: "e3", value: "Alice S." }, - { ref: "e5", value: "US/Pacific" }, - { ref: "e7", value: true } + { target: "e3", value: "Alice S." }, + { target: "e5", value: "US/Pacific" }, + { target: "e7", value: true } ] } -→ browser_click { ref: "e9" } +→ browser_click { target: "e9" } ``` diff --git a/mcp/tools/interaction.mdx b/mcp/tools/interaction.mdx index df8e1df37b..62015131ff 100644 --- a/mcp/tools/interaction.mdx +++ b/mcp/tools/interaction.mdx @@ -16,16 +16,16 @@ Click, hover, drag, and select elements using refs from accessibility snapshots. ## Targeting elements -Every interaction tool takes a `ref` parameter that identifies the target element. Refs come from +Every interaction tool takes a `target` parameter that identifies the element. Values come from accessibility snapshots returned by `browser_snapshot` or after navigation. Take a snapshot first, -find the element's `[ref=...]` tag, then pass that ref to the interaction tool. +find the element's `[ref=...]` tag, then pass that value as `target`. ```txt → browser_snapshot - - button "Submit" [ref=e12] ← ref is "e12" - - link "Learn more" [ref=e15] ← ref is "e15" + - button "Submit" [ref=e12] ← target is "e12" + - link "Learn more" [ref=e15] ← target is "e15" -→ browser_click { ref: "e12" } // clicks the Submit button +→ browser_click { target: "e12" } // clicks the Submit button ``` ## browser_click @@ -34,11 +34,11 @@ Click an element on the page. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference from snapshot | +| `target` | string | yes | Exact target element reference from the page snapshot | ```txt -→ browser_click { ref: "e12" } // clicks the Submit button -→ browser_click { ref: "e15" } // clicks the Learn more link +→ browser_click { target: "e12" } // clicks the Submit button +→ browser_click { target: "e15" } // clicks the Learn more link ``` ## browser_hover @@ -47,10 +47,10 @@ Hover over an element to trigger tooltips, dropdowns, or hover states. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `ref` | string | yes | Element reference from snapshot | +| `target` | string | yes | Exact target element reference from the page snapshot | ```txt -→ browser_hover { ref: "e3" } +→ browser_hover { target: "e3" } → browser_snapshot // Snapshot now shows the revealed dropdown menu - menuitem "Profile" [ref=e20] @@ -64,11 +64,11 @@ Drag one element and drop it onto another. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `startRef` | string | yes | Element to drag | -| `endRef` | string | yes | Element to drop onto | +| `startTarget` | string | yes | Element to drag | +| `endTarget` | string | yes | Element to drop onto | ```txt -→ browser_drag { startRef: "e5", endRef: "e10" } +→ browser_drag { startTarget: "e5", endTarget: "e10" } ``` ## browser_select_option @@ -77,14 +77,14 @@ Select one or more options in a `