Proposal: deprecate waitFor and add waitForTimeout

[jackfranklin]

Puppeteer's API currently has a few waitForX functions:

• waitForSelector
• waitForFunction
• waitForXPath

(And others that are less relevant to this proposal).

We also ship waitFor, which has the following docs:

This method behaves differently with respect to the type of the first parameter:

* if selectorOrFunctionOrTimeout is a string, then the first argument is treated as a selector or xpath, depending on whether or not it starts with '//', and the method is a shortcut for page.waitForSelector or page.waitForXPath
* if selectorOrFunctionOrTimeout is a function, then the first argument is treated as a predicate to wait for and the method is a shortcut for page.waitForFunction().
* if selectorOrFunctionOrTimeout is a number, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
* otherwise, an exception is thrown

So if you call waitFor(someFunc), you're just calling waitForFunction. Similarly, waitFor('.foo') calls waitForSelector, and waitFor('//div') calls waitForXPath. The only unique behaviour waitFor provides is calling it with a time: waitFor(1000) does exactly what you expect.

Another downside of this method is that it's harder to type safely with TypeScript (you can do it via overloads, but it's uneccessarily complex, especially when all the standalone waitForX functions are already typed).

I think it's confusing that most of the API for waiting is explicitly named, e.g. waitForSelector, yet the only way to wait for a timeout is to call waitFor.

I'd propose a nicer, more consistent API would:

1. Add waitForTimeout. This is consistent with the naming of the other wait for methods, which are all named waitForX.
2. Remove waitFor.

Rather than do this as one breaking change we can do this change in two parts:

1. Ship a version with waitForTimeout. Deprecate waitFor and log a message when it's used, but maintain its current behaviour.
2. After a reasonable amount of time, ship a release that removes waitFor. The migration path should be straightforward, users will have to swap waitFor for the correct waitForX method. We'll have a waitForX for every behaviour of the original waitFor, so this won't be more than a renaming of some method calls.

[jackfranklin]

@mathiasbynens @hanselfmu @OrKoN PTAL

[mathiasbynens]

LGTM. Explicit, dedicated APIs > generic overloaded APIs (even if you don't consider TypeScript).

[OrKoN]

LGTM

[supnate]

Please don't remove waitFor. We have a CI running tests from more than 40 repos from different teams in one job. If it's removed, all teams need to commit the update at the same time to make build success. It's a hard thing to do.

[jackfranklin]

@supnate waitFor isn't removed yet but we do plan to remove it in a future release. That said, it's not going to happen imminently so your teams have plenty of time. I'd suggest trying to migrate slowly to prepare yourself for when waitFor is removed, but rest assured you have time on your side 👍

[supnate]

Thanks @jackfranklin for the suggestion. But you know people don't care warnings much. We can ask teams in different countries to do it but there will be no mechanism to ensure all code are updated before it's finally removed unless we write some script to check it. We've been using puppeteer very smoothly from 1.x to 5.x and we wish it could continue. like you can add a new API but just remove waitFor from docs but it never really deprecate.

[supnate]

BTW, would you please update the issue title using waitForTimeout instead of waitForTimer since the warning points to this issue?

[delesseps]

Does someone know what the future of the TypeScript Types are? with waitFor being deprecated I don't see anyone looking to add waitForTimeout

currently if anyone is using TypeScript they can add the following to extend the definitions

import * as puppeteer from 'puppeteer';

declare module 'puppeteer' {
  export interface Page {
    waitForTimeout(duration: number): Promise<void>;
  }
}

[fgroupindonesia]

and what about the usage of waitForX is that still same as waitFor original parameter?
and... is it reasonable for hiding the notification at the moment? :D

[Colton1070]

Yeah, I was confused being told it's deprecated but also the only way currently to wait for a specific amount of time is to use waitFor(1000). Hope either an alternate function is created or waitFor() becomes the time exclusive version.

[dobesv]

You can also wait for a specific time outside the Page, e.g.

await Bluebird.delay(100)

[framerate]

Take a look at #3347

// this test fails with a time out
await page.waitForSelector(buttonSelector) 
await page.click(buttonSelector)

// this one passes
await page.waitForSelector(buttonSelector)
await page.waitFor(1000)
await page.click(buttonSelector)

// so does this one
await page.waitForSelector(buttonSelector)
page.$eval(buttonSelector, elem => elem.click())

So if you remove waitFor without fixing waitForSelector() or .click() a lot of people's tests may break

EDIT: wrong copy/paste

[zeevgg]

hey, started getting warnings about deprecation.
so what is the new way to use it?

[framerate]

what is the new way to use it?

Looks like its waitForTimeout() now

[adrianarandac]

TypeError: runner.waitForTimeout(_html selector_) is not a function
I'm trying to replace a waitFor and got this message. Is it shipped?

[OrKoN]

If you want to wait for a number of milliseconds to pass, use page.waitForTimeout(1000). If you want to wait for a selector, use page.waitForSelector(".selector").

Please see the documentation for these methods: https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitfortimeoutmilliseconds and make sure you use a version that ships waitForTimeout.

[San-Zer0-786]

TypeError: page.waitForTimeout is not a function

TypeError: page.waitFor is not a

This is on latest 22.3.0

How annoying. What harm is there in keeping older function names, to prevent projects from being nuked on updates?

[civilizator]

Same thing, although it worked fine for two years TypeError: page.waitForTimeout is not a function puppeteer 22.4.0

Updated to version 22.4.1 and problem still persists.

Downgrade to 20.3.0 and works great for me.

[antonok-edm]

In case anyone else finds this issue wondering why neither waitFor nor waitForTimeout exist - see #11780.