From 3daf00806720df6afb762153872bb61d651ad310 Mon Sep 17 00:00:00 2001
From: Pavel Feldman <pavel.feldman@gmail.com>
Date: Thu, 2 Dec 2021 20:29:38 -0800
Subject: [PATCH] docs(locator): add section on working with the lists (#10651)

---
 docs/src/api/class-locator.md             | 89 +++++++++++++++++++++++
 packages/playwright-core/types/types.d.ts | 21 ++++++
 2 files changed, 110 insertions(+)

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index ec5d12efc0..6153769306 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -156,6 +156,95 @@ await page.Locator("button").First.ClickAsync();
 await page.Locator("button").CountAsync();
 ```
 
+**Lists**
+
+You can also use locators to work with the element lists.
+
+```js
+// Locate elements, this locator points to a list.
+const rows = page.locator('table tr');
+
+// Pattern 1: use locator methods to calculate text on the whole list.
+const texts = await rows.allTextContents();
+
+// Pattern 2: do something with each element in the list.
+const count = await rows.count()
+for (let i = 0; i < count; ++i)
+  console.log(await rows.nth(i).textContent());
+
+// Pattern 3: resolve locator to elements on page and map them to their text content.
+// Note: the code inside evaluateAll runs in page, you can call any DOM apis there.
+const texts = await rows.evaluateAll(list => list.map(element => element.textContent));
+```
+
+```python async
+# Locate elements, this locator points to a list.
+rows = page.locator("table tr")
+
+# Pattern 1: use locator methods to calculate text on the whole list.
+texts = await rows.all_text_contents()
+
+# Pattern 2: do something with each element in the list.
+count = await rows.count()
+for i in range(count):
+  print(await rows.nth(i).text_content())
+
+# Pattern 3: resolve locator to elements on page and map them to their text content.
+# Note: the code inside evaluateAll runs in page, you can call any DOM apis there.
+texts = await rows.evaluate_all("list => list.map(element => element.textContent)")
+```
+
+```python sync
+# Locate elements, this locator points to a list.
+rows = page.locator("table tr")
+
+# Pattern 1: use locator methods to calculate text on the whole list.
+texts = rows.all_text_contents()
+
+# Pattern 2: do something with each element in the list.
+count = rows.count()
+for i in range(count):
+  print(rows.nth(i).text_content())
+
+# Pattern 3: resolve locator to elements on page and map them to their text content.
+# Note: the code inside evaluateAll runs in page, you can call any DOM apis there.
+texts = rows.evaluate_all("list => list.map(element => element.textContent)")
+```
+
+```java
+// Locate elements, this locator points to a list.
+Locator rows = page.locator("table tr");
+
+// Pattern 1: use locator methods to calculate text on the whole list.
+List<String> texts = rows.allTextContents();
+
+// Pattern 2: do something with each element in the list.
+int count = rows.count()
+for (int i = 0; i < count; ++i)
+  System.out.println(rows.nth(i).textContent());
+
+// Pattern 3: resolve locator to elements on page and map them to their text content.
+// Note: the code inside evaluateAll runs in page, you can call any DOM apis there.
+Object texts = rows.evaluateAll("list => list.map(element => element.textContent)");
+```
+
+```csharp
+// Locate elements, this locator points to a list.
+var rows = page.Locator("table tr");
+
+// Pattern 1: use locator methods to calculate text on the whole list.
+var texts = await rows.AllTextContentsAsync();
+
+// Pattern 2: do something with each element in the list:
+var count = await rows.CountAsync()
+for (let i = 0; i < count; ++i)
+  Console.WriteLine(await rows.Nth(i).TextContentAsync());
+
+// Pattern 3: resolve locator to elements on page and map them to their text content
+// Note: the code inside evaluateAll runs in page, you can call any DOM apis there
+var texts = await rows.EvaluateAllAsync("list => list.map(element => element.textContent)");
+```
+
 ## async method: Locator.allInnerTexts
 - returns: <[Array]<[string]>>
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index bd89fd5d4e..5d4214f528 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -8528,6 +8528,27 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
  * await page.locator('button').count();
  * ```
  *
+ * **Lists**
+ *
+ * You can also use locators to work with the element lists.
+ *
+ * ```js
+ * // Locate elements, this locator points to a list.
+ * const rows = page.locator('table tr');
+ *
+ * // Pattern 1: use locator methods to calculate text on the whole list.
+ * const texts = await rows.allTextContents();
+ *
+ * // Pattern 2: do something with each element in the list.
+ * const count = await rows.count()
+ * for (let i = 0; i < count; ++i)
+ *   console.log(await rows.nth(i).textContent());
+ *
+ * // Pattern 3: resolve locator to elements on page and map them to their text content.
+ * // Note: the code inside evaluateAll runs in page, you can call any DOM apis there.
+ * const texts = await rows.evaluateAll(list => list.map(element => element.textContent));
+ * ```
+ *
  */
 export interface Locator {
   /**