feat: rename Locator.filter(locator) to Locator.and (#22101)

docs/src/api/class-locator.md

@@ -98,6 +98,45 @@ String[] texts = page.getByRole(AriaRole.LINK).allTextContents();
 var texts = await page.GetByRole(AriaRole.Link).AllTextContentsAsync();
 ```
 
+## method: Locator.and
+* since: v1.33
+* langs:
+  - alias-python: and_
+- returns: <[Locator]>
+
+Creates a locator that matches both this locator and the argument locator.
+
+**Usage**
+
+The following example finds a button with a specific title.
+
+```js
+const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
+```
+
+```java
+Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));
+```
+
+```python async
+button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
+```
+
+```python sync
+button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
+```
+
+```csharp
+var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe"));
+```
+
+### param: Locator.and.locator
+* since: v1.33
+- `locator` <[Locator]>
+
+Additional locator to match.
+
+
 ## async method: Locator.blur
 * since: v1.28
 
@@ -888,7 +927,7 @@ Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
 ### option: Locator.fill.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
-## method: Locator.filter#1
+## method: Locator.filter
 * since: v1.22
 - returns: <[Locator]>
 
@@ -946,47 +985,10 @@ await rowLocator
     .ScreenshotAsync();
 ```
 
-### option: Locator.filter#1.-inline- = %%-locator-options-list-v1.14-%%
+### option: Locator.filter.-inline- = %%-locator-options-list-v1.14-%%
 * since: v1.22
 
 
-## method: Locator.filter#2
-* since: v1.33
-- returns: <[Locator]>
-
-Creates a locator that matches both this locator and the argument locator.
-
-**Usage**
-
-The following example finds a button with a specific title.
-
-```js
-const button = page.getByRole('button').filter(page.getByTitle('Subscribe'));
-```
-
-```java
-Locator button = page.getByRole(AriaRole.BUTTON).filter(page.getByTitle("Subscribe"));
-```
-
-```python async
-button = page.get_by_role("button").filter(page.getByTitle("Subscribe"))
-```
-
-```python sync
-button = page.get_by_role("button").filter(page.getByTitle("Subscribe"))
-```
-
-```csharp
-var button = page.GetByRole(AriaRole.Button).Filter(page.GetByTitle("Subscribe"));
-```
-
-### param: Locator.filter#2.locator
-* since: v1.33
-- `locator` <[Locator]>
-
-Additional locator to match.
-
-
 ## method: Locator.first
 * since: v1.14
 - returns: <[Locator]>

docs/src/api/params.md

@@ -1233,7 +1233,7 @@ Learn more about [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-sele
 
 ## template-locator-locator
 
-The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to [`method: Locator.filter#1`] method.
+The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to [`method: Locator.filter`] method.
 
 [Learn more about locators](../locators.md).
 
@@ -1293,7 +1293,7 @@ use: {
 
 Allows locating elements that contain given text.
 
-See also [`method: Locator.filter#1`] that allows to match by another criteria, like an accessible role, and then filter by the text content.
+See also [`method: Locator.filter`] that allows to match by another criteria, like an accessible role, and then filter by the text content.
 
 
 **Usage**

docs/src/locators.md

@@ -806,7 +806,7 @@ Consider the following DOM structure where we want to click on the buy button of
 
 ### Filter by text
 
-Locators can be filtered by text with the [`method: Locator.filter#1`] method. It will search for a particular string somewhere inside the element, possibly in a descendant element, case-insensitively. You can also pass a regular expression.
+Locators can be filtered by text with the [`method: Locator.filter`] method. It will search for a particular string somewhere inside the element, possibly in a descendant element, case-insensitively. You can also pass a regular expression.
 
 ```js
 await page
@@ -987,26 +987,26 @@ Note that the inner locator is matched starting from the outer one, not from the
 
 ### Filter by matching an additional locator
 
-Method [`method: Locator.filter#2`] narrows down an existing locator by matching an additional locator. For example, you can combine [`method: Page.getByRole`] and [`method: Page.getByTitle`] to match by both role and title.
+Method [`method: Locator.and`] narrows down an existing locator by matching an additional locator. For example, you can combine [`method: Page.getByRole`] and [`method: Page.getByTitle`] to match by both role and title.
 
 ```js
-const button = page.getByRole('button').filter(page.getByTitle('Subscribe'));
+const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
 ```
 
 ```java
-Locator button = page.getByRole(AriaRole.BUTTON).filter(page.getByTitle("Subscribe"));
+Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));
 ```
 
 ```python async
-button = page.get_by_role("button").filter(page.getByTitle("Subscribe"))
+button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
 ```
 
 ```python sync
-button = page.get_by_role("button").filter(page.getByTitle("Subscribe"))
+button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))
 ```
 
 ```csharp
-var button = page.GetByRole(AriaRole.Button).Filter(page.GetByTitle("Subscribe"));
+var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe"));
 ```
 
 ### Filter by **not** matching an additional locator
@@ -1246,7 +1246,7 @@ await page.GetByText("orange").ClickAsync();
 ```
 
 #### Filter by text
-Use the [`method: Locator.filter#1`] to locate a specific item in a list.
+Use the [`method: Locator.filter`] to locate a specific item in a list.
 
 For example, consider the following DOM structure:
 
@@ -1351,7 +1351,7 @@ However, use this method with caution. Often times, the page might change, and t
 
 ### Chaining filters
 
-When you have elements with various similarities, you can use the [`method: Locator.filter#1`] method to select the right one. You can also chain multiple filters to narrow down the selection.
+When you have elements with various similarities, you can use the [`method: Locator.filter`] method to select the right one. You can also chain multiple filters to narrow down the selection.
 
 For example, consider the following DOM structure:
 

docs/src/other-locators.md

@@ -432,14 +432,14 @@ await page.Locator("button").Locator("nth=-1").ClickAsync();
 
 ## Parent element locator
 
-When you need to target a parent element of some other element, most of the time you should [`method: Locator.filter#1`] by the child locator. For example, consider the following DOM structure:
+When you need to target a parent element of some other element, most of the time you should [`method: Locator.filter`] by the child locator. For example, consider the following DOM structure:
 
 ```html
 <li><label>Hello</label></li>
 <li><label>World</label></li>
 ```
 
-If you'd like to target the parent `<li>` of a label with text `"Hello"`, using [`method: Locator.filter#1`] works best:
+If you'd like to target the parent `<li>` of a label with text `"Hello"`, using [`method: Locator.filter`] works best:
 
 ```js
 const child = page.getByText('Hello');
@@ -466,7 +466,7 @@ var child = page.GetByText("Hello");
 var parent = page.GetByRole(AriaRole.Listitem).Filter(new () { Has = child });
 ```
 
-Alternatively, if you cannot find a suitable locator for the parent element, use `xpath=..`. Note that this method is not as reliable, because any changes to the DOM structure will break your tests. Prefer [`method: Locator.filter#1`] when possible.
+Alternatively, if you cannot find a suitable locator for the parent element, use `xpath=..`. Note that this method is not as reliable, because any changes to the DOM structure will break your tests. Prefer [`method: Locator.filter`] when possible.
 
 ```js
 const parent = page.getByText('Hello').locator('xpath=..');

docs/src/release-notes-csharp.md

@@ -452,7 +452,7 @@ Note that the new methods [`method: Page.routeFromHAR`] and [`method: BrowserCon
 
   Read more in [our documentation](./locators.md#locate-by-role).
 
-- New [`method: Locator.filter#1`] API to filter an existing locator
+- New [`method: Locator.filter`] API to filter an existing locator
 
   ```csharp
   var buttons = page.Locator("role=button");

docs/src/release-notes-java.md

@@ -385,7 +385,7 @@ Note that the new methods [`method: Page.routeFromHAR`] and [`method: BrowserCon
 
   Read more in [our documentation](./locators.md#locate-by-role).
 
-- New [`method: Locator.filter#1`] API to filter an existing locator
+- New [`method: Locator.filter`] API to filter an existing locator
 
   ```java
   Locator buttonsLocator = page.locator("role=button");

docs/src/release-notes-js.md

@@ -786,7 +786,7 @@ WebServer is now considered "ready" if request to the specified url has any of t
 
   Read more in [our documentation](./locators.md#locate-by-role).
 
-- New [`method: Locator.filter#1`] API to filter an existing locator
+- New [`method: Locator.filter`] API to filter an existing locator
 
   ```js
   const buttons = page.locator('role=button');

docs/src/release-notes-python.md

@@ -440,7 +440,7 @@ Note that the new methods [`method: Page.routeFromHAR`] and [`method: BrowserCon
 
   Read more in [our documentation](./locators.md#locate-by-role).
 
-- New [`method: Locator.filter#1`] API to filter an existing locator
+- New [`method: Locator.filter`] API to filter an existing locator
 
   ```py
   buttons = page.locator("role=button")

packages/playwright-core/src/client/locator.ts

@@ -168,15 +168,8 @@ export class Locator implements api.Locator {
     return new FrameLocator(this._frame, this._selector + ' >> ' + selector);
   }
 
-  filter(options?: LocatorOptions): Locator;
-  filter(locator: Locator): Locator;
-  filter(optionsOrLocator?: LocatorOptions | Locator): Locator {
-    if (optionsOrLocator instanceof Locator) {
-      if (optionsOrLocator._frame !== this._frame)
-        throw new Error(`Locators must belong to the same frame.`);
-      return new Locator(this._frame, this._selector + ` >> internal:and=` + JSON.stringify(optionsOrLocator._selector));
-    }
-    return new Locator(this._frame, this._selector, optionsOrLocator);
+  filter(options?: LocatorOptions): Locator {
+    return new Locator(this._frame, this._selector, options);
   }
 
   async elementHandle(options?: TimeoutOptions): Promise<ElementHandle<SVGElement | HTMLElement>> {
@@ -187,6 +180,12 @@ export class Locator implements api.Locator {
     return this._frame.$$(this._selector);
   }
 
+  and(locator: Locator): Locator {
+    if (locator._frame !== this._frame)
+      throw new Error(`Locators must belong to the same frame.`);
+    return new Locator(this._frame, this._selector + ` >> internal:and=` + JSON.stringify(locator._selector));
+  }
+
   first(): Locator {
     return new Locator(this._frame, this._selector + ' >> nth=0');
   }

packages/playwright-core/src/server/injected/consoleApi.ts

@@ -53,14 +53,11 @@ class Locator {
     self.getByText = (text: string | RegExp, options?: { exact?: boolean }): Locator => self.locator(getByTextSelector(text, options));
     self.getByTitle = (text: string | RegExp, options?: { exact?: boolean }): Locator => self.locator(getByTitleSelector(text, options));
     self.getByRole = (role: string, options: ByRoleOptions = {}): Locator => self.locator(getByRoleSelector(role, options));
-    self.filter = (optionsOrLocator?: { hasText?: string | RegExp, has?: Locator } | Locator): Locator => {
-      if (optionsOrLocator instanceof Locator)
-        return new Locator(injectedScript, selectorBase + ` >> internal:and=` + JSON.stringify((optionsOrLocator as any)[selectorSymbol]));
-      return new Locator(injectedScript, selector, optionsOrLocator);
-    };
+    self.filter = (options?: { hasText?: string | RegExp, has?: Locator }): Locator => new Locator(injectedScript, selector, options);
     self.first = (): Locator => self.locator('nth=0');
     self.last = (): Locator => self.locator('nth=-1');
     self.nth = (index: number): Locator => self.locator(`nth=${index}`);
+    self.and = (locator: Locator): Locator => new Locator(injectedScript, selectorBase + ` >> internal:and=` + JSON.stringify((locator as any)[selectorSymbol]));
     self.or = (locator: Locator): Locator => new Locator(injectedScript, selectorBase + ` >> internal:or=` + JSON.stringify((locator as any)[selectorSymbol]));
     self.not = (locator: Locator): Locator => new Locator(injectedScript, selectorBase + ` >> internal:not=` + JSON.stringify((locator as any)[selectorSymbol]));
   }
@@ -94,6 +91,7 @@ class ConsoleAPI {
     delete this._injectedScript.window.playwright.first;
     delete this._injectedScript.window.playwright.last;
     delete this._injectedScript.window.playwright.nth;
+    delete this._injectedScript.window.playwright.and;
     delete this._injectedScript.window.playwright.or;
     delete this._injectedScript.window.playwright.not;
   }

packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts

@@ -213,7 +213,7 @@ export class JavaScriptLocatorFactory implements LocatorFactory {
       case 'or':
         return `or(${body})`;
       case 'and':
-        return `filter(${body})`;
+        return `and(${body})`;
       case 'not':
         return `not(${body})`;
       case 'test-id':
@@ -287,7 +287,7 @@ export class PythonLocatorFactory implements LocatorFactory {
       case 'or':
         return `or_(${body})`;
       case 'and':
-        return `filter(${body})`;
+        return `and_(${body})`;
       case 'not':
         return `not_(${body})`;
       case 'test-id':
@@ -370,7 +370,7 @@ export class JavaLocatorFactory implements LocatorFactory {
       case 'or':
         return `or(${body})`;
       case 'and':
-        return `filter(${body})`;
+        return `and(${body})`;
       case 'not':
         return `not(${body})`;
       case 'test-id':
@@ -447,7 +447,7 @@ export class CSharpLocatorFactory implements LocatorFactory {
       case 'or':
         return `Or(${body})`;
       case 'and':
-        return `Filter(${body})`;
+        return `And(${body})`;
       case 'not':
         return `Not(${body})`;
       case 'test-id':

packages/playwright-core/src/utils/isomorphic/locatorParser.ts

@@ -103,7 +103,7 @@ function shiftParams(template: string, sub: number) {
 
 function transform(template: string, params: TemplateParams, testIdAttributeName: string): string {
   // Recursively handle filter(has=).
-  // TODO: handle or(locator), not(locator) and filter(locator).
+  // TODO: handle or(locator), not(locator), and(locator).
   while (true) {
     const hasMatch = template.match(/filter\(,?has=/);
     if (!hasMatch)

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

@@ -2695,7 +2695,7 @@ export interface Page {
   /**
    * Allows locating elements that contain given text.
    *
-   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1) that allows to
+   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
    * match by another criteria, like an accessible role, and then filter by the text content.
    *
    * **Usage**
@@ -6119,7 +6119,7 @@ export interface Frame {
   /**
    * Allows locating elements that contain given text.
    *
-   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1) that allows to
+   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
    * match by another criteria, like an accessible role, and then filter by the text content.
    *
    * **Usage**
@@ -10387,6 +10387,21 @@ export interface Locator {
    */
   allTextContents(): Promise<Array<string>>;
 
+  /**
+   * Creates a locator that matches both this locator and the argument locator.
+   *
+   * **Usage**
+   *
+   * The following example finds a button with a specific title.
+   *
+   * ```js
+   * const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
+   * ```
+   *
+   * @param locator Additional locator to match.
+   */
+  and(locator: Locator): Locator;
+
   /**
    * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
    * @param options
@@ -10995,21 +11010,6 @@ export interface Locator {
     hasText?: string|RegExp;
   }): Locator;
 
-  /**
-   * Creates a locator that matches both this locator and the argument locator.
-   *
-   * **Usage**
-   *
-   * The following example finds a button with a specific title.
-   *
-   * ```js
-   * const button = page.getByRole('button').filter(page.getByTitle('Subscribe'));
-   * ```
-   *
-   * @param locator Additional locator to match.
-   */
-  filter(locator: Locator): Locator;
-
   /**
    * Returns locator to the first matching element.
    */
@@ -11290,7 +11290,7 @@ export interface Locator {
   /**
    * Allows locating elements that contain given text.
    *
-   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1) that allows to
+   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
    * match by another criteria, like an accessible role, and then filter by the text content.
    *
    * **Usage**
@@ -11634,7 +11634,7 @@ export interface Locator {
 
   /**
    * The method finds an element matching the specified selector in the locator's subtree. It also accepts filter
-   * options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1)
+   * options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter)
    * method.
    *
    * [Learn more about locators](https://playwright.dev/docs/locators).
@@ -17202,7 +17202,7 @@ export interface FrameLocator {
   /**
    * Allows locating elements that contain given text.
    *
-   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1) that allows to
+   * See also [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter) that allows to
    * match by another criteria, like an accessible role, and then filter by the text content.
    *
    * **Usage**
@@ -17286,7 +17286,7 @@ export interface FrameLocator {
 
   /**
    * The method finds an element matching the specified selector in the locator's subtree. It also accepts filter
-   * options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter-1)
+   * options, similar to [locator.filter([options])](https://playwright.dev/docs/api/class-locator#locator-filter)
    * method.
    *
    * [Learn more about locators](https://playwright.dev/docs/locators).

tests/library/inspector/console-api.spec.ts

@@ -77,9 +77,9 @@ it('should support locator.not()', async ({ page }) => {
   expect(await page.evaluate(`playwright.locator('div').not(playwright.locator('.foo')).elements.map(e => e.innerHTML)`)).toEqual(['Hello']);
 });
 
-it('should support locator.filter(locator)', async ({ page }) => {
+it('should support locator.and()', async ({ page }) => {
   await page.setContent('<div data-testid=Hey>Hi</div>');
-  expect(await page.evaluate(`playwright.locator('div').filter(playwright.getByTestId('Hey')).elements.map(e => e.innerHTML)`)).toEqual(['Hi']);
+  expect(await page.evaluate(`playwright.locator('div').and(playwright.getByTestId('Hey')).elements.map(e => e.innerHTML)`)).toEqual(['Hi']);
 });
 
 it('should support playwright.getBy*', async ({ page }) => {

tests/library/locator-generator.spec.ts

@@ -360,10 +360,10 @@ it('asLocator internal:or', async () => {
 });
 
 it('asLocator internal:and', async () => {
-  expect.soft(asLocator('javascript', 'div >> internal:and="span >> article"', false)).toBe(`locator('div').filter(locator('span').locator('article'))`);
-  expect.soft(asLocator('python', 'div >> internal:and="span >> article"', false)).toBe(`locator("div").filter(locator("span").locator("article"))`);
-  expect.soft(asLocator('java', 'div >> internal:and="span >> article"', false)).toBe(`locator("div").filter(locator("span").locator("article"))`);
-  expect.soft(asLocator('csharp', 'div >> internal:and="span >> article"', false)).toBe(`Locator("div").Filter(Locator("span").Locator("article"))`);
+  expect.soft(asLocator('javascript', 'div >> internal:and="span >> article"', false)).toBe(`locator('div').and(locator('span').locator('article'))`);
+  expect.soft(asLocator('python', 'div >> internal:and="span >> article"', false)).toBe(`locator("div").and_(locator("span").locator("article"))`);
+  expect.soft(asLocator('java', 'div >> internal:and="span >> article"', false)).toBe(`locator("div").and(locator("span").locator("article"))`);
+  expect.soft(asLocator('csharp', 'div >> internal:and="span >> article"', false)).toBe(`Locator("div").And(Locator("span").Locator("article"))`);
 });
 
 it('asLocator internal:not', async () => {

tests/page/locator-query.spec.ts

@@ -171,17 +171,17 @@ it('should support locator.or', async ({ page }) => {
   await expect(page.locator('span').or(page.locator('article'))).toHaveText('world');
 });
 
-it('should support locator.filter(locator)', async ({ page }) => {
+it('should support locator.and', async ({ page }) => {
   await page.setContent(`
     <div data-testid=foo>hello</div><div data-testid=bar>world</div>
     <span data-testid=foo>hello2</span><span data-testid=bar>world2</span>
   `);
-  await expect(page.locator('div').filter(page.locator('div'))).toHaveCount(2);
-  await expect(page.locator('div').filter(page.getByTestId('foo'))).toHaveText(['hello']);
-  await expect(page.locator('div').filter(page.getByTestId('bar'))).toHaveText(['world']);
-  await expect(page.getByTestId('foo').filter(page.locator('div'))).toHaveText(['hello']);
-  await expect(page.getByTestId('bar').filter(page.locator('span'))).toHaveText(['world2']);
-  await expect(page.locator('span').filter(page.getByTestId(/bar|foo/))).toHaveCount(2);
+  await expect(page.locator('div').and(page.locator('div'))).toHaveCount(2);
+  await expect(page.locator('div').and(page.getByTestId('foo'))).toHaveText(['hello']);
+  await expect(page.locator('div').and(page.getByTestId('bar'))).toHaveText(['world']);
+  await expect(page.getByTestId('foo').and(page.locator('div'))).toHaveText(['hello']);
+  await expect(page.getByTestId('bar').and(page.locator('span'))).toHaveText(['world2']);
+  await expect(page.locator('span').and(page.getByTestId(/bar|foo/))).toHaveCount(2);
 });
 
 it('should support locator.not', async ({ page }) => {