All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading