feat: implement Locator.prototype.filter (#10631)

docs/api/puppeteer.locator.filter.md

@@ -0,0 +1,27 @@
+---
+sidebar_label: Locator.filter
+---
+
+# Locator.filter() method
+
+Creates an expectation that is evaluated against located values.
+
+If the expectations do not match, then the locator will retry.
+
+#### Signature:
+
+```typescript
+class Locator {
+  filter<S extends T>(predicate: Predicate<T, S>): Locator<S>;
+}
+```
+
+## Parameters
+
+| Parameter | Type                                              | Description |
+| --------- | ------------------------------------------------- | ----------- |
+| predicate | [Predicate](./puppeteer.predicate.md)&lt;T, S&gt; |             |
+
+**Returns:**
+
+[Locator](./puppeteer.locator.md)&lt;S&gt;

docs/api/puppeteer.locator.md

@@ -26,6 +26,7 @@ export declare abstract class Locator<T> extends EventEmitter
 | ------------------------------------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [click(this, options)](./puppeteer.locator.click.md)                                                   |                     |                                                                                                                                                                                                                                          |
 | [fill(this, value, options)](./puppeteer.locator.fill.md)                                              |                     | Fills out the input identified by the locator using the provided value. The type of the input is determined at runtime and the appropriate fill-out method is chosen based on the type. contenteditable, selector, inputs are supported. |
+| [filter(predicate)](./puppeteer.locator.filter.md)                                                     |                     | <p>Creates an expectation that is evaluated against located values.</p><p>If the expectations do not match, then the locator will retry.</p>                                                                                             |
 | [hover(this, options)](./puppeteer.locator.hover.md)                                                   |                     |                                                                                                                                                                                                                                          |
 | [map(mapper)](./puppeteer.locator.map.md)                                                              |                     | Maps the locator using the provided mapper.                                                                                                                                                                                              |
 | [off(eventName, handler)](./puppeteer.locator.off.md)                                                  |                     |                                                                                                                                                                                                                                          |

packages/puppeteer-core/src/api/locators/FilteredLocator.ts

@@ -37,7 +37,7 @@ export type Predicate<From, To extends From = From> =
 /**
  * @internal
  */
-export class ExpectedLocator<From, To extends From> extends DelegatedLocator<
+export class FilteredLocator<From, To extends From> extends DelegatedLocator<
   From,
   To
 > {

packages/puppeteer-core/src/api/locators/Locator.ts

@@ -47,7 +47,7 @@ import {BoundingBox, ClickOptions, ElementHandle} from '../ElementHandle.js';
 import {
   Action,
   AwaitedLocator,
-  ExpectedLocator,
+  FilteredLocator,
   MappedLocator,
   Mapper,
   Predicate,
@@ -671,10 +671,10 @@ export abstract class Locator<T> extends EventEmitter {
    *
    * If the expectations do not match, then the locator will retry.
    *
-   * @internal
+   * @public
    */
-  expect<S extends T>(predicate: Predicate<T, S>): Locator<S> {
+  filter<S extends T>(predicate: Predicate<T, S>): Locator<S> {
-    return new ExpectedLocator(this, predicate);
+    return new FilteredLocator(this, predicate);
   }
 
   click<ElementType extends Element>(

packages/puppeteer-core/src/api/locators/locators.ts

@@ -16,7 +16,7 @@
 
 export * from './Locator.js';
 export * from './NodeLocator.js';
-export * from './ExpectedLocator.js';
+export * from './FilteredLocator.js';
 export * from './RaceLocator.js';
 export * from './DelegatedLocator.js';
 export * from './MappedLocator.js';

test/src/locator.spec.ts

@@ -587,7 +587,7 @@ describe('Locator', function () {
       await page.setContent(`<div>test</div>`);
       const result = page
         .locator('::-p-text(test)')
-        .expect(element => {
+        .filter(element => {
           return element.getAttribute('clickable') !== null;
         })
         .map(element => {
@@ -601,7 +601,7 @@ describe('Locator', function () {
     });
   });
 
-  describe('Locator.prototype.expect', () => {
+  describe('Locator.prototype.filter', () => {
     it('should resolve as soon as the predicate matches', async () => {
       const clock = sinon.useFakeTimers({
         shouldClearNativeTimers: true,
@@ -612,10 +612,10 @@ describe('Locator', function () {
         const result = page
           .locator('::-p-text(test)')
           .setTimeout(5000)
-          .expect(async element => {
+          .filter(async element => {
             return element.getAttribute('clickable') === 'true';
           })
-          .expect(element => {
+          .filter(element => {
             return element.getAttribute('clickable') === 'true';
           })
           .hover();