browser_evaluate
Execute JavaScript expressions on web pages or specific elements using structured accessibility snapshots for precise interactions through Playwright MCP server.
Instructions
Evaluate JavaScript expression on page or element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| element | No | Human-readable element description used to obtain permission to interact with the element | |
| function | Yes | () => { /* code */ } or (element) => { /* code */ } when element is provided | |
| ref | No | Exact target element reference from the page snapshot |
Implementation Reference
- src/tools/evaluate.ts:41-57 (handler)The handler function that performs the JavaScript evaluation on the browser page or element. It handles locators if provided, adds replay code to the response, waits for completion, and adds the result.handle: async (tab, params, response) => { response.setIncludeSnapshot(); let locator: playwright.Locator | undefined; if (params.ref && params.element) { locator = await tab.refLocator({ ref: params.ref, element: params.element }); response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`); } else { response.addCode(`await page.evaluate(${javascript.quote(params.function)});`); } await tab.waitForCompletion(async () => { const receiver = locator ?? tab.page as any; const result = await receiver._evaluateFunction(params.function); response.addResult(JSON.stringify(result, null, 2) || 'undefined'); }); },
- src/tools/evaluate.ts:25-39 (schema)Zod schema for input validation (function, optional element, ref) and the tool schema definition including name 'browser_evaluate'.const evaluateSchema = z.object({ 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'), }); const evaluate = defineTabTool({ capability: 'core', schema: { name: 'browser_evaluate', title: 'Evaluate JavaScript', description: 'Evaluate JavaScript expression on page or element', inputSchema: evaluateSchema, type: 'destructive', },
- src/tools/evaluate.ts:60-62 (registration)Exports the defined tool for import and collection in src/tools.tsexport default [ evaluate, ];
- src/tools.ts:36-52 (registration)Collects and exports all tools, spreading the evaluate tool (browser_evaluate) into the allTools array used by the browser server backend.export const allTools: Tool<any>[] = [ ...common, ...console, ...dialogs, ...evaluate, ...files, ...install, ...keyboard, ...navigate, ...network, ...mouse, ...pdf, ...screenshot, ...snapshot, ...tabs, ...wait, ];