# Migrate Puppeteer Scripts to Playwright

Yes. An agent ports each Puppeteer script to the Playwright library call by call, keeps the Chrome-only parts on Chromium, runs what it can and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-puppeteer-to-playwright/puppeteer/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The two libraries look alike, which is why a migration by search and replace goes wrong. The agent reads every script and sorts its calls into three groups: the same in both, renamed, and different in kind. In a repository like puppeteer/examples that means about twenty standalone scripts on `puppeteer` `^1.11.0`, with no tests. The target is the `playwright` library package, not `@playwright/test`, because these are scripts that print results and write files, not test cases. Playwright's own guide to migrating from Puppeteer supplies the renames, and the agent checks each against the type declarations of the version it installs.

Most lines carry over. `puppeteer.launch()` becomes `chromium.launch()`, and `browser.newPage()`, `page.goto()`, `page.waitForSelector()`, `page.$eval()`, `page.screenshot()` and the `request` and `response` page events keep their names. The renames are few: `browser.createIncognitoBrowserContext()` in `lazyimages_without_scroll_events.js` becomes `browser.newContext()`, and the `defaultViewport` launch option that script passes becomes a `viewport` on the context. Playwright has no `networkidle0` or `networkidle2`. Its `waitUntil` accepts `networkidle`, and the scripts use both of Puppeteer's spellings, so the agent maps each and notes that the two libraries do not define idle the same way. The eight `page.waitFor(ms)` pauses become `page.waitForTimeout(ms)`, which Playwright keeps, with a note where a condition would be better.

The third group needs thought. `side-by-side-pageload.js` loads a Nexus 5X descriptor from `puppeteer/DeviceDescriptors` and calls `page.emulate()`. Playwright exports `devices` with the same entry, but applies it when the context is created, so the script's structure changes, not just a name. Three scripts open a DevTools session with `page.target().createCDPSession()`; in Playwright that is `page.context().newCDPSession(page)` and works on Chromium only. `google_search_features.js` records a Chrome trace through `page.tracing`, which in Playwright is `browser.startTracing(page)`, also Chromium only, and `code_coverage.js` keeps `page.coverage` under the same restriction. `verify_download.js` sets download behaviour through a raw CDP command and then watches the folder with `fs.watch` until the file appears; Playwright has a `download` event with `saveAs`, so the agent replaces the workaround. `lighthouse/chromelauncher_puppeteer.js` attaches to a Chrome it did not launch, which becomes `chromium.connectOverCDP()`.

It then installs a browser with `npx playwright install chromium` and runs what can run without a third-party site, starting `server.js` so the lazy-image script can load `html/lazyload.html` from port 8080. The scripts that launch with `headless: false` to show a window, play audio or go full screen keep that option, which Playwright spells the same way, and run under a virtual display when the machine has none. For each script the agent records whether it ran before the change, whether it runs after, and what it printed. Before is often no, because the locked dependencies include an old native `sharp` that does not build on a current Node, so the agent reports that honestly and does not invent a baseline.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Port the Puppeteer scripts in this repository to the Playwright library and open a pull request. Read package.json, yarn.lock, README.md, server.js and every .js file at the top level and under cdp/ and lighthouse/ first. Use the playwright package, not @playwright/test: these are scripts, not tests, and they should stay runnable with node. Read Playwright's Migrating from Puppeteer guide and check every replacement against the installed type declarations. For each script list its Puppeteer calls in three groups: unchanged, renamed, and different in kind. Port the first two directly. For the third group, explain the Playwright way and restructure the script: device emulation, CDP sessions, tracing, coverage, downloads, attaching to an existing browser. Keep Chromium for anything that relies on CDP, coverage or tracing, and say which scripts could now also run on Firefox or WebKit. Map networkidle0 and networkidle2 to what Playwright offers and say how the meaning differs. Keep fixed delays as they are and flag the ones a locator or an event should replace. Install the browser with npx playwright install chromium. Run every script that does not need a third-party site, before and after where the old version can be installed, serving html/ with server.js; run windowed scripts under a virtual display. Port the third-party ones without rewriting their selectors and record what each does when started. Remove puppeteer and any dependency only it needed. Put one table row per script in the pull request: calls changed, ran before, ran after, output or error.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request rewrites the scripts, swaps `puppeteer` for `playwright` in `package.json` and updates the lockfile and the README's wording. The description opens with a mapping table for this repository only: each Puppeteer call the scripts made, its Playwright form, and the group it fell into. It is short, because most of Puppeteer's surface was never used here, and that is more useful to a reviewer than a general cheat sheet.

Then one row per script. For a script in the third group the row links to a few sentences on what changed in its structure: the device descriptor moving to `newContext`, the download event replacing a file watcher, the trace moving from the page to the browser. Rows for scripts that ran show their output. Rows for scripts aimed at a live third-party page show what happened when they were started and say plainly when the failure is a selector that no longer matches, which no library change can fix.

A reviewer reads the Chromium-only list first. Anyone hoping the migration makes every script cross-browser will find that the ones built on CDP, coverage and tracing stay on Chromium by nature. They then run the scripts they depend on and compare results with the Puppeteer versions, paying attention to anything that waited for network idle, since timing is where the two libraries differ most. The fixed delays the agent flagged are a good first follow-up.

## Run it on every repository of Puppeteer scripts

This is a one-time job per repository, and teams often have several: a scraper, a PDF renderer, a folder of monitoring scripts. Send one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run sorts its own calls, so a PDF service that uses three Puppeteer methods gets a small diff and a crawler gets a large one. Runs past the key's `max_concurrent` are accepted as `queued` and start as earlier ones finish.

Because the sandbox parks with its disk when a turn ends, the first pull request does not have to be the last word. Read the per-script table, then send a follow-up with `POST …/sessions/{id}/messages` naming the scripts that matter most and asking for their fixed delays to become locators and events. The follow-up wakes the same machine with the browser already installed, so the second pass spends its time on the scripts and not on setup.

## Why run it on Rush?

Browser scripts are only as good as their last successful run, and these have no tests to stand in for one. In a Rush sandbox the agent installs Chromium, serves the local pages, starts a display for the windowed scripts and runs each one after porting it. The transcript holds every command and every script's output, so when the table says a script printed its coverage summary or wrote its PDF, the lines that show it are in the run's record next to the pull request.

The alternative is an afternoon of running some twenty scripts by hand, twice, and remembering which ones failed for reasons that have nothing to do with the migration. The agent keeps that ledger as it goes. It also separates three causes a person tends to blur: a call that changed, a dependency that no longer installs, and a website that moved on.

## Frequently asked questions

### Do I need @playwright/test, or just playwright?

For scripts, just `playwright`. It gives you `chromium`, `firefox` and `webkit` launchers and the same page API, and the scripts stay plain Node programs. `@playwright/test` adds a test runner, fixtures and assertions, which is the right choice when the scripts are really end-to-end tests.

### What replaces networkidle0 and networkidle2?

Playwright has a single `networkidle` value for `waitUntil` and for `page.waitForLoadState`. It is not an exact equivalent of either Puppeteer setting, so a script that leaned on the difference may wait a little longer or shorter. The agent maps both to `networkidle` and flags the scripts where waiting for a specific element or response would be more reliable.

### Can I still use the Chrome DevTools Protocol?

Yes, on Chromium. `page.context().newCDPSession(page)` returns a session with `send` and events, so raw commands port with little change. Scripts that depend on it cannot move to Firefox or WebKit, and the pull request lists them.

### Will the scripts run faster or more reliably afterwards?

The port alone does not promise either. It keeps each script's behaviour, including its fixed delays. The reliability gains people associate with Playwright come from locators and auto-waiting, which means rewriting how a script finds and waits for elements; the agent flags where that would help and leaves it for a follow-up.

## More Puppeteer jobs

- [Upgrade Puppeteer 1.x Scripts to the Current Release](https://getrush.ai/run/upgrade-puppeteer/puppeteer/)
- [Fix page.waitForTimeout Is Not a Function After a Puppeteer Upgrade](https://getrush.ai/run/fix-page-waitfortimeout-is-not-a-function/puppeteer/)

## More jobs like this: Hand off a long task

- [Migrate a SolidJS App from Rollup to Vite](https://getrush.ai/run/migrate-rollup-to-vite/solidjs/)
- [Migrate a Python Project from setup.py to pyproject.toml](https://getrush.ai/run/migrate-setup-py-to-pyproject/python/)
- [Move a Slack Bolt App From Socket Mode to HTTP](https://getrush.ai/run/migrate-socket-mode-to-http/slack-bolt/)
- [Migrate an Echo and GORM API From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/echo/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
