playwriter/PLAYWRITER_AGENTS.md

this codebase has the codebase for playwriter

the extension uses chrome.debugger to manage the user browser

read ./README.md for an overview of how this extension and mcp work read playwriter/src/prompt.md to understand how the MCP works

backward compatibility

breaking changes to the WS protocol MUST never be made. publishing the extension code will never be instant, which means the extension must keep working with newer versions of the MCP and WS relay server.

architecture

• user installs the extension in chrome. we assume there is only one chrome window for now, the first opened.
• extension connects to a websocket server. on 19988. if this server is still not open, it retries connecting in a loop
• the MCP spawns the ws server if not already listening on 19988, in background. the mcp then connects to this same server with a playwright client
• the server exposes /cdp/client-id which is used by playwright clients to communicate with the extension
• the extension instead connects to /extension which is used to receive cdp commands and send responses and cdp events.
• some events are treated specially for example because
  • we need to send attachedToTarget to let playwright know which pages are available
  • we need to send detachedFromTarget when we disable the extension in a tab
  • a few more events need custom handling
• tabs are identified by sessionId or targetId (CDP concepts) or tabId (chrome debugger concept only)

mcp.ts MUST never use console.log. only console.error

write code that will run on all platforms: mac, linux, windows. especially around paths handling and command execution

development

extension/ contains the chrome extension code. you need to run pnpm build to make it ready to be loaded in chrome. the extension folder chrome will use is extension/dist

when I ask you to release extension run package.json release script

playwriter contains the ws server and MCP code. also the tests for the mcp are there. playwriter/src/prompt.md contains the docs for the MCP the agent will use. you should add there important sections that help the agent control the browser well with the MCP interface

playwriter/src/resource.md is for more generic knowledge about playwright that the agent can use when necessary, for things like best practices for selecting locators on the page

website/public/resources/ is auto-generated by playwriter/scripts/build-resources.ts during pnpm build. DO NOT edit these files manually - edit the source files in playwriter/src/ instead (e.g. debugger-examples.ts, editor-examples.ts, styles-examples.ts)

CDP docs

here are some commands you can run to fetch does about CDP various domains (events and commands namespaces)

curl -sL https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/master/pdl/domains/Target.pdl # manage “targets”: pages, iframes, workers, etc., and attach/detach sessions
curl -sL https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/master/pdl/domains/Browser.pdl # top-level browser control: version info, window management, permission settings, etc.
curl -sL https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/master/pdl/domains/Page.pdl – navigate, reload, screenshot, PDF, frame management, dialogs, and page lifecycle events.
curl -sL https://raw.githubusercontent.com/ChromeDevTools/devtools-protocol/master/pdl/domains/Emulation.pdl # emulate device metrics, viewport, timezone, locale, geolocation, media type, CPU, etc.

you can list other files in that folder on github to read more if you need to control things like DOM, performance, etc

testing

run cd playwriter && pnpm test to test the extension and mcp and CDP directly in a chrome instance automated. with the extension loaded too.

the test script will also pass -u to update some inline snapshots used

you can run singular tests with -t "testname"

each test() block should reset the extension connection to make sure tests are independent.

NEVER call browser.close() in tests or any other code that interacts with our CDP endpoint

remember that every time the extension is activated in a tab that tab gets added to the available pages. so if you toggle the extension and then do .newPage() there will be 2 pages, not 1.

to debug server or extension issues you can also inspect the file @playwriter/relay-server.log to see both extension and server logs. with all cdp events sent. to see if there are events missing or something broken. this file is recreated every time the server is started and appended in real time. use rg to only read relevant lines and parts because it can get quite long

IMPORTANT: pnpm test will take about 30 seconds so set a timeout of at least 3600ms when running the pnpm test bash command

changelogs

when you do an important change, update relevant CHANGELOG.md files for each package.

also bump package.json versions and IMPORTANT also the extension/manifest.json version too

debugging playwriter mcp issues

sometimes the user will ask you to debug an mcp issue. to do this you may want to add logs to the mcp and server. to do this you will also need to restart the server so we use the latest code. restarting the mcp yourself is not possible. instead you will need to ask the user to do it or write a test case, where the mcp can be reloaded. also making changes in the extension will not work. you will have to write a test case for that to work. you can ask the user to reconnect these too. for reloading the extension you can run the pnpm build script and do osascript -e 'tell application "Google Chrome" to open location "chrome://extensions/?id=elnnakgjclnapgflmidlpobefkdmapdm"' to make it easier for the user to reload it

if the problem was in the ws server you can restart that yourself killing process listening on 19988 and sending a new mcp call.

playwright source code

the playwright source code is cloned at ./tmp/playwright (gitignored). use Task agents to explore it when you need to understand how playwright implements CDP commands, page discovery, browser connection, etc. key files:

• packages/playwright-core/src/server/chromium/ - chromium-specific CDP implementation
• packages/playwright-core/src/server/chromium/crConnection.ts - CDP websocket connection
• packages/playwright-core/src/server/chromium/crBrowser.ts - browser and page discovery
• packages/playwright-core/src/server/chromium/chromium.ts - connectOverCDP implementation