docs(queryhandler): add custom query handler docs (#6476)

new-docs/puppeteer.customqueryhandler.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CustomQueryHandler](./puppeteer.customqueryhandler.md)
+
+## CustomQueryHandler interface
+
+Contains two functions `queryOne` and `queryAll` that can be [registered](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) as alternative querying strategies. The functions `queryOne` and `queryAll` are executed in the page context. `queryOne` should take an `Element` and a selector string as argument and return a single `Element` or `null` if no element is found. `queryAll` takes the same arguments but should instead return a `NodeListOf<Element>` or `Array<Element>` with all the elements that match the given query selector.
+
+<b>Signature:</b>
+
+```typescript
+export interface CustomQueryHandler 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [queryAll](./puppeteer.customqueryhandler.queryall.md) | (element: Element \| Document, selector: string) =&gt; Element\[\] \| NodeListOf&lt;Element&gt; |  |
+|  [queryOne](./puppeteer.customqueryhandler.queryone.md) | (element: Element \| Document, selector: string) =&gt; Element \| null |  |
+

new-docs/puppeteer.customqueryhandler.queryall.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CustomQueryHandler](./puppeteer.customqueryhandler.md) &gt; [queryAll](./puppeteer.customqueryhandler.queryall.md)
+
+## CustomQueryHandler.queryAll property
+
+<b>Signature:</b>
+
+```typescript
+queryAll?: (element: Element | Document, selector: string) => Element[] | NodeListOf<Element>;
+```

new-docs/puppeteer.customqueryhandler.queryone.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CustomQueryHandler](./puppeteer.customqueryhandler.md) &gt; [queryOne](./puppeteer.customqueryhandler.queryone.md)
+
+## CustomQueryHandler.queryOne property
+
+<b>Signature:</b>
+
+```typescript
+queryOne?: (element: Element | Document, selector: string) => Element | null;
+```

new-docs/puppeteer.md

@@ -59,6 +59,7 @@
 |  [CoverageEntry](./puppeteer.coverageentry.md) | The CoverageEntry class represents one entry of the coverage report. |
 |  [Credentials](./puppeteer.credentials.md) |  |
 |  [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) | Set of configurable options for CSS coverage. |
+|  [CustomQueryHandler](./puppeteer.customqueryhandler.md) | Contains two functions <code>queryOne</code> and <code>queryAll</code> that can be [registered](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) as alternative querying strategies. The functions <code>queryOne</code> and <code>queryAll</code> are executed in the page context. <code>queryOne</code> should take an <code>Element</code> and a selector string as argument and return a single <code>Element</code> or <code>null</code> if no element is found. <code>queryAll</code> takes the same arguments but should instead return a <code>NodeListOf&lt;Element&gt;</code> or <code>Array&lt;Element&gt;</code> with all the elements that match the given query selector. |
 |  [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) |  |
 |  [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md) |  |
 |  [FrameWaitForFunctionOptions](./puppeteer.framewaitforfunctionoptions.md) |  |

new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Puppeteer](./puppeteer.puppeteer.md) &gt; [\_\_experimental\_clearQueryHandlers](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md)
+
+## Puppeteer.\_\_experimental\_clearQueryHandlers() method
+
+Clears all registered handlers.
+
+<b>Signature:</b>
+
+```typescript
+__experimental_clearQueryHandlers(): void;
+```
+<b>Returns:</b>
+
+void
+

new-docs/puppeteer.puppeteer.__experimental_customqueryhandlernames.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Puppeteer](./puppeteer.puppeteer.md) &gt; [\_\_experimental\_customQueryHandlerNames](./puppeteer.puppeteer.__experimental_customqueryhandlernames.md)
+
+## Puppeteer.\_\_experimental\_customQueryHandlerNames() method
+
+<b>Signature:</b>
+
+```typescript
+__experimental_customQueryHandlerNames(): string[];
+```
+<b>Returns:</b>
+
+string\[\]
+
+a list with the names of all registered custom query handlers.
+

new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md

@@ -0,0 +1,34 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Puppeteer](./puppeteer.puppeteer.md) &gt; [\_\_experimental\_registerCustomQueryHandler](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md)
+
+## Puppeteer.\_\_experimental\_registerCustomQueryHandler() method
+
+Registers a [custom query handler](./puppeteer.customqueryhandler.md)<!-- -->. After registration, the handler can be used everywhere where a selector is expected by prepending the selection string with `<name>/`<!-- -->. The name is only allowed to consist of lower- and upper case latin letters.
+
+<b>Signature:</b>
+
+```typescript
+__experimental_registerCustomQueryHandler(name: string, queryHandler: CustomQueryHandler): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  name | string | The name that the custom query handler will be registered under. |
+|  queryHandler | [CustomQueryHandler](./puppeteer.customqueryhandler.md) | The [custom query handler](./puppeteer.customqueryhandler.md) to register. |
+
+<b>Returns:</b>
+
+void
+
+## Example
+
+
+```
+puppeteer.registerCustomQueryHandler('text', { … });
+const aHandle = await page.$('text/…');
+
+```
+

new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Puppeteer](./puppeteer.puppeteer.md) &gt; [\_\_experimental\_unregisterCustomQueryHandler](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md)
+
+## Puppeteer.\_\_experimental\_unregisterCustomQueryHandler() method
+
+<b>Signature:</b>
+
+```typescript
+__experimental_unregisterCustomQueryHandler(name: string): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  name | string | The name of the query handler to unregistered. |
+
+<b>Returns:</b>
+
+void
+

new-docs/puppeteer.puppeteer.md

@@ -48,6 +48,10 @@ Once you have created a `page` you have access to a large API to interact with t
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
+|  [\_\_experimental\_clearQueryHandlers()](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md) |  | Clears all registered handlers. |
+|  [\_\_experimental\_customQueryHandlerNames()](./puppeteer.puppeteer.__experimental_customqueryhandlernames.md) |  |  |
+|  [\_\_experimental\_registerCustomQueryHandler(name, queryHandler)](./puppeteer.puppeteer.__experimental_registercustomqueryhandler.md) |  | Registers a [custom query handler](./puppeteer.customqueryhandler.md)<!-- -->. After registration, the handler can be used everywhere where a selector is expected by prepending the selection string with <code>&lt;name&gt;/</code>. The name is only allowed to consist of lower- and upper case latin letters. |
+|  [\_\_experimental\_unregisterCustomQueryHandler(name)](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md) |  |  |
 |  [connect(options)](./puppeteer.puppeteer.connect.md) |  | This method attaches Puppeteer to an existing browser instance. |
 |  [createBrowserFetcher(options)](./puppeteer.puppeteer.createbrowserfetcher.md) |  |  |
 |  [defaultArgs(options)](./puppeteer.puppeteer.defaultargs.md) |  |  |

src/api-docs-entry.ts

@@ -57,4 +57,5 @@ export * from './common/EvalTypes.js';
 export * from './common/PDFOptions.js';
 export * from './common/TimeoutSettings.js';
 export * from './common/LifecycleWatcher.js';
+export * from './common/QueryHandler.js';
 export * from 'devtools-protocol/types/protocol';

src/common/Puppeteer.ts

@@ -284,7 +284,18 @@ export class Puppeteer {
   }
 
   /**
-   * @internal
+   * Registers a {@link CustomQueryHandler | custom query handler}. After
+   * registration, the handler can be used everywhere where a selector is
+   * expected by prepending the selection string with `<name>/`. The name is
+   * only allowed to consist of lower- and upper case latin letters.
+   * @example
+   * ```
+   * puppeteer.registerCustomQueryHandler('text', { … });
+   * const aHandle = await page.$('text/…');
+   * ```
+   * @param name - The name that the custom query handler will be registered under.
+   * @param queryHandler - The {@link CustomQueryHandler | custom query handler} to
+   * register.
    */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_registerCustomQueryHandler(
@@ -295,23 +306,23 @@ export class Puppeteer {
   }
 
   /**
-   * @internal
+   * @param name - The name of the query handler to unregistered.
    */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_unregisterCustomQueryHandler(name: string): void {
     unregisterCustomQueryHandler(name);
   }
 
   /**
-   * @internal
+   * @returns a list with the names of all registered custom query handlers.
    */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_customQueryHandlerNames(): string[] {
     return customQueryHandlerNames();
   }
 
   /**
-   * @internal
+   * Clears all registered handlers.
    */
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_clearQueryHandlers(): void {

src/common/QueryHandler.ts

@@ -41,6 +41,17 @@ export interface InternalQueryHandler {
   ) => Promise<JSHandle>;
 }
 
+/**
+ * Contains two functions `queryOne` and `queryAll` that can
+ * be {@link Puppeteer.__experimental_registerCustomQueryHandler | registered}
+ * as alternative querying strategies. The functions `queryOne` and `queryAll`
+ * are executed in the page context.  `queryOne` should take an `Element` and a
+ * selector string as argument and return a single `Element` or `null` if no
+ * element is found. `queryAll` takes the same arguments but should instead
+ * return a `NodeListOf<Element>` or `Array<Element>` with all the elements
+ * that match the given query selector.
+ * @public
+ */
 export interface CustomQueryHandler {
   queryOne?: (element: Element | Document, selector: string) => Element | null;
   queryAll?: (
@@ -104,6 +115,9 @@ const _defaultHandler = makeQueryHandler({
 const _builtInHandlers = new Map([['aria', ariaHandler]]);
 const _queryHandlers = new Map(_builtInHandlers);
 
+/**
+ * @internal
+ */
 export function registerCustomQueryHandler(
   name: string,
   handler: CustomQueryHandler
@@ -121,24 +135,33 @@ export function registerCustomQueryHandler(
 }
 
 /**
- * @param {string} name
+ * @internal
  */
 export function unregisterCustomQueryHandler(name: string): void {
   if (_queryHandlers.has(name) && !_builtInHandlers.has(name)) {
     _queryHandlers.delete(name);
   }
 }
 
+/**
+ * @internal
+ */
 export function customQueryHandlerNames(): string[] {
   return [..._queryHandlers.keys()].filter(
     (name) => !_builtInHandlers.has(name)
   );
 }
 
+/**
+ * @internal
+ */
 export function clearCustomQueryHandlers(): void {
   customQueryHandlerNames().forEach(unregisterCustomQueryHandler);
 }
 
+/**
+ * @internal
+ */
 export function getQueryHandlerAndSelector(
   selector: string
 ): { updatedSelector: string; queryHandler: InternalQueryHandler } {