github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix!: refactor custom query handler API (#9078)

Browse Source 
This PR removes the deprecated query selector API from the `puppeteer`
instance. Direct imports of the query selector API have also been
deprecated and users are now expected to use the static methods defined
on `Puppeteer`.
This commit is contained in:
jrandolf 2022-10-10 16:01:09 +02:00 committed by GitHub
parent acbc59999b
commit 1847704789
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 150 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/api/index.md
View File

@ -52,10 +52,10 @@ sidebar_label: API
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [clearCustomQueryHandlers()](./puppeteer.clearcustomqueryhandlers.md) | Clears all registered handlers. |
| -------------------------------------------------------------------------------------- | ----------- |
| [clearCustomQueryHandlers()](./puppeteer.clearcustomqueryhandlers.md) | |
| [customQueryHandlerNames()](./puppeteer.customqueryhandlernames.md) | |
| [registerCustomQueryHandler(name, handler)](./puppeteer.registercustomqueryhandler.md) | Registers a [custom query handler](./puppeteer.customqueryhandler.md). |
| [registerCustomQueryHandler(name, handler)](./puppeteer.registercustomqueryhandler.md) | |
| [unregisterCustomQueryHandler(name)](./puppeteer.unregistercustomqueryhandler.md) | |
## Interfaces

4
docs/api/puppeteer.clearcustomqueryhandlers.md
View File

@ -4,7 +4,9 @@ sidebar_label: clearCustomQueryHandlers
# clearCustomQueryHandlers() function
Clears all registered handlers.
> Warning: This API is now obsolete.
>
> Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.clearCustomQueryHandlers()](./puppeteer.puppeteer.clearcustomqueryhandlers.md)
**Signature:**

5
docs/api/puppeteer.connect.md
View File

@ -7,6 +7,7 @@ sidebar_label: connect
**Signature:**
```typescript
connect: (options: import('./types').ConnectOptions) =>
Promise<import('./types').Browser>;
connect: (
options: import('puppeteer-core/internal/common/Puppeteer.js').ConnectOptions
) => Promise<import('./types').Browser>;
```

6
docs/api/puppeteer.customqueryhandlernames.md
View File

@ -4,6 +4,10 @@ sidebar_label: customQueryHandlerNames
# customQueryHandlerNames() function
> Warning: This API is now obsolete.
>
> Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.customQueryHandlerNames()](./puppeteer.puppeteer.customqueryhandlernames.md)
**Signature:**
```typescript
@ -13,5 +17,3 @@ export declare function customQueryHandlerNames(): string[];
**Returns:**
string\[\]
a list with the names of all registered custom query handlers.

12
docs/api/puppeteer.puppeteer.clearcustomqueryhandlers.md
View File

@ -4,24 +4,16 @@ sidebar_label: Puppeteer.clearCustomQueryHandlers
# Puppeteer.clearCustomQueryHandlers() method
> Warning: This API is now obsolete.
>
> Import directly puppeteer.
Unregisters all custom query handlers.
**Signature:**
```typescript
class Puppeteer {
clearCustomQueryHandlers(): void;
static clearCustomQueryHandlers(): void;
}
```
**Returns:**
void
## Example
```ts
import {clearCustomQueryHandlers} from 'puppeteer';
```

12
docs/api/puppeteer.puppeteer.customqueryhandlernames.md
View File

@ -4,24 +4,16 @@ sidebar_label: Puppeteer.customQueryHandlerNames
# Puppeteer.customQueryHandlerNames() method
> Warning: This API is now obsolete.
>
> Import directly puppeteer.
Gets the names of all custom query handlers.
**Signature:**
```typescript
class Puppeteer {
customQueryHandlerNames(): string[];
static customQueryHandlerNames(): string[];
}
```
**Returns:**
string\[\]
## Example
```ts
import {customQueryHandlerNames} from 'puppeteer';
```

10
docs/api/puppeteer.puppeteer.md
View File

@ -21,9 +21,9 @@ The constructor for this class is marked as internal. Third-party code should no
## Methods
| Method | Modifiers | Description |
| ----------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
| [clearCustomQueryHandlers()](./puppeteer.puppeteer.clearcustomqueryhandlers.md) | | |
| ----------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------- |
| [clearCustomQueryHandlers()](./puppeteer.puppeteer.clearcustomqueryhandlers.md) | <code>static</code> | Unregisters all custom query handlers. |
| [connect(options)](./puppeteer.puppeteer.connect.md) | | This method attaches Puppeteer to an existing browser instance. |
| [customQueryHandlerNames()](./puppeteer.puppeteer.customqueryhandlernames.md) | | |
| [registerCustomQueryHandler(name, queryHandler)](./puppeteer.puppeteer.registercustomqueryhandler.md) | | |
| [unregisterCustomQueryHandler(name)](./puppeteer.puppeteer.unregistercustomqueryhandler.md) | | |
| [customQueryHandlerNames()](./puppeteer.puppeteer.customqueryhandlernames.md) | <code>static</code> | Gets the names of all custom query handlers. |
| [registerCustomQueryHandler(name, queryHandler)](./puppeteer.puppeteer.registercustomqueryhandler.md) | <code>static</code> | Registers a [custom query handler](./puppeteer.customqueryhandler.md). |
| [unregisterCustomQueryHandler(name)](./puppeteer.puppeteer.unregistercustomqueryhandler.md) | <code>static</code> | Unregisters a custom query handler for a given name. |

21
docs/api/puppeteer.puppeteer.registercustomqueryhandler.md
View File

@ -4,15 +4,13 @@ sidebar_label: Puppeteer.registerCustomQueryHandler
# Puppeteer.registerCustomQueryHandler() method
> Warning: This API is now obsolete.
>
> Import directly puppeteer.
Registers a [custom query handler](./puppeteer.customqueryhandler.md).
**Signature:**
```typescript
class Puppeteer {
registerCustomQueryHandler(
static registerCustomQueryHandler(
name: string,
queryHandler: CustomQueryHandler
): void;
@ -22,16 +20,21 @@ class Puppeteer {
## Parameters
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------- | ----------- |
| name | string | |
| queryHandler | [CustomQueryHandler](./puppeteer.customqueryhandler.md) | |
| ------------ | ------------------------------------------------------- | -------------------------------------------------------------------------- |
| 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
## Remarks
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
```ts
import {registerCustomQueryHandler} from 'puppeteer';
```
puppeteer.registerCustomQueryHandler('text', { … });
const aHandle = await page.$('text/…');
```

12
docs/api/puppeteer.puppeteer.unregistercustomqueryhandler.md
View File

@ -4,15 +4,13 @@ sidebar_label: Puppeteer.unregisterCustomQueryHandler
# Puppeteer.unregisterCustomQueryHandler() method
> Warning: This API is now obsolete.
>
> Import directly puppeteer.
Unregisters a custom query handler for a given name.
**Signature:**
```typescript
class Puppeteer {
unregisterCustomQueryHandler(name: string): void;
static unregisterCustomQueryHandler(name: string): void;
}
```
@ -25,9 +23,3 @@ class Puppeteer {
**Returns:**
void
## Example
```ts
import {unregisterCustomQueryHandler} from 'puppeteer';
```

19
docs/api/puppeteer.registercustomqueryhandler.md
View File

@ -4,7 +4,9 @@ sidebar_label: registerCustomQueryHandler
# registerCustomQueryHandler() function
Registers a [custom query handler](./puppeteer.customqueryhandler.md).
> Warning: This API is now obsolete.
>
> Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.registerCustomQueryHandler()](./puppeteer.puppeteer.registercustomqueryhandler.md)
**Signature:**
@ -18,21 +20,10 @@ export declare function registerCustomQueryHandler(
## Parameters
| Parameter | Type | Description |
| --------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| name | string | The name that the custom query handler will be registered under. |
| --------- | ------------------------------------------------------- | ----------- |
| name | string | |
| handler | [CustomQueryHandler](./puppeteer.customqueryhandler.md) | |
**Returns:**
void
## Remarks
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/…');
```

8
docs/api/puppeteer.unregistercustomqueryhandler.md
View File

@ -4,6 +4,10 @@ sidebar_label: unregisterCustomQueryHandler
# unregisterCustomQueryHandler() function
> Warning: This API is now obsolete.
>
> Import [Puppeteer](./puppeteer.puppeteer.md) and use the static method [Puppeteer.unregisterCustomQueryHandler()](./puppeteer.puppeteer.unregistercustomqueryhandler.md)
**Signature:**
```typescript
@ -13,8 +17,8 @@ export declare function unregisterCustomQueryHandler(name: string): void;
## Parameters
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------- |
| name | string | The name of the query handler to unregistered. |
| --------- | ------ | ----------- |
| name | string | |
**Returns:**

101
packages/puppeteer-core/src/common/Puppeteer.ts
View File

@ -54,6 +54,56 @@ export interface ConnectOptions extends BrowserConnectOptions {
* @public
*/
export class Puppeteer {
/**
* Registers a {@link CustomQueryHandler | custom query handler}.
*
* @remarks
* 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.
*
* @public
*/
static registerCustomQueryHandler(
name: string,
queryHandler: CustomQueryHandler
): void {
return registerCustomQueryHandler(name, queryHandler);
}
/**
* Unregisters a custom query handler for a given name.
*/
static unregisterCustomQueryHandler(name: string): void {
return unregisterCustomQueryHandler(name);
}
/**
* Gets the names of all custom query handlers.
*/
static customQueryHandlerNames(): string[] {
return customQueryHandlerNames();
}
/**
* Unregisters all custom query handlers.
*/
static clearCustomQueryHandlers(): void {
return clearCustomQueryHandlers();
}
/**
* @internal
*/
@ -83,55 +133,4 @@ export class Puppeteer {
connect(options: ConnectOptions): Promise<Browser> {
return _connectToCDPBrowser(options);
}
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import {registerCustomQueryHandler} from 'puppeteer';
* ```
*/
registerCustomQueryHandler(
name: string,
queryHandler: CustomQueryHandler
): void {
return registerCustomQueryHandler(name, queryHandler);
}
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import {unregisterCustomQueryHandler} from 'puppeteer';
* ```
*/
unregisterCustomQueryHandler(name: string): void {
return unregisterCustomQueryHandler(name);
}
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import {customQueryHandlerNames} from 'puppeteer';
* ```
*/
customQueryHandlerNames(): string[] {
return customQueryHandlerNames();
}
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import {clearCustomQueryHandlers} from 'puppeteer';
* ```
*/
clearCustomQueryHandlers(): void {
return clearCustomQueryHandlers();
}
}

29
packages/puppeteer-core/src/common/QueryHandler.ts
View File

@ -237,24 +237,8 @@ const INTERNAL_QUERY_HANDLERS = new Map<string, RegisteredQueryHandler>([
const QUERY_HANDLERS = new Map<string, RegisteredQueryHandler>();
/**
* Registers a {@link CustomQueryHandler | custom query handler}.
*
* @remarks
* 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.
* @deprecated Import {@link Puppeteer} and use the static method
* {@link Puppeteer.registerCustomQueryHandler}
*
* @public
*/
@ -278,7 +262,8 @@ export function registerCustomQueryHandler(
}
/**
* @param name - The name of the query handler to unregistered.
* @deprecated Import {@link Puppeteer} and use the static method
* {@link Puppeteer.unregisterCustomQueryHandler}
*
* @public
*/
@ -287,7 +272,8 @@ export function unregisterCustomQueryHandler(name: string): void {
}
/**
* @returns a list with the names of all registered custom query handlers.
* @deprecated Import {@link Puppeteer} and use the static method
* {@link Puppeteer.customQueryHandlerNames}
*
* @public
*/
@ -296,7 +282,8 @@ export function customQueryHandlerNames(): string[] {
}
/**
* Clears all registered handlers.
* @deprecated Import {@link Puppeteer} and use the static method
* {@link Puppeteer.clearCustomQueryHandlers}
*
* @public
*/

5
packages/puppeteer-core/src/puppeteer-core.ts
View File

@ -18,6 +18,11 @@ export {Protocol} from 'devtools-protocol';
export * from './common/Device.js';
export * from './common/Errors.js';
export * from './common/PredefinedNetworkConditions.js';
export * from './common/Puppeteer.js';
/**
* @deprecated Use the query handler API defined on {@link Puppeteer}
*/
export * from './common/QueryHandler.js';
import {rootDirname} from './constants.js';

4
packages/puppeteer/src/puppeteer.ts
View File

@ -18,6 +18,10 @@ export {Protocol} from 'devtools-protocol';
export * from 'puppeteer-core/internal/common/Device.js';
export * from 'puppeteer-core/internal/common/Errors.js';
export * from 'puppeteer-core/internal/common/PredefinedNetworkConditions.js';
export * from 'puppeteer-core/internal/common/Puppeteer.js';
/**
* @deprecated Use the query handler API defined on {@link Puppeteer}
*/
export * from 'puppeteer-core/internal/common/QueryHandler.js';
export {BrowserFetcher} from 'puppeteer-core/internal/node/BrowserFetcher.js';
export {LaunchOptions} from 'puppeteer-core/internal/node/LaunchOptions.js';

49
test/src/elementhandle.spec.ts
View File

@ -15,14 +15,15 @@
*/
import expect from 'expect';
import sinon from 'sinon';
import {ElementHandle} from 'puppeteer-core/internal/common/ElementHandle.js';
import sinon from 'sinon';
import {
getTestState,
setupTestBrowserHooks,
setupTestPageAndContextHooks,
} from './mocha-utils.js';
import {Puppeteer} from 'puppeteer';
import utils from './utils.js';
describe('ElementHandle specs', function () {
@ -390,16 +391,15 @@ describe('ElementHandle specs', function () {
});
describe('Custom queries', function () {
this.afterEach(() => {
const {puppeteer} = getTestState();
puppeteer.clearCustomQueryHandlers();
afterEach(() => {
Puppeteer.clearCustomQueryHandlers();
});
it('should register and unregister', async () => {
const {page, puppeteer} = getTestState();
const {page} = getTestState();
await page.setContent('<div id="not-foo"></div><div id="foo"></div>');
// Register.
puppeteer.registerCustomQueryHandler('getById', {
Puppeteer.registerCustomQueryHandler('getById', {
queryOne: (_element, selector) => {
return document.querySelector(`[id="${selector}"]`);
},
@ -412,11 +412,11 @@ describe('ElementHandle specs', function () {
return element.id;
}, element)
).toBe('foo');
const handlerNamesAfterRegistering = puppeteer.customQueryHandlerNames();
const handlerNamesAfterRegistering = Puppeteer.customQueryHandlerNames();
expect(handlerNamesAfterRegistering.includes('getById')).toBeTruthy();
// Unregister.
puppeteer.unregisterCustomQueryHandler('getById');
Puppeteer.unregisterCustomQueryHandler('getById');
try {
await page.$('getById/foo');
throw new Error('Custom query handler name not set - throw expected');
@ -426,13 +426,12 @@ describe('ElementHandle specs', function () {
);
}
const handlerNamesAfterUnregistering =
puppeteer.customQueryHandlerNames();
Puppeteer.customQueryHandlerNames();
expect(handlerNamesAfterUnregistering.includes('getById')).toBeFalsy();
});
it('should throw with invalid query names', () => {
try {
const {puppeteer} = getTestState();
puppeteer.registerCustomQueryHandler('1/2/3', {
Puppeteer.registerCustomQueryHandler('1/2/3', {
queryOne: () => {
return document.querySelector('foo');
},
@ -447,11 +446,11 @@ describe('ElementHandle specs', function () {
}
});
it('should work for multiple elements', async () => {
const {page, puppeteer} = getTestState();
const {page} = getTestState();
await page.setContent(
'<div id="not-foo"></div><div class="foo">Foo1</div><div class="foo baz">Foo2</div>'
);
puppeteer.registerCustomQueryHandler('getByClass', {
Puppeteer.registerCustomQueryHandler('getByClass', {
queryAll: (_element, selector) => {
return [...document.querySelectorAll(`.${selector}`)];
},
@ -470,11 +469,11 @@ describe('ElementHandle specs', function () {
expect(classNames).toStrictEqual(['foo', 'foo baz']);
});
it('should eval correctly', async () => {
const {page, puppeteer} = getTestState();
const {page} = getTestState();
await page.setContent(
'<div id="not-foo"></div><div class="foo">Foo1</div><div class="foo baz">Foo2</div>'
);
puppeteer.registerCustomQueryHandler('getByClass', {
Puppeteer.registerCustomQueryHandler('getByClass', {
queryAll: (_element, selector) => {
return [...document.querySelectorAll(`.${selector}`)];
},
@ -486,8 +485,8 @@ describe('ElementHandle specs', function () {
expect(elements).toBe(2);
});
it('should wait correctly with waitForSelector', async () => {
const {page, puppeteer} = getTestState();
puppeteer.registerCustomQueryHandler('getByClass', {
const {page} = getTestState();
Puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return (element as Element).querySelector(`.${selector}`);
},
@ -504,8 +503,8 @@ describe('ElementHandle specs', function () {
});
it('should wait correctly with waitForSelector on an element', async () => {
const {page, puppeteer} = getTestState();
puppeteer.registerCustomQueryHandler('getByClass', {
const {page} = getTestState();
Puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return (element as Element).querySelector(`.${selector}`);
},
@ -541,8 +540,8 @@ describe('ElementHandle specs', function () {
it('should wait correctly with waitFor', async () => {
/* page.waitFor is deprecated so we silence the warning to avoid test noise */
sinon.stub(console, 'warn').callsFake(() => {});
const {page, puppeteer} = getTestState();
puppeteer.registerCustomQueryHandler('getByClass', {
const {page} = getTestState();
Puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return (element as Element).querySelector(`.${selector}`);
},
@ -558,11 +557,11 @@ describe('ElementHandle specs', function () {
expect(element).toBeDefined();
});
it('should work when both queryOne and queryAll are registered', async () => {
const {page, puppeteer} = getTestState();
const {page} = getTestState();
await page.setContent(
'<div id="not-foo"></div><div class="foo"><div id="nested-foo" class="foo"/></div><div class="foo baz">Foo2</div>'
);
puppeteer.registerCustomQueryHandler('getByClass', {
Puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return (element as Element).querySelector(`.${selector}`);
},
@ -578,11 +577,11 @@ describe('ElementHandle specs', function () {
expect(elements.length).toBe(3);
});
it('should eval when both queryOne and queryAll are registered', async () => {
const {page, puppeteer} = getTestState();
const {page} = getTestState();
await page.setContent(
'<div id="not-foo"></div><div class="foo">text</div><div class="foo baz">content</div>'
);
puppeteer.registerCustomQueryHandler('getByClass', {
Puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return (element as Element).querySelector(`.${selector}`);
},

7
test/src/queryselector.spec.ts
View File

@ -14,6 +14,7 @@
* limitations under the License.
*/
import expect from 'expect';
import {Puppeteer} from 'puppeteer';
import {CustomQueryHandler} from 'puppeteer-core/internal/common/QueryHandler.js';
import {
getTestState,
@ -397,14 +398,12 @@ describe('querySelector', function () {
},
};
before(() => {
const {puppeteer} = getTestState();
puppeteer.registerCustomQueryHandler('allArray', handler);
Puppeteer.registerCustomQueryHandler('allArray', handler);
});
it('should have registered handler', async () => {
const {puppeteer} = getTestState();
expect(
puppeteer.customQueryHandlerNames().includes('allArray')
Puppeteer.customQueryHandlerNames().includes('allArray')
).toBeTruthy();
});
it('$$ should query existing elements', async () => {