From cddf3293cfe500affedc5808fe461c3498cedc8b Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Thu, 16 Jun 2022 10:05:30 -0700
Subject: [PATCH] docs: mention chaining in locator.filter (#14920)

---
 docs/src/api/class-locator.md             | 46 +++++++++++++++++++++++
 docs/src/locators.md                      | 41 ++++++++++++++------
 packages/playwright-core/types/types.d.ts | 13 ++++++-
 3 files changed, 88 insertions(+), 12 deletions(-)

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index a70d736037..8ee10386e9 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -388,6 +388,52 @@ Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
 - returns: <[Locator]>
 
 This method narrows existing locator according to the options, for example filters by text.
+It can be chained to filter multiple times.
+
+```js
+const rowLocator = page.locator('tr');
+// ...
+await rowLocator
+    .filter({ hasText: 'text in column 1' })
+    .filter({ has: page.locator('button', { hasText: 'column 2 button' }) })
+    .screenshot();
+```
+```java
+Locator rowLocator = page.locator("tr");
+// ...
+rowLocator
+    .filter(new Locator.FilterOptions().setHasText("text in column 1"))
+    .filter(new Locator.FilterOptions().setHas(
+        page.locator("button", new Page.LocatorOptions().setHasText("column 2 button"))
+    ))
+    .screenshot();
+```
+```python async
+row_locator = page.lsocator("tr")
+# ...
+await row_locator
+    .filter(has_text="text in column 1")
+    .filter(has=page.locator("tr", has_text="column 2 button"))
+    .screenshot()
+```
+```python sync
+row_locator = page.lsocator("tr")
+# ...
+row_locator
+    .filter(has_text="text in column 1")
+    .filter(has=page.locator("tr", has_text="column 2 button"))
+    .screenshot()
+```
+```csharp
+var rowLocator = page.Locator("tr");
+// ...
+await rowLocator
+    .Filter(new LocatorFilterOptions { HasText = "text in column 1" })
+    .Filter(new LocatorFilterOptions {
+        Has = page.Locator("tr", new PageLocatorOptions { HasText = "column 2 button" } )
+    })
+    .ScreenshotAsync();
+```
 
 ### option: Locator.filter.-inline- = %%-locator-options-list-%%
 
diff --git a/docs/src/locators.md b/docs/src/locators.md
index 23e0ba8df6..e755e0a35e 100644
--- a/docs/src/locators.md
+++ b/docs/src/locators.md
@@ -316,32 +316,51 @@ page.locator("article", has=page.locator("button.subscribe"))
 page.Locator("article", new PageLocatorOptions { Has = page.Locator("button.subscribe") })
 ```
 
-You can also filter an existing locator with [`method: Locator.filter`] method.
+You can also filter an existing locator with [`method: Locator.filter`] method, possibly chaining it multiple times.
 
 ```js
-const buttonLocator = page.locator('button');
+const rowLocator = page.locator('tr');
 // ...
-await buttonLocator.filter({ hasText: 'Sign up' }).click();
+await rowLocator
+    .filter({ hasText: 'text in column 1' })
+    .filter({ has: page.locator('button', { hasText: 'column 2 button' }) })
+    .screenshot();
 ```
 ```java
-Locator buttonLocator = page.locator("button");
+Locator rowLocator = page.locator("tr");
 // ...
-buttonLocator.filter(new Locator.FilterOptions().setHasText("Sign up")).click();
+rowLocator
+    .filter(new Locator.FilterOptions().setHasText("text in column 1"))
+    .filter(new Locator.FilterOptions().setHas(
+        page.locator("button", new Page.LocatorOptions().setHasText("column 2 button"))
+    ))
+    .screenshot();
 ```
 ```python async
-button_locator = page.locator("button")
+row_locator = page.lsocator("tr")
 # ...
-await button_locator.filter(has_text="Sign up").click()
+await row_locator
+    .filter(has_text="text in column 1")
+    .filter(has=page.locator("tr", has_text="column 2 button"))
+    .screenshot()
 ```
 ```python sync
-button_locator = page.locator("button")
+row_locator = page.lsocator("tr")
 # ...
-button_locator.filter(has_text="Sign up").click()
+row_locator
+    .filter(has_text="text in column 1")
+    .filter(has=page.locator("tr", has_text="column 2 button"))
+    .screenshot()
 ```
 ```csharp
-var buttonLocator = page.Locator("button");
+var rowLocator = page.Locator("tr");
 // ...
-await buttonLocator.Filter(new LocatorFilterOptions { HasText = "Sign up" }).ClickAsync();
+await rowLocator
+    .Filter(new LocatorFilterOptions { HasText = "text in column 1" })
+    .Filter(new LocatorFilterOptions {
+        Has = page.Locator("tr", new PageLocatorOptions { HasText = "column 2 button" } )
+    })
+    .ScreenshotAsync();
 ```
 
 ## Locator vs ElementHandle
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index f5ad646c8b..d6b6e3bd9b 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -9476,7 +9476,18 @@ export interface Locator {
   }): Promise<void>;
 
   /**
-   * This method narrows existing locator according to the options, for example filters by text.
+   * This method narrows existing locator according to the options, for example filters by text. It can be chained to filter
+   * multiple times.
+   *
+   * ```js
+   * const rowLocator = page.locator('tr');
+   * // ...
+   * await rowLocator
+   *     .filter({ hasText: 'text in column 1' })
+   *     .filter({ has: page.locator('button', { hasText: 'column 2 button' }) })
+   *     .screenshot();
+   * ```
+   *
    * @param options
    */
   filter(options?: {