docs: add warning to locator.all (#22537)

References #22517.
microsoft · Apr 24, 2023 · 05b113f · 05b113f
1 parent 62bd419
commit 05b113f
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 5 deletions.
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
@@ -13,7 +13,13 @@ a way to find element(s) on the page at any moment. Locator can be created with
 When locator points to a list of elements, returns array of locators, pointing
 to respective elements.
 
-Note that [`method: Locator.all`] does not wait for elements to match the locator, and instead immediately returns whatever is present in the page. To avoid flakiness when elements are loaded dynamically, wait for the loading to finish before calling [`method: Locator.all`].
+:::note
+[`method: Locator.all`] does not wait for elements to match the locator, and instead immediately returns whatever is present in the page.
+
+When the list of elements changes dynamically, [`method: Locator.all`] will produce unpredictable and flaky results.
+
+When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling [`method: Locator.all`].
+:::
 
 **Usage**
 

diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
@@ -10203,10 +10203,11 @@ export interface Locator {
   /**
    * When locator points to a list of elements, returns array of locators, pointing to respective elements.
    *
-   * Note that [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) does not wait for elements to
-   * match the locator, and instead immediately returns whatever is present in the page. To avoid flakiness when
-   * elements are loaded dynamically, wait for the loading to finish before calling
-   * [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all).
+   * **NOTE** [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) does not wait for elements to
+   * match the locator, and instead immediately returns whatever is present in the page.  When the list of elements
+   * changes dynamically, [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all) will produce
+   * unpredictable and flaky results.  When the list of elements is stable, but loaded dynamically, wait for the full
+   * list to finish loading before calling [locator.all()](https://playwright.dev/docs/api/class-locator#locator-all).
    *
    * **Usage**
    *