Proposal: deprecate `waitFor` and add `waitForTimeout`

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.

[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.

[chrara]

If your a dummy like me then here’s what you need to do:

Replace: await page.waitFor(1000); With: await page.waitForTimeout(1000);