From cc7f1fd063bf73dbb40cf08059283b78aaa28516 Mon Sep 17 00:00:00 2001 From: Johan Bay Date: Wed, 7 Oct 2020 10:43:46 +0200 Subject: [PATCH] docs(queryhandler): add custom query handler docs (#6476) --- new-docs/puppeteer.customqueryhandler.md | 21 ++++++++++++ .../puppeteer.customqueryhandler.queryall.md | 11 ++++++ .../puppeteer.customqueryhandler.queryone.md | 11 ++++++ new-docs/puppeteer.md | 1 + ...eteer.__experimental_clearqueryhandlers.md | 17 ++++++++++ ....__experimental_customqueryhandlernames.md | 17 ++++++++++ ...experimental_registercustomqueryhandler.md | 34 +++++++++++++++++++ ...perimental_unregistercustomqueryhandler.md | 22 ++++++++++++ new-docs/puppeteer.puppeteer.md | 4 +++ src/api-docs-entry.ts | 1 + src/common/Puppeteer.ts | 19 ++++++++--- src/common/QueryHandler.ts | 25 +++++++++++++- 12 files changed, 178 insertions(+), 5 deletions(-) create mode 100644 new-docs/puppeteer.customqueryhandler.md create mode 100644 new-docs/puppeteer.customqueryhandler.queryall.md create mode 100644 new-docs/puppeteer.customqueryhandler.queryone.md create mode 100644 new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md create mode 100644 new-docs/puppeteer.puppeteer.__experimental_customqueryhandlernames.md create mode 100644 new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md create mode 100644 new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md diff --git a/new-docs/puppeteer.customqueryhandler.md b/new-docs/puppeteer.customqueryhandler.md new file mode 100644 index 00000000000..76b9928dba7 --- /dev/null +++ b/new-docs/puppeteer.customqueryhandler.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [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` or `Array` with all the elements that match the given query selector. + +Signature: + +```typescript +export interface CustomQueryHandler +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [queryAll](./puppeteer.customqueryhandler.queryall.md) | (element: Element \| Document, selector: string) => Element\[\] \| NodeListOf<Element> | | +| [queryOne](./puppeteer.customqueryhandler.queryone.md) | (element: Element \| Document, selector: string) => Element \| null | | + diff --git a/new-docs/puppeteer.customqueryhandler.queryall.md b/new-docs/puppeteer.customqueryhandler.queryall.md new file mode 100644 index 00000000000..c6496466909 --- /dev/null +++ b/new-docs/puppeteer.customqueryhandler.queryall.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CustomQueryHandler](./puppeteer.customqueryhandler.md) > [queryAll](./puppeteer.customqueryhandler.queryall.md) + +## CustomQueryHandler.queryAll property + +Signature: + +```typescript +queryAll?: (element: Element | Document, selector: string) => Element[] | NodeListOf; +``` diff --git a/new-docs/puppeteer.customqueryhandler.queryone.md b/new-docs/puppeteer.customqueryhandler.queryone.md new file mode 100644 index 00000000000..95c11ab102a --- /dev/null +++ b/new-docs/puppeteer.customqueryhandler.queryone.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CustomQueryHandler](./puppeteer.customqueryhandler.md) > [queryOne](./puppeteer.customqueryhandler.queryone.md) + +## CustomQueryHandler.queryOne property + +Signature: + +```typescript +queryOne?: (element: Element | Document, selector: string) => Element | null; +``` diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 40e6a85ae6f..114f66a0816 100644 --- a/new-docs/puppeteer.md +++ b/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 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. | | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) | | | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md) | | | [FrameWaitForFunctionOptions](./puppeteer.framewaitforfunctionoptions.md) | | diff --git a/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md b/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md new file mode 100644 index 00000000000..067cb971223 --- /dev/null +++ b/new-docs/puppeteer.puppeteer.__experimental_clearqueryhandlers.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_clearQueryHandlers](./puppeteer.puppeteer.__experimental_clearqueryhandlers.md) + +## Puppeteer.\_\_experimental\_clearQueryHandlers() method + +Clears all registered handlers. + +Signature: + +```typescript +__experimental_clearQueryHandlers(): void; +``` +Returns: + +void + diff --git a/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlernames.md b/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlernames.md new file mode 100644 index 00000000000..2fa5f12683b --- /dev/null +++ b/new-docs/puppeteer.puppeteer.__experimental_customqueryhandlernames.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_customQueryHandlerNames](./puppeteer.puppeteer.__experimental_customqueryhandlernames.md) + +## Puppeteer.\_\_experimental\_customQueryHandlerNames() method + +Signature: + +```typescript +__experimental_customQueryHandlerNames(): string[]; +``` +Returns: + +string\[\] + +a list with the names of all registered custom query handlers. + diff --git a/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md b/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md new file mode 100644 index 00000000000..da1dc5b092a --- /dev/null +++ b/new-docs/puppeteer.puppeteer.__experimental_registercustomqueryhandler.md @@ -0,0 +1,34 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_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 `/`. The name is only allowed to consist of lower- and upper case latin letters. + +Signature: + +```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. | + +Returns: + +void + +## Example + + +``` +puppeteer.registerCustomQueryHandler('text', { … }); +const aHandle = await page.$('text/…'); + +``` + diff --git a/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md b/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md new file mode 100644 index 00000000000..c47b2b89c87 --- /dev/null +++ b/new-docs/puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [Puppeteer](./puppeteer.puppeteer.md) > [\_\_experimental\_unregisterCustomQueryHandler](./puppeteer.puppeteer.__experimental_unregistercustomqueryhandler.md) + +## Puppeteer.\_\_experimental\_unregisterCustomQueryHandler() method + +Signature: + +```typescript +__experimental_unregisterCustomQueryHandler(name: string): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| name | string | The name of the query handler to unregistered. | + +Returns: + +void + diff --git a/new-docs/puppeteer.puppeteer.md b/new-docs/puppeteer.puppeteer.md index f5245414fa8..41259a6d9e3 100644 --- a/new-docs/puppeteer.puppeteer.md +++ b/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 <name>/. 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) | | | diff --git a/src/api-docs-entry.ts b/src/api-docs-entry.ts index 10c36e84326..848a343601c 100644 --- a/src/api-docs-entry.ts +++ b/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'; diff --git a/src/common/Puppeteer.ts b/src/common/Puppeteer.ts index 621da963fe0..503e1b5d20d 100644 --- a/src/common/Puppeteer.ts +++ b/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 `/`. 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,7 +306,7 @@ 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 { @@ -303,7 +314,7 @@ export class Puppeteer { } /** - * @internal + * @returns a list with the names of all registered custom query handlers. */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_customQueryHandlerNames(): string[] { @@ -311,7 +322,7 @@ export class Puppeteer { } /** - * @internal + * Clears all registered handlers. */ // eslint-disable-next-line @typescript-eslint/camelcase __experimental_clearQueryHandlers(): void { diff --git a/src/common/QueryHandler.ts b/src/common/QueryHandler.ts index 1706ea77b93..71386683724 100644 --- a/src/common/QueryHandler.ts +++ b/src/common/QueryHandler.ts @@ -41,6 +41,17 @@ export interface InternalQueryHandler { ) => Promise; } +/** + * 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` or `Array` 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,7 +135,7 @@ export function registerCustomQueryHandler( } /** - * @param {string} name + * @internal */ export function unregisterCustomQueryHandler(name: string): void { if (_queryHandlers.has(name) && !_builtInHandlers.has(name)) { @@ -129,16 +143,25 @@ export function unregisterCustomQueryHandler(name: string): void { } } +/** + * @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 } {