Choose Playwright when you need multi-browser support (Chromium, Firefox, WebKit), built-in test runner features (parallelism, retries, reporters), network interception, or mobile emulation out of the box.
Choose Puppeteer when you want a minimal dependency footprint, are already deeply invested in a Puppeteer-specific API, or need Chrome DevTools Protocol features that Playwright does not yet expose.
When migrating, replace `puppeteer.launch` with `chromium.launch` (or use the `test` fixture), and replace `page.waitForSelector` + `page.$` calls with Playwright locators (`page.locator`, `page.getByRole`, etc.).
Replace Puppeteer's `page.waitForNavigation` paired with a click by Playwright's `Promise.all([page.waitForURL('**target**'), page.click('...')])` pattern, or simply rely on Playwright's auto-waiting.
Replace Puppeteer's `page.on('request', ...)` / `page.setRequestInterception(true)` pattern with Playwright's `page.route(pattern, handler)` for cleaner mock/intercept code.
Known gotchas
Playwright's auto-waiting means many explicit `waitFor*` calls from Puppeteer are redundant — but removing them all at once can hide real timing dependencies. Migrate incrementally and run tests after each change.
Puppeteer and Playwright have different coordinate systems for `mouse.move` and `touchscreen` APIs. Automated drag-and-drop scripts often need to be rewritten, not just translated.
Playwright's `ElementHandle` API exists for compatibility but is discouraged; the idiomatic approach is locators. If you port Puppeteer code that heavily uses `ElementHandle`, plan a second pass to convert to locators — mixing both styles leads to maintenance confusion.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp