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
/**
* Copyright (c) Microsoft Corporation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { spawn } from 'child_process';
import * as z from 'zod';
import { libPath } from '../../package';
import { defineTabTool, defineTool } from './tool';
import { elementSchema, optionalElementSchema } from './snapshot';
import type { AnnotateResult } from '../dashboard/dashboardController';
const resume = defineTool({
capability: 'devtools',
schema: {
name: 'browser_resume',
title: 'Resume paused script execution',
description: 'Resume script execution after it was paused. When called with step set to true, execution will pause again before the next action.',
inputSchema: z.object({
step: z.boolean().optional().describe('When true, execution will pause again before the next action, allowing step-by-step debugging.'),
location: z.string().optional().describe('Pause execution at a specific <file>:<line>, e.g. "example.spec.ts:42".'),
}),
type: 'action',
},
handle: async (context, params, response) => {
const browserContext = await context.ensureBrowserContext();
const pausedPromise = new Promise<void>(resolve => {
const listener = () => {
if (browserContext.debugger.pausedDetails()) {
browserContext.debugger.off('pausedstatechanged', listener);
resolve();
}
};
browserContext.debugger.on('pausedstatechanged', listener);
browserContext.once('close', () => {
browserContext.debugger.off('pausedstatechanged', listener);
resolve();
});
});
if (params.location) {
// Split at the last colon, but not at the drive letter of a Windows path like "C:\tests\example.spec.ts".
const separator = params.location.lastIndexOf(':');
const [file, lineStr] = separator > 1 ? [params.location.slice(0, separator), params.location.slice(separator + 1)] : [params.location, ''];
let location;
if (lineStr) {
const line = Number(lineStr);
if (isNaN(line))
throw new Error(`Invalid location "${params.location}", expected format is <file>:<line>, e.g. "example.spec.ts:42"`);
location = { file, line };
} else {
location = { file: params.location };
}
await browserContext.debugger.runTo(location);
} else if (params.step) {
await browserContext.debugger.next();
} else {
await browserContext.debugger.resume();
}
await pausedPromise;
},
});
const highlight = defineTabTool({
capability: 'devtools',
schema: {
name: 'browser_highlight',
title: 'Highlight element',
description: 'Show a persistent highlight overlay around the element on the page.',
inputSchema: elementSchema.extend({
style: z.string().optional().describe('Additional inline CSS applied to the highlight overlay, e.g. "outline: 2px dashed red".'),
}),
type: 'readOnly',
},
handle: async (tab, params, response) => {
const { locator } = await tab.targetLocator(params);
await locator.highlight({ style: params.style });
response.addTextResult(`Highlighted ${locator}`);
},
});
const hideHighlight = defineTabTool({
capability: 'devtools',
schema: {
name: 'browser_hide_highlight',
title: 'Hide element highlight',
description: 'Remove a highlight overlay previously added for the element.',
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) => {
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`);
}
},
});
const annotate = defineTabTool({
capability: 'devtools',
schema: {
name: 'browser_annotate',
title: 'Annotate the current page',
description: 'Open the Playwright Dashboard in annotation mode for the current page and wait for the user to draw annotations. Returns the annotated screenshot, ARIA snapshot, and the list of annotations.',
inputSchema: z.object({}),
type: 'readOnly',
},
handle: async (tab, params, response, signal) => {
// eslint-disable-next-line no-restricted-syntax -- _guid is the cross-process page identifier shared with the dashboard daemon.
const pageId = (tab.page as any)._guid as string;
const daemonScript = libPath('entry', 'dashboardApp.js');
const daemonArgs = [daemonScript, `--pageId=${pageId}`];
// Spawn the dashboard daemon (idempotent — the singleton socket guards against duplicates).
const daemon = spawn(process.execPath, daemonArgs, { detached: true, stdio: 'ignore', windowsHide: true });
daemon.unref();
// Spawn the annotate client in JSON mode to capture the raw payload over stdout.
const client = spawn(process.execPath, [...daemonArgs, '--annotate'], {
stdio: ['pipe', 'pipe', 'inherit'],
});
const onAbort = () => client.kill();
signal?.addEventListener('abort', onAbort);
const stdoutChunks: Buffer[] = [];
client.stdout!.on('data', chunk => stdoutChunks.push(chunk));
const exitCode = await new Promise<number | null>(resolve => client.on('exit', code => resolve(code)));
signal?.removeEventListener('abort', onAbort);
if (signal?.aborted) {
response.addTextResult('Annotation cancelled.');
return;
}
if (exitCode !== 0) {
response.addError(`Annotation client exited with code ${exitCode}`);
return;
}
const text = Buffer.concat(stdoutChunks).toString('utf8').trim();
if (!text) {
response.addTextResult('No annotations were submitted.');
return;
}
const result = JSON.parse(text) as AnnotateResult;
if (result.type !== 'submitted' || result.frames.length === 0) {
response.addTextResult('No annotations were submitted.');
return;
}
const { frames, feedback } = result;
const date = new Date();
if (feedback)
response.addTextResult(feedback);
const multi = frames.length > 1;
for (let i = 0; i < frames.length; i++) {
const frame = frames[i];
const idx = i + 1;
const session = frame.sessionTitle || 'session';
const tab = frame.title || 'tab';
response.addTextResult(`${multi ? `## Screenshot ${idx}\n` : ''}${session} / ${tab} @ ${frame.url} (${frame.viewportWidth}x${frame.viewportHeight})`);
for (const a of frame.annotations)
response.addTextResult(` { x: ${a.x}, y: ${a.y}, width: ${a.width}, height: ${a.height} }: ${a.text}`);
if (frame.data)
await response.addResult(`Annotation image${multi ? ' ' + idx : ''}`, Buffer.from(frame.data, 'base64'), { prefix: `annotations${multi ? '-' + idx : ''}`, ext: 'png', date });
if (frame.ariaSnapshot)
await response.addResult(`Annotation snapshot${multi ? ' ' + idx : ''}`, Buffer.from(frame.ariaSnapshot, 'utf8'), { prefix: `annotations${multi ? '-' + idx : ''}`, ext: 'yaml', date });
}
},
});
export default [resume, highlight, hideHighlight, annotate];