All jobs

Fix page.waitForTimeout Is Not a Function After a Puppeteer Upgrade

Yes. An agent upgrades puppeteer, reproduces the TypeError, replaces the removed wait with a setTimeout promise, checks the Chrome download 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 agent clones the repository into its own cloud sandbox and reads the script first. In a small screenshot tool like inbn/screenshot-urls, index.js parses --url, --input, --dest, --width, --height, --format, --wait and --selector with commander, launches puppeteer.launch(), and for each URL calls page.setViewport, page.goto, then if (waitTime) { await page.waitForTimeout(waitTime); } at line 85 before page.screenshot with captureBeyondViewport: false or a clip from the selector's bounding box. package.json pins puppeteer at ^18.0.5, the lock file resolves 18.0.5 with its Chromium under node_modules/puppeteer/.local-chromium, the README documents node index.js --url=... --width=1600 --height=900 and --input=pages.txt, and there is no test script.

Then it reproduces both states. With the locked 18.0.5, node index.js -u https://example.com -t 500 -d out.jpg writes a JPEG. After npm install puppeteer@22.0.0 the same command throws TypeError: page.waitForTimeout is not a function at index.js:85:18, and the same command without -t still succeeds, because the branch is never taken. The method is present on 21.11.0 and gone on 22.0.0, and on the current release Page.prototype.waitForTimeout is undefined while waitForSelector and waitForNetworkIdle remain. So any user who passes --wait gets the crash and everyone else sees nothing.

The fix is one line: await new Promise((resolve) => setTimeout(resolve, waitTime));, which is what the removed helper did. With it, the -t 500 command writes the same screenshot on puppeteer 22, and the captureBeyondViewport and clip options still work as before. The agent also notes what the upgrade changed around the script: from puppeteer 19 the browser is downloaded at install time into ~/.cache/puppeteer instead of node_modules, so a CI job or Docker image that only copies node_modules has no Chrome and fails with Could not find Chrome at launch; the pull request names npx puppeteer browsers install chrome as the step to add there.

One thing the agent reads but leaves alone: the --input branch fills urls inside an fs.readFile callback and then launches the browser without waiting for it, so a bulk run can start with an empty list. That is a separate bug, present on 18 and 22 alike, and the pull request reports it with the line rather than mixing it into the upgrade.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "This Node.js script fails with \"TypeError: page.waitForTimeout is not a function\" after upgrading puppeteer. Read package.json, the lock file and every file that uses the puppeteer API first. Install the locked puppeteer version and run the script once to show it works, then install the current puppeteer release, run the same command and quote the error with its line. Replace each page.waitForTimeout call with an awaited setTimeout promise of the same duration, keep every other option as it is, and run the script again to show the output file is written. Check where the new release downloads its browser and say what a CI job or container image must do to have it. Report any unrelated bug you notice with its line, but do not fix it. Open a pull request that quotes the failing and passing runs.",
  "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

What comes back is a pull request touching index.js, package.json and package-lock.json: the wait rewritten as a promise around setTimeout, the puppeteer range moved to the current major, nothing else in the loop changed. The description quotes the TypeError with its line from the upgraded run, the successful run with --wait after the fix, and the browser cache path the new release uses, with the install command for CI.

A reviewer checks that the delay is still in milliseconds and still only runs when --wait was passed, that the screenshot options were not touched, and that the deploy path installs Chrome where the new puppeteer looks. The run's record has both commands with their full output and the written file as the run's artifact, so the before and after can be opened rather than taken on trust.

Run it on every Monday morning

Add an automation to the Project with this prompt and a schedule trigger, cron set to 0 9 * * 1 in your timezone. Each Monday one run bumps puppeteer, exercises the script and opens one pull request on its own branch; a week where the script cannot be made to run ends needs_review with the error attached, and a week already on the current release opens nothing.

The same body works from your own code with POST /o/{org}/sessions and an API key when a dependency bot's puppeteer bump turns red; the key's webhook_url receives run.completed or run.failed with the session URL and the pull request when the run ends.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

This failure hides behind an option. The script works for everyone who does not pass --wait, so a laptop test of the upgrade passes and the crash shows up for the one user who needs the delay. The agent runs the script both ways in its sandbox, at the locked version and the new one, and every command and its output stays in the run's record, so the pull request shows the exact call that broke and the exact run that proved the fix.

A browser automation upgrade also touches the machine, not just the code: the download location moved, and a container built the old way has no Chrome. In a Rush sandbox the agent sees that first-hand, because it has to install the browser where the new release expects it, and it writes that step into the pull request instead of leaving it for the first failed deploy.

Frequently asked questions

Why was waitForTimeout removed?

It was deprecated as a fixed sleep that makes scripts slow and flaky, and puppeteer 22 dropped it in favour of waiting for a condition: waitForSelector, waitForNetworkIdle or waitForFunction. For a screenshot tool whose user asks for a literal delay, a promise around setTimeout is the honest replacement, and the pull request says so.

Should the script wait for a selector instead of a timeout?

When --selector is given, the agent could wait for it with waitForSelector before clipping, and the pull request suggests it. It does not change the --wait semantics in the same change, because users pass a number of milliseconds and expect exactly that.

Where does Chrome come from now?

Puppeteer 18 shipped a Chromium build inside node_modules/puppeteer/.local-chromium. From 19 the install step downloads Chrome into ~/.cache/puppeteer, keyed by the version the release pins. A CI job or image that caches only node_modules must run npx puppeteer browsers install chrome, and the pull request includes that line.

Will it fix the --input race it found?

Only if you ask. The fs.readFile callback that fills the URL list runs after the browser launches, so bulk runs can start empty; that is true before and after the upgrade. The prompt tells the agent to report it with the line and leave it for a separate change.

More Puppeteer jobs

More jobs like this: Upgrade dependencies weekly

Keep reading