# Upgrade Puppeteer 1.x Scripts to the Current Release

Yes. An agent finds every removed Puppeteer call in your scripts, replaces each with its current form, runs the scripts it can and opens a PR that lists the rest.

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

## What the agent does

Old Puppeteer scripts fail one line at a time, so the agent maps the damage before it upgrades. In a repository like puppeteer/examples, `package.json` asks for `puppeteer` `^1.11.0`, `yarn.lock` holds it at 1.11.0 and `engines` still says Node 8 or later. There are about twenty standalone scripts and no test suite or `scripts` block, so nothing can be run to find out what broke. The agent searches the scripts for every Puppeteer call and checks each one against the type declarations that ship with the release it is installing, which also tells it the new minimum: the current Puppeteer needs Node 22.12 or later.

Four kinds of call no longer exist or have moved. `page.waitFor(ms)` is gone, and so is its later replacement `page.waitForTimeout`; it is called eight times across `fullscreen.js`, `google_search_features.js`, `lazyimages_without_scroll_events.js` and `screenshot_element_on_tab.js`, and each becomes a plain promise around `setTimeout`. `browser.createIncognitoBrowserContext()`, used twice in the lazy-image script, is now `browser.createBrowserContext()`. `side-by-side-pageload.js` loads `puppeteer/DeviceDescriptors`, a module path that no longer resolves; the Nexus 5X entry it wants is in the `KnownDevices` export. And `page.target().createCDPSession()`, in three scripts, still runs but `page.target()` is deprecated in favour of `page.createCDPSession()`, so the agent moves those too.

Launch behaviour changed as well. `headless: true` now starts Chrome's new headless mode, and the old one is `headless: 'shell'`. For `code_coverage.js` and `lighthouse/throttling.js`, which pass `true`, the agent keeps the new mode and says so. Several scripts pass `headless: false` because they show a window, play sound or go full screen; the agent runs those under a virtual display when the machine has none and reports the ones whose result only a person can judge. Puppeteer downloads a matching Chrome when it installs. If that download is not available where the run happens, the agent points `executablePath` at a browser that is, and says which browser and version the scripts ran against.

The install has its own obstacle, unrelated to Puppeteer. `crawlsite.js` depends on `sharp` `^0.21.1`, a native module from the same era, and on Node 22 its build fails, which stops `npm install` for the whole repository. The agent upgrades `sharp` just far enough to install and checks the one call that uses it, a resize to a fixed height. Then it runs what can be run without someone else's website. `server.js` serves the repository on port 8080, so the lazy-image script can be pointed at `html/lazyload.html`, and `code_coverage.js` and `view-source.js` take any URL. Scripts aimed at a tweet, a video or a search doodle are ported and started once, with whatever they print recorded. `hash_navigation.js` expects `html/spa.html` on port 5000, a file the repository does not contain, so it is reported as not runnable.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade Puppeteer in this repository of scripts from the locked 1.x release to the current one 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. List every Puppeteer API each script calls. Install the current puppeteer and check each call against the type declarations in node_modules, not from memory: report which calls were removed, which were renamed and which are deprecated, with file and line. Replace each removed or renamed call with its current equivalent and move deprecated ones. Say what headless: true means in the new release and whether any script should use the old mode. Set engines.node to what the new release requires. If installing the repository's other dependencies fails on the sandbox's Node, upgrade only the package that fails, only as far as needed, and check the code that uses it. If Puppeteer cannot download its browser, use an installed one through executablePath and name it. Run every script that does not depend on a third-party site, serving html/ with server.js where a script needs a page; run scripts that open a window under a virtual display. For scripts that target third-party sites, port them, start each once and record what happened without changing their selectors. Do not upgrade lighthouse, chrome-launcher or request in this pull request; list what in those scripts stands out as stale. Put a table in the pull request with one row per script: calls changed, whether it ran, and the 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 changes `package.json`, the lockfile and the scripts that called something removed. Its description starts with the API table: each removed, renamed or deprecated call, the files and lines where it appeared, and what replaced it, with the declaration it was checked against. A second table has one row per script with three columns: what changed in it, whether it ran in the sandbox, and the first lines of its output or its error.

That second table is honest about its gaps. Scripts that ran against the local `html/` pages or a neutral URL show output. Scripts that depend on a third-party page show whatever happened when they were started, which for a selector written years ago against someone else's markup is often a timeout, and the description says that such a failure is about the page and not about the upgrade. The `sharp` bump and the one line it affects are listed separately, with the install error that forced it.

A reviewer picks two or three scripts they actually use and runs them, since a table row that says a script ran is not the same as its result being right. They check the new `engines.node` against wherever these scripts are scheduled, because a cron host on an older Node will fail at install. And they read the list of what was left alone: the Lighthouse scripts still depend on an alpha release from the same period, and `request` is deprecated, so a follow-up is likely.

## Run it on every Monday morning

Puppeteer releases track Chrome, so new versions arrive often. An automation in the Project that holds the repository, with a `schedule` trigger whose `cron` is `0 8 * * 1` and a `timezone`, starts one run each Monday with a shorter prompt: compare the locked Puppeteer with the newest release, read the release notes in between for removed or deprecated calls, upgrade, rerun the scripts that can run, and open a pull request with the table, or end with one line when the lock is current.

The weekly run is where staying current pays off. A jump across many majors, like the one on this page, changes four kinds of call at once; a weekly bump usually changes none, and a deprecation notice normally arrives before the removal it announces. If the upgrade breaks a script the agent cannot repair, the run ends `needs_review` with the error quoted, and the next Monday's run starts fresh.

## Why run it on Rush?

These scripts have no tests, so the only way to know one works is to launch a browser and run it. In a Rush sandbox the agent has a machine where it can install Chrome's dependencies, start a virtual display for the scripts that open a window, serve the local pages and run each script in turn. Every command, every script's output and every stack trace is kept in the run's record, so the per-script table in the pull request can be checked against what actually happened.

It also removes the guesswork about what changed. An upgrade done from memory of a changelog misses calls, because the list of removals across this many majors is long and most of it does not apply. Checking each call the scripts really make against the installed declarations gives a short, exact list, and a second repository of old scripts gets the same request with its own URL in `resources`.

## Frequently asked questions

### What replaces page.waitFor and page.waitForTimeout?

Neither exists in the current Puppeteer. For a fixed delay, await a promise that resolves from `setTimeout`. Where the delay was standing in for a condition, `page.waitForSelector` or `page.waitForFunction` is the better replacement, and the agent says which it chose at each call site and why.

### Why does my script behave differently in headless mode after upgrading?

Because `headless: true` now means Chrome's new headless mode, which is the full browser without a window. The previous implementation is still available as `headless: 'shell'`. If a script depended on old headless behaviour, switching that one option restores it, and the pull request notes any script where the agent did so.

### Will it fix selectors that no longer match the live site?

Not in this request. A selector that fails because a third-party page changed is a different job from an API upgrade, and mixing them hides which change fixed what. The table shows which scripts failed that way, and a follow-up to the same session can take them one at a time.

### Does it switch from yarn to npm?

No. The repository has a `yarn.lock`, so the agent keeps Yarn and updates that lockfile. It changes the package manager only if you ask, since the lockfile format is part of what your other environments install from.

## More Puppeteer jobs

- [Fix page.waitForTimeout Is Not a Function After a Puppeteer Upgrade](https://getrush.ai/run/fix-page-waitfortimeout-is-not-a-function/puppeteer/)
- [Migrate Puppeteer Scripts to Playwright](https://getrush.ai/run/migrate-puppeteer-to-playwright/puppeteer/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade PyJWT From 1.x to 2.x in a Flask API](https://getrush.ai/run/upgrade-pyjwt/pyjwt/)
- [Upgrade Python Dependencies Weekly for a Dagster Project](https://getrush.ai/run/upgrade-python-dependencies/dagster/)
- [Upgrade Python Dependencies Weekly for a LangGraph Agent](https://getrush.ai/run/upgrade-python-dependencies/langgraph/)
- [Upgrade Python Dependencies Weekly for a Litestar App](https://getrush.ai/run/upgrade-python-dependencies/litestar/)

## 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/)
