docs: add comments to Promise.all snippets with explanation (#11379)

Drive-by: more locators.

docs/src/api/class-download.md

@@ -8,9 +8,13 @@ browser context is closed.
 Download event is emitted once the download starts. Download path becomes available once download completes:
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the download.
 const [ download ] = await Promise.all([
-  page.waitForEvent('download'), // wait for download to start
-  page.click('a')
+  // It is important to call waitForEvent before click to set up waiting.
+  page.waitForEvent('download'),
+  // Triggers the download.
+  page.locator('text=Download file').click(),
 ]);
 // wait for download to complete
 const path = await download.path();

docs/src/api/class-filechooser.md

@@ -3,9 +3,13 @@
 [FileChooser] objects are dispatched by the page in the [`event: Page.fileChooser`] event.
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the file chooser.
 const [fileChooser] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('filechooser'),
-  page.click('upload')
+  // Opens the file chooser.
+  page.locator('text=Upload').click(),
 ]);
 await fileChooser.setFiles('myfile.pdf');
 ```

docs/src/api/class-page.md

@@ -366,8 +366,12 @@ popup with `window.open('http://example.com')`, this event will fire when the ne
 done and its response has started loading in the popup.
 
 ```js
+// Note that Promise.all prevents a race condition
+// between evaluating and waiting for the popup.
 const [popup] = await Promise.all([
+  // It is important to call waitForEvent first.
   page.waitForEvent('popup'),
+  // Opens the popup.
   page.evaluate(() => window.open('https://example.com')),
 ]);
 console.log(await popup.evaluate('location.href'));
@@ -3122,9 +3126,13 @@ Waits for event to fire and passes its value into the predicate function. Return
 value. Will throw an error if the page is closed before the event is fired. Returns the event data value.
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the event.
 const [frame, _] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('framenavigated'),
-  page.click('button')
+  // Triggers the navigation.
+  page.locator('button').click(),
 ]);
 ```
 
@@ -3331,8 +3339,10 @@ await page.WaitForLoadStateAsync(); // The promise resolves after 'load' event.
 
 ```js
 const [popup] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('popup'),
-  page.click('button'), // Click triggers a popup.
+  // Click triggers a popup.
+  page.locator('button').click(),
 ])
 await popup.waitForLoadState('domcontentloaded'); // The promise resolves after 'domcontentloaded' event.
 console.log(await popup.title()); // Popup is ready to use.
@@ -3394,9 +3404,13 @@ cause the page to navigate. e.g. The click target has an `onclick` handler that
 Consider this example:
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the navigation.
 const [response] = await Promise.all([
-  page.waitForNavigation(), // The promise resolves after navigation has finished
-  page.click('a.delayed-navigation'), // Clicking the link will indirectly cause a navigation
+  // It is important to call waitForNavigation before click to set up waiting.
+  page.waitForNavigation(),
+  // Clicking the link will indirectly cause a navigation.
+  page.locator('a.delayed-navigation').click(),
 ]);
 ```
 

docs/src/downloads.md

@@ -24,7 +24,7 @@ const [ download ] = await Promise.all([
   // Start waiting for the download
   page.waitForEvent('download'),
   // Perform the action that initiates download
-  page.click('button#delayed-download')
+  page.locator('button#delayed-download').click(),
 ]);
 // Wait for the download process to complete
 const path = await download.path();

docs/src/events.md

@@ -62,6 +62,7 @@ Wait for popup window:
 // Note that Promise.all prevents a race condition
 // between clicking and waiting for the popup.
 const [popup] = await Promise.all([
+  // It is important to call waitForEvent first.
   page.waitForEvent('popup'),
   // This action triggers the popup
   page.evaluate('window.open()')

docs/src/input.md

@@ -721,9 +721,12 @@ If you don't have input element in hand (it is created dynamically), you can han
 or use a corresponding waiting method upon your action:
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the file chooser.
 const [fileChooser] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('filechooser'),
-  page.click('upload')
+  page.locator('upload').click(),
 ]);
 await fileChooser.setFiles('myfile.pdf');
 ```

docs/src/navigations.md

@@ -313,8 +313,11 @@ recommended to explicitly call [`method: Page.waitForNavigation`]. For example:
 // Note that Promise.all prevents a race condition
 // between clicking and waiting for a navigation.
 await Promise.all([
-  page.waitForNavigation(), // Waits for the next navigation
-  page.click('div.delayed-navigation'), // Triggers a navigation after a timeout
+  // Waits for the next navigation.
+  // It is important to call waitForNavigation before click to set up waiting.
+  page.waitForNavigation(),
+  // Triggers a navigation after a timeout.
+  page.locator('div.delayed-navigation').clikc(),
 ]);
 ```
 
@@ -363,8 +366,10 @@ Clicking an element could trigger multiple navigations. In these cases, it is re
 // Note that Promise.all prevents a race condition
 // between clicking and waiting for a navigation.
 await Promise.all([
+  // It is important to call waitForNavigation before click to set up waiting.
   page.waitForNavigation({ url: '**/login' }),
-  page.click('a'), // Triggers a navigation with a script redirect
+  // Triggers a navigation with a script redirect.
+  page.locator('text=Click me').click(),
 ]);
 ```
 
@@ -411,9 +416,13 @@ When popup is opened, explicitly calling [`method: Page.waitForLoadState`] ensur
 state.
 
 ```js
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the popup.
 const [ popup ] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('popup'),
-  page.click('a[target="_blank"]'),  // Opens popup
+  // Opens popup.
+  page.locator('a[target="_blank"]').click(),
 ]);
 await popup.waitForLoadState('load');
 ```

docs/src/pages.md

@@ -241,10 +241,13 @@ If the page opens a pop-up (e.g. pages opened by `target="_blank"` links), you c
 This event is emitted in addition to the `browserContext.on('page')` event, but only for popups relevant to this page.
 
 ```js
-// Get popup after a specific action (e.g., click)
+// Note that Promise.all prevents a race condition
+// between clicking and waiting for the popup.
 const [popup] = await Promise.all([
+  // It is important to call waitForEvent before click to set up waiting.
   page.waitForEvent('popup'),
-  page.click('#open')
+  // Opens popup.
+  page.locator('#open').click(),
 ]);
 await popup.waitForLoadState();
 console.log(await popup.title());

packages/playwright-core/types/types.d.ts

@@ -955,8 +955,12 @@ export interface Page {
    * done and its response has started loading in the popup.
    *
    * ```js
+   * // Note that Promise.all prevents a race condition
+   * // between evaluating and waiting for the popup.
    * const [popup] = await Promise.all([
+   *   // It is important to call waitForEvent first.
    *   page.waitForEvent('popup'),
+   *   // Opens the popup.
    *   page.evaluate(() => window.open('https://example.com')),
    * ]);
    * console.log(await popup.evaluate('location.href'));
@@ -1224,8 +1228,12 @@ export interface Page {
    * done and its response has started loading in the popup.
    *
    * ```js
+   * // Note that Promise.all prevents a race condition
+   * // between evaluating and waiting for the popup.
    * const [popup] = await Promise.all([
+   *   // It is important to call waitForEvent first.
    *   page.waitForEvent('popup'),
+   *   // Opens the popup.
    *   page.evaluate(() => window.open('https://example.com')),
    * ]);
    * console.log(await popup.evaluate('location.href'));
@@ -3578,8 +3586,12 @@ export interface Page {
    * done and its response has started loading in the popup.
    *
    * ```js
+   * // Note that Promise.all prevents a race condition
+   * // between evaluating and waiting for the popup.
    * const [popup] = await Promise.all([
+   *   // It is important to call waitForEvent first.
    *   page.waitForEvent('popup'),
+   *   // Opens the popup.
    *   page.evaluate(() => window.open('https://example.com')),
    * ]);
    * console.log(await popup.evaluate('location.href'));
@@ -3646,8 +3658,10 @@ export interface Page {
    *
    * ```js
    * const [popup] = await Promise.all([
+   *   // It is important to call waitForEvent before click to set up waiting.
    *   page.waitForEvent('popup'),
-   *   page.click('button'), // Click triggers a popup.
+   *   // Click triggers a popup.
+   *   page.locator('button').click(),
    * ])
    * await popup.waitForLoadState('domcontentloaded'); // The promise resolves after 'domcontentloaded' event.
    * console.log(await popup.title()); // Popup is ready to use.
@@ -3683,9 +3697,13 @@ export interface Page {
    * Consider this example:
    *
    * ```js
+   * // Note that Promise.all prevents a race condition
+   * // between clicking and waiting for the navigation.
    * const [response] = await Promise.all([
-   *   page.waitForNavigation(), // The promise resolves after navigation has finished
-   *   page.click('a.delayed-navigation'), // Clicking the link will indirectly cause a navigation
+   *   // It is important to call waitForNavigation before click to set up waiting.
+   *   page.waitForNavigation(),
+   *   // Clicking the link will indirectly cause a navigation.
+   *   page.locator('a.delayed-navigation').click(),
    * ]);
    * ```
    *
@@ -13257,9 +13275,13 @@ export interface Dialog {
  * Download event is emitted once the download starts. Download path becomes available once download completes:
  *
  * ```js
+ * // Note that Promise.all prevents a race condition
+ * // between clicking and waiting for the download.
  * const [ download ] = await Promise.all([
- *   page.waitForEvent('download'), // wait for download to start
- *   page.click('a')
+ *   // It is important to call waitForEvent before click to set up waiting.
+ *   page.waitForEvent('download'),
+ *   // Triggers the download.
+ *   page.locator('text=Download file').click(),
  * ]);
  * // wait for download to complete
  * const path = await download.path();
@@ -13529,9 +13551,13 @@ export interface Electron {
  * [page.on('filechooser')](https://playwright.dev/docs/api/class-page#page-event-file-chooser) event.
  *
  * ```js
+ * // Note that Promise.all prevents a race condition
+ * // between clicking and waiting for the file chooser.
  * const [fileChooser] = await Promise.all([
+ *   // It is important to call waitForEvent before click to set up waiting.
  *   page.waitForEvent('filechooser'),
- *   page.click('upload')
+ *   // Opens the file chooser.
+ *   page.locator('text=Upload').click(),
  * ]);
  * await fileChooser.setFiles('myfile.pdf');
  * ```