What to do with page.evaluateAsync?

[aslushnikov]

Today, there are two methods in page's API:

• page.evaluate which evaluates code in the page and returns result.
• page.evaluateAync which too evaluates code in the page and, if the evaluation result is promise, waits for promise to resolve and returns the promise value.

The page.evaluate is straightforward, but page.evaluateAsync has cryptic name and hard to grasp. Should we remove the page.evaluateAsync and always await promise in page.evaluate?

If we want to keep them separate, is there a better name for the page.evaluateAsync?

---

Illustrating with examples, the following snippet returns "42":

var Browser = require('puppeteer').Browser();
var browser = new Browser();
browser.newPage().then(async page => {
    console.log(await page.evaluate(() => 6 * 7)); // prints '42'
    browser.close();
});

However, if we try to return a promise, we will get an empty object as a result:

var Browser = require('puppeteer').Browser();
var browser = new Browser();
browser.newPage().then(async page => {
    console.log(await page.evaluate(() => Promise.resolve(6 * 7))); // prints '{}'
    browser.close();
});

In order to get the '42' as a returned value, one would need to use page.evaluateAsync:

var Browser = require('puppeteer').Browser();
var browser = new Browser();
browser.newPage().then(async page => {
    console.log(await page.evaluateAsync(() => Promise.resolve(6 * 7))); // prints '42'
    browser.close();
});

This kind of situation could be avoided if we were to await promise in page.evaluate.

---

For the record: in case of merging evaluate with the evaluateAsync methods, we should make sure that evaluating the code from-inside the inpagecallback works successfully (which is a bit tricky since page is on a pause)

[aslushnikov]

Guys, I would appreciate your feedback on this! cc @ebidel @paulirish @dgozman

[ebidel]

FWIW, from our experience w/ Lighthouse, lots of the code we've needed to eval in the page needs to be wrapped in a promise. Basically, anything non-trivial the user will be doing. Also, most of the web platform APIs have moved towards promises, so devs are used to dealing with them. async/await only make things easier.

I like the idea of one method. Simplify + keep things async. Though, do we want to match the Phantom API as much as possible? It might be easier to transition existing users.

[aslushnikov]

Phantom's evaluateAsync is a totally different beast, (which is not needed in our case since most of puppeteer's api's return promises). This is a good argument towards removing puppeteer's evaluateAsync - to avoid confusion.

Though, do we want to match the Phantom API as much as possible?

I think we want to strike a good balance between having a familiar API while not missing the opportunity to improve. So if there are a few options to implement X and there is no clear winner, we should pick the one which is more familiar for phantom users.