docs: webFrameMain.fromId() can return undefined (#27068)

* docs: webFrameMain.fromId() can return undefined

* docs: webFrameMain.fromId() can return undefined

docs/api/web-frame-main.md

@@ -63,7 +63,8 @@ These methods can be accessed from the `webFrameMain` module:
   instances (`frame.routingId`) and are also passed by frame
   specific `WebContents` navigation events (e.g. `did-frame-navigate`).
 
-Returns `WebFrameMain` - A frame with the given process and routing IDs.
+Returns `WebFrameMain | undefined` - A frame with the given process and routing IDs,
+or `undefined` if there is no WebFrameMain associated with the given IDs.
 
 ## Class: WebFrameMain
 

spec-main/api-web-frame-main-spec.ts

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as url from 'url';
 import { BrowserWindow, WebFrameMain, webFrameMain } from 'electron/main';
 import { closeAllWindows } from './window-helpers';
-import { emittedOnce } from './events-helpers';
+import { emittedOnce, emittedNTimes } from './events-helpers';
 import { AddressInfo } from 'net';
 
 describe('webFrameMain module', () => {
@@ -178,24 +178,24 @@ describe('webFrameMain module', () => {
     });
   });
 
-  it('webFrameMain.fromId can find each frame from navigation events', (done) => {
-    const w = new BrowserWindow({ show: false, webPreferences: { contextIsolation: true } });
-
-    w.loadFile(path.join(subframesPath, 'frame-with-frame-container.html'));
-
-    let eventCount = 0;
-    w.webContents.on('did-frame-finish-load', (event, isMainFrame, frameProcessId, frameRoutingId) => {
-      const frame = webFrameMain.fromId(frameProcessId, frameRoutingId);
-      expect(frame).not.to.be.null();
-      expect(frame?.processId).to.be.equal(frameProcessId);
-      expect(frame?.routingId).to.be.equal(frameRoutingId);
-      expect(frame?.top === frame).to.be.equal(isMainFrame);
+  describe('webFrameMain.fromId', () => {
+    it('returns undefined for unknown IDs', () => {
+      expect(webFrameMain.fromId(0, 0)).to.be.undefined();
+    });
 
-      eventCount++;
+    it('can find each frame from navigation events', async () => {
+      const w = new BrowserWindow({ show: false, webPreferences: { contextIsolation: true } });
 
       // frame-with-frame-container.html, frame-with-frame.html, frame.html
-      if (eventCount === 3) {
-        done();
+      const didFrameFinishLoad = emittedNTimes(w.webContents, 'did-frame-finish-load', 3);
+      w.loadFile(path.join(subframesPath, 'frame-with-frame-container.html'));
+
+      for (const [, isMainFrame, frameProcessId, frameRoutingId] of await didFrameFinishLoad) {
+        const frame = webFrameMain.fromId(frameProcessId, frameRoutingId);
+        expect(frame).not.to.be.null();
+        expect(frame?.processId).to.be.equal(frameProcessId);
+        expect(frame?.routingId).to.be.equal(frameRoutingId);
+        expect(frame?.top === frame).to.be.equal(isMainFrame);
       }
     });
   });