feat: webContents.loadURL returns a promise

[nornagon]

Description of Change

Many tests use the following pattern to load a page in a WebContents and wait for the load to finish:

async () => {
  webContents.loadFile('path/to/page.html')
  await emittedOnce(webContents, 'did-finish-load')
  // ... do something with the page
}

This is an aesthetic improvement over the callback method of webContents.on('did-finish-load', ...), but is unfortunately flaky: it is sometimes possible that the 'did-finish-load' event is emitted before the listener is registered (see #15853 for example, which fixes the flaky test described in #15095). This is to do with the fact that the tests use the BrowserWindow module via the remote API, so there is a short window of time after loading the URL but before the event listener is registered. If the event is fired during that window, it will be lost, and the test times out.

It's possible to eliminate the additional emittedOnce helper call, clean up the code, and remove the possibility of flakiness by having loadURL return a promise. The above could would be written as follows with this patch:

async () => {
  await webContents.loadFile('path/to/page.html')
  // ... do something with the page
}

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation is changed or added
• PR title follows semantic commit guidelines

Release Notes

Notes: webContents.loadURL and loadFile now return a promise

[deepak1556]

We could instead use content::ChildProcessSecurityPolicy::CanRequestURL to determine if a navigation will happen and abort with did-fail-load on our end for these types of cases.

[nornagon]

I figured this would be a reasonable "catch-all", since I think did-stop-loading will be emitted regardless of what happens?

[nornagon]

but CanRequestURL might be a good extra check to give a more informative error

[deepak1556]

since I think did-stop-loading will be emitted regardless of what happens?

yup that is correct, its emitted whenever a document stops its resource loading be it failure or success. Having this check can simplify existing url validity check https://github.com/electron/electron/blob/master/atom/browser/api/atom_api_web_contents.cc#L1157

[MarshallOfSound]

Looks good from here

[release-clerk]

Release Notes Persisted

webContents.loadURL and loadFile now return a promise