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

chore: add custom rule for formatting comments (#8777)

Browse Source
This commit is contained in:
jrandolf 2022-08-12 14:15:26 +02:00 committed by GitHub
parent 73221042db
commit ddbe88b887
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
48 changed files with 2613 additions and 2318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
.eslintplugin.js Normal file
View File

@ -0,0 +1,95 @@
const prettier = require('prettier');
const cleanupBlockComment = value => {
return value
.trim()
.split('\n')
.map(value => {
value = value.trim();
if (value.startsWith('*')) {
value = value.slice(1);
if (value.startsWith(' ')) {
value = value.slice(1);
}
}
return value.trimEnd();
})
.join('\n')
.trim();
};
const format = (value, offset, prettierOptions) => {
return prettier
.format(value, {
...prettierOptions,
// This is the print width minus 3 (the length of ` * `) and the offset.
printWidth: prettierOptions.printWidth - (offset + 3),
})
.trim();
};
const buildBlockComment = (value, offset) => {
const spaces = ' '.repeat(offset);
const lines = value.split('\n').map(line => {
return ` * ${line}`;
});
lines.unshift('/**');
lines.push(' */');
lines.forEach((line, i) => {
lines[i] = `${spaces}${line}`;
});
return lines.join('\n');
};
/**
* @type import("eslint").Rule.RuleModule
*/
const rule = {
meta: {
type: 'suggestion',
docs: {
description: 'Enforce Prettier formatting on comments',
recommended: false,
},
fixable: 'code',
schema: [],
messages: {},
},
create(context) {
const prettierOptions = {
printWidth: 80,
...prettier.resolveConfig.sync(context.getPhysicalFilename()),
parser: 'markdown',
};
for (const comment of context.getSourceCode().getAllComments()) {
switch (comment.type) {
case 'Block': {
const offset = comment.loc.start.column;
const value = cleanupBlockComment(comment.value);
const formattedValue = format(value, offset, prettierOptions);
if (formattedValue !== value) {
context.report({
node: comment,
message: `Comment is not formatted correctly.`,
fix(fixer) {
return fixer.replaceText(
comment,
buildBlockComment(formattedValue, offset).trimStart()
);
},
});
}
break;
}
}
}
return {};
},
};
module.exports = {
rules: {
'prettier-comments': rule,
},
};

16
.eslintrc.js
View File

@ -1,12 +1,3 @@
// TODO: Enable this at some point.
// const RESTRICTED_UNDERSCORED_IDENTIFIERS = [
// 'PropertyDefinition > Identifier[name=/^_[a-z].*$/]',
// ].map((selector) => ({
// selector,
// message:
// 'Use private fields (fields prefixed with #) and an appropriate getter/setter.',
// }));
module.exports = {
root: true,
env: {
@ -132,8 +123,10 @@ module.exports = {
'plugin:@typescript-eslint/eslint-recommended',
'plugin:@typescript-eslint/recommended',
],
plugins: ['eslint-plugin-tsdoc'],
plugins: ['eslint-plugin-tsdoc', 'local'],
rules: {
// Keeps comments formatted.
'local/prettier-comments': 2,
// Brackets keep code readable.
curly: [2, 'all'],
// Brackets keep code readable and `return` intentions clear.
@ -189,9 +182,6 @@ module.exports = {
selector: "CallExpression[callee.name='require']",
message: '`require` statements are not allowed. Use `import`.',
},
// Don't allow underscored declarations on camelCased variables/properties.
// ...RESTRICTED_UNDERSCORED_IDENTIFIERS,
],
},
},

2
docs/api/puppeteer.accessibility.snapshot.md
View File

@ -28,7 +28,7 @@ An AXNode object representing the snapshot.
## Remarks
\*\*NOTE\*\* The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers. Puppeteer will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
**NOTE** The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers. Puppeteer will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
## Example 1

2
docs/api/puppeteer.browserfetcher.md
View File

@ -30,7 +30,7 @@ const browser = await puppeteer.launch({
});
```
\*\*NOTE\*\* BrowserFetcher is not designed to work concurrently with other instances of BrowserFetcher that share the same downloads directory.
**NOTE** BrowserFetcher is not designed to work concurrently with other instances of BrowserFetcher that share the same downloads directory.
## Methods

2
docs/api/puppeteer.elementhandle.press.md
View File

@ -29,4 +29,4 @@ Promise<void>
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
\*\*NOTE\*\* Modifier keys DO affect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
**NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift` will type the text in upper case.

2
docs/api/puppeteer.jshandle.jsonvalue.md
View File

@ -24,4 +24,4 @@ Throws if the object cannot be serialized due to circularity.
## Remarks
If the object has a `toJSON` function, it \*will not\* be called.
If the object has a `toJSON` function, it **will not** be called.

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

@ -31,7 +31,7 @@ await page.mouse.move(0, 0);
await page.mouse.up();
```
\*\*Note\*\*: The mouse events trigger synthetic `MouseEvent`s. This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse.
**Note**: The mouse events trigger synthetic `MouseEvent`s. This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse.
For example, dragging and selecting text is not possible using `page.mouse`. Instead, you can use the [\`DocumentOrShadowRoot.getSelection()\`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection) functionality implemented in the platform.
@ -67,7 +67,7 @@ await page.evaluate(() => {
});
```
\*\*Note\*\*: If you want access to the clipboard API, you have to give it permission to do so:
**Note**: If you want access to the clipboard API, you have to give it permission to do so:
```ts
await browser

4
docs/api/puppeteer.page.goto.md
View File

@ -40,7 +40,9 @@ The argument `options` might have the following properties:
- `referer` : Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders()](./puppeteer.page.setextrahttpheaders.md).
`page.goto` will throw an error if: - there's an SSL error (e.g. in case of self-signed certificates). - target URL is invalid. - the timeout is exceeded during navigation. - the remote server does not respond or is unreachable. - the main resource failed to load.
`page.goto` will throw an error if:
- there's an SSL error (e.g. in case of self-signed certificates). - target URL is invalid. - the timeout is exceeded during navigation. - the remote server does not respond or is unreachable. - the main resource failed to load.
`page.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling response.status().

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

@ -26,11 +26,11 @@ class Page {
## Parameters
| Parameter | Type | Description |
| ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pageFunction | Func \| string | Function to be evaluated in browser context |
| options | { timeout?: number; polling?: string \| number; } | <i>(Optional)</i> Optional waiting parameters - <code>polling</code> - An interval at which the <code>pageFunction</code> is executed, defaults to <code>raf</code>. If <code>polling</code> is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: - <code>raf</code> - to constantly execute <code>pageFunction</code> in <code>requestAnimationFrame</code> callback. This is the tightest polling mode which is suitable to observe styling changes. - <code>mutation</code>- to execute pageFunction on every DOM mutation. - <code>timeout</code> - maximum time to wait for in milliseconds. Defaults to <code>30000</code> (30 seconds). Pass <code>0</code> to disable timeout. The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method. |
| args | Params | Arguments to pass to <code>pageFunction</code> |
| Parameter | Type | Description |
| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pageFunction | Func \| string | Function to be evaluated in browser context |
| options | { timeout?: number; polling?: string \| number; } | <p><i>(Optional)</i> Optional waiting parameters</p><p>- <code>polling</code> - An interval at which the <code>pageFunction</code> is executed, defaults to <code>raf</code>. If <code>polling</code> is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: - <code>raf</code> - to constantly execute <code>pageFunction</code> in <code>requestAnimationFrame</code> callback. This is the tightest polling mode which is suitable to observe styling changes. - <code>mutation</code>- to execute pageFunction on every DOM mutation. - <code>timeout</code> - maximum time to wait for in milliseconds. Defaults to <code>30000</code> (30 seconds). Pass <code>0</code> to disable timeout. The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method.</p> |
| args | Params | Arguments to pass to <code>pageFunction</code> |
**Returns:**

4
docs/api/puppeteer.page.waitfornavigation.md
View File

@ -24,7 +24,9 @@ class Page {
Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;
A `Promise` which resolves to the main resource response. - In case of multiple redirects, the navigation will resolve with the response of the last redirect. - In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
A `Promise` which resolves to the main resource response.
- In case of multiple redirects, the navigation will resolve with the response of the last redirect. - In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
## Remarks

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

@ -19,7 +19,9 @@ export declare type PaperFormat =
## Remarks
The sizes of each format are as follows: - `Letter`: 8.5in x 11in
The sizes of each format are as follows:
- `Letter`: 8.5in x 11in
- `Legal`: 8.5in x 14in

4
docs/api/puppeteer.pdfoptions.headertemplate.md
View File

@ -4,7 +4,9 @@ sidebar_label: PDFOptions.headerTemplate
# PDFOptions.headerTemplate property
HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date
HTML template for the print header. Should be valid HTML with the following classes used to inject values into them:
- `date` formatted print date
- `title` document title

34
docs/api/puppeteer.pdfoptions.md
View File

@ -14,20 +14,20 @@ export interface PDFOptions
## Properties
| Property | Modifiers | Type | Description |
| --------------------------------------------------------------------- | --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [displayHeaderFooter?](./puppeteer.pdfoptions.displayheaderfooter.md) | | boolean | <i>(Optional)</i> Whether to show the header and footer. |
| [footerTemplate?](./puppeteer.pdfoptions.footertemplate.md) | | string | <i>(Optional)</i> HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md). |
| [format?](./puppeteer.pdfoptions.format.md) | | [PaperFormat](./puppeteer.paperformat.md) | <i>(Optional)</i> |
| [headerTemplate?](./puppeteer.pdfoptions.headertemplate.md) | | string | <p><i>(Optional)</i> HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - <code>date</code> formatted print date</p><p>- <code>title</code> document title</p><p>- <code>url</code> document location</p><p>- <code>pageNumber</code> current page number</p><p>- <code>totalPages</code> total pages in the document</p> |
| [height?](./puppeteer.pdfoptions.height.md) | | string \| number | <i>(Optional)</i> Sets the height of paper. You can pass in a number or a string with a unit. |
| [landscape?](./puppeteer.pdfoptions.landscape.md) | | boolean | <i>(Optional)</i> Whether to print in landscape orientation. |
| [margin?](./puppeteer.pdfoptions.margin.md) | | [PDFMargin](./puppeteer.pdfmargin.md) | <i>(Optional)</i> Set the PDF margins. |
| [omitBackground?](./puppeteer.pdfoptions.omitbackground.md) | | boolean | <i>(Optional)</i> Hides default white background and allows generating pdfs with transparency. |
| [pageRanges?](./puppeteer.pdfoptions.pageranges.md) | | string | <i>(Optional)</i> Paper ranges to print, e.g. <code>1-5, 8, 11-13</code>. |
| [path?](./puppeteer.pdfoptions.path.md) | | string | <i>(Optional)</i> The path to save the file to. |
| [preferCSSPageSize?](./puppeteer.pdfoptions.prefercsspagesize.md) | | boolean | <i>(Optional)</i> Give any CSS <code>@page</code> size declared in the page priority over what is declared in the <code>width</code> or <code>height</code> or <code>format</code> option. |
| [printBackground?](./puppeteer.pdfoptions.printbackground.md) | | boolean | <i>(Optional)</i> Set to <code>true</code> to print background graphics. |
| [scale?](./puppeteer.pdfoptions.scale.md) | | number | <i>(Optional)</i> Scales the rendering of the web page. Amount must be between <code>0.1</code> and <code>2</code>. |
| [timeout?](./puppeteer.pdfoptions.timeout.md) | | number | <i>(Optional)</i> Timeout in milliseconds |
| [width?](./puppeteer.pdfoptions.width.md) | | string \| number | <i>(Optional)</i> Sets the width of paper. You can pass in a number or a string with a unit. |
| Property | Modifiers | Type | Description |
| --------------------------------------------------------------------- | --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [displayHeaderFooter?](./puppeteer.pdfoptions.displayheaderfooter.md) | | boolean | <i>(Optional)</i> Whether to show the header and footer. |
| [footerTemplate?](./puppeteer.pdfoptions.footertemplate.md) | | string | <i>(Optional)</i> HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md). |
| [format?](./puppeteer.pdfoptions.format.md) | | [PaperFormat](./puppeteer.paperformat.md) | <i>(Optional)</i> |
| [headerTemplate?](./puppeteer.pdfoptions.headertemplate.md) | | string | <p><i>(Optional)</i> HTML template for the print header. Should be valid HTML with the following classes used to inject values into them:</p><p>- <code>date</code> formatted print date</p><p>- <code>title</code> document title</p><p>- <code>url</code> document location</p><p>- <code>pageNumber</code> current page number</p><p>- <code>totalPages</code> total pages in the document</p> |
| [height?](./puppeteer.pdfoptions.height.md) | | string \| number | <i>(Optional)</i> Sets the height of paper. You can pass in a number or a string with a unit. |
| [landscape?](./puppeteer.pdfoptions.landscape.md) | | boolean | <i>(Optional)</i> Whether to print in landscape orientation. |
| [margin?](./puppeteer.pdfoptions.margin.md) | | [PDFMargin](./puppeteer.pdfmargin.md) | <i>(Optional)</i> Set the PDF margins. |
| [omitBackground?](./puppeteer.pdfoptions.omitbackground.md) | | boolean | <i>(Optional)</i> Hides default white background and allows generating pdfs with transparency. |
| [pageRanges?](./puppeteer.pdfoptions.pageranges.md) | | string | <i>(Optional)</i> Paper ranges to print, e.g. <code>1-5, 8, 11-13</code>. |
| [path?](./puppeteer.pdfoptions.path.md) | | string | <i>(Optional)</i> The path to save the file to. |
| [preferCSSPageSize?](./puppeteer.pdfoptions.prefercsspagesize.md) | | boolean | <i>(Optional)</i> Give any CSS <code>@page</code> size declared in the page priority over what is declared in the <code>width</code> or <code>height</code> or <code>format</code> option. |
| [printBackground?](./puppeteer.pdfoptions.printbackground.md) | | boolean | <i>(Optional)</i> Set to <code>true</code> to print background graphics. |
| [scale?](./puppeteer.pdfoptions.scale.md) | | number | <i>(Optional)</i> Scales the rendering of the web page. Amount must be between <code>0.1</code> and <code>2</code>. |
| [timeout?](./puppeteer.pdfoptions.timeout.md) | | number | <i>(Optional)</i> Timeout in milliseconds |
| [width?](./puppeteer.pdfoptions.width.md) | | string \| number | <i>(Optional)</i> Sets the width of paper. You can pass in a number or a string with a unit. |

2
docs/api/puppeteer.puppeteernode.executablepath.md
View File

@ -26,4 +26,4 @@ A path where Puppeteer expects to find the bundled browser. The browser binary m
## Remarks
\*\*NOTE\*\* `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` environment variables.
**NOTE** `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` environment variables.

2
docs/api/puppeteer.puppeteernode.launch.md
View File

@ -28,7 +28,7 @@ Promise which resolves to browser instance.
## Remarks
\*\*NOTE\*\* Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
**NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
## Example

13
package-lock.json generated
View File

@ -54,6 +54,7 @@
"eslint-config-prettier": "8.5.0",
"eslint-formatter-codeframe": "7.32.1",
"eslint-plugin-import": "2.26.0",
"eslint-plugin-local": "^1.0.0",
"eslint-plugin-mocha": "10.1.0",
"eslint-plugin-prettier": "4.2.1",
"eslint-plugin-tsdoc": "0.2.16",
@ -2624,6 +2625,12 @@
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/eslint-plugin-local": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/eslint-plugin-local/-/eslint-plugin-local-1.0.0.tgz",
"integrity": "sha512-bcwcQnKL/Iw5Vi/F2lG1he5oKD2OGjhsLmrcctkWrWq5TujgiaYb0cj3pZgr3XI54inNVnneOFdAx1daLoYLJQ==",
"dev": true
},
"node_modules/eslint-plugin-mocha": {
"version": "10.1.0",
"resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.1.0.tgz",
@ -9061,6 +9068,12 @@
}
}
},
"eslint-plugin-local": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/eslint-plugin-local/-/eslint-plugin-local-1.0.0.tgz",
"integrity": "sha512-bcwcQnKL/Iw5Vi/F2lG1he5oKD2OGjhsLmrcctkWrWq5TujgiaYb0cj3pZgr3XI54inNVnneOFdAx1daLoYLJQ==",
"dev": true
},
"eslint-plugin-mocha": {
"version": "10.1.0",
"resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-10.1.0.tgz",

1
package.json
View File

@ -113,6 +113,7 @@
"eslint-config-prettier": "8.5.0",
"eslint-formatter-codeframe": "7.32.1",
"eslint-plugin-import": "2.26.0",
"eslint-plugin-local": "1.0.0",
"eslint-plugin-mocha": "10.1.0",
"eslint-plugin-prettier": "4.2.1",
"eslint-plugin-tsdoc": "0.2.16",

5
src/common/Accessibility.ts
View File

@ -152,6 +152,7 @@ export class Accessibility {
*
* @example
* An example of dumping the entire accessibility tree:
*
* ```ts
* const snapshot = await page.accessibility.snapshot();
* console.log(snapshot);
@ -159,14 +160,14 @@ export class Accessibility {
*
* @example
* An example of logging the focused node's name:
*
* ```ts
* const snapshot = await page.accessibility.snapshot();
* const node = findFocusedNode(snapshot);
* console.log(node && node.name);
*
* function findFocusedNode(node) {
* if (node.focused)
* return node;
* if (node.focused) return node;
* for (const child of node.children || []) {
* const foundNode = findFocusedNode(child);
* return foundNode;

3
src/common/AriaQueryHandler.ts
View File

@ -59,11 +59,12 @@ function isKnownAttribute(
return knownAttributes.has(attribute);
}
/*
/**
* The selectors consist of an accessible name to query for and optionally
* further aria attributes on the form `[<attribute>=<value>]`.
* Currently, we only support the `name` and `role` attribute.
* The following examples showcase how the syntax works wrt. querying:
*
* - 'title[role="heading"]' queries for elements with name 'title' and role 'heading'.
* - '[role="img"]' queries for elements with role 'img' and any name.
* - 'label' queries for elements with name 'label' and any role.

25
src/common/Browser.ts
View File

@ -181,8 +181,8 @@ export const enum BrowserEmittedEvents {
* emit various events which are documented in the {@link BrowserEmittedEvents} enum.
*
* @example
*
* An example of using a {@link Browser} to create a {@link Page}:
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -195,8 +195,8 @@ export const enum BrowserEmittedEvents {
* ```
*
* @example
*
* An example of disconnecting from and reconnecting to a {@link Browser}:
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -411,9 +411,10 @@ export class Browser extends EventEmitter {
* browser contexts.
*
* @example
*
* ```ts
* (async () => {
* const browser = await puppeteer.launch();
* const browser = await puppeteer.launch();
* // Create a new incognito browser context.
* const context = await browser.createIncognitoBrowserContext();
* // Create a new page in a pristine context.
@ -631,9 +632,12 @@ export class Browser extends EventEmitter {
* @example
*
* An example of finding a target for a page opened via `window.open`:
*
* ```ts
* await page.evaluate(() => window.open('https://www.example.com/'));
* const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');
* const newWindowTarget = await browser.waitForTarget(
* target => target.url() === 'https://www.example.com/'
* );
* ```
*/
async waitForTarget(
@ -788,6 +792,7 @@ export const enum BrowserContextEmittedEvents {
* method. "Incognito" browser contexts don't write any browsing data to disk.
*
* @example
*
* ```ts
* // Create a new incognito browser context
* const context = await browser.createIncognitoBrowserContext();
@ -798,6 +803,7 @@ export const enum BrowserContextEmittedEvents {
* // Dispose context once it's no longer needed.
* await context.close();
* ```
*
* @public
*/
export class BrowserContext extends EventEmitter {
@ -829,9 +835,12 @@ export class BrowserContext extends EventEmitter {
*
* @example
* An example of finding a target for a page opened via `window.open`:
*
* ```ts
* await page.evaluate(() => window.open('https://www.example.com/'));
* const newWindowTarget = await browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');
* const newWindowTarget = await browserContext.waitForTarget(
* target => target.url() === 'https://www.example.com/'
* );
* ```
*
* @param predicate - A function to be run for every target
@ -891,9 +900,12 @@ export class BrowserContext extends EventEmitter {
/**
* @example
*
* ```ts
* const context = browser.defaultBrowserContext();
* await context.overridePermissions('https://html5demos.com', ['geolocation']);
* await context.overridePermissions('https://html5demos.com', [
* 'geolocation',
* ]);
* ```
*
* @param origin - The origin to grant permissions to, e.g. "https://example.com".
@ -923,6 +935,7 @@ export class BrowserContext extends EventEmitter {
* Clears all permission overrides for the browser context.
*
* @example
*
* ```ts
* const context = browser.defaultBrowserContext();
* context.overridePermissions('https://example.com', ['clipboard-read']);

7
src/common/Connection.ts
View File

@ -280,14 +280,17 @@ export const CDPSessionEmittedEvents = {
* and {@link https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md | Getting Started with DevTools Protocol}.
*
* @example
*
* ```ts
* const client = await page.target().createCDPSession();
* await client.send('Animation.enable');
* client.on('Animation.animationCreated', () => console.log('Animation created!'));
* client.on('Animation.animationCreated', () =>
* console.log('Animation created!')
* );
* const response = await client.send('Animation.getPlaybackRate');
* console.log('playback rate is ' + response.playbackRate);
* await client.send('Animation.setPlaybackRate', {
* playbackRate: response.playbackRate / 2
* playbackRate: response.playbackRate / 2,
* });
* ```
*

9
src/common/Coverage.ts
View File

@ -98,11 +98,12 @@ export interface CSSCoverageOptions {
* @example
* An example of using JavaScript and CSS coverage to get percentage of initially
* executed code:
*
* ```ts
* // Enable both JavaScript and CSS coverage
* await Promise.all([
* page.coverage.startJSCoverage(),
* page.coverage.startCSSCoverage()
* page.coverage.startCSSCoverage(),
* ]);
* // Navigate to page
* await page.goto('https://example.com');
@ -116,11 +117,11 @@ export interface CSSCoverageOptions {
* const coverage = [...jsCoverage, ...cssCoverage];
* for (const entry of coverage) {
* totalBytes += entry.text.length;
* for (const range of entry.ranges)
* usedBytes += range.end - range.start - 1;
* for (const range of entry.ranges) usedBytes += range.end - range.start - 1;
* }
* console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
* console.log(`Bytes used: ${(usedBytes / totalBytes) * 100}%`);
* ```
*
* @public
*/
export class Coverage {

1
src/common/Debug.ts
View File

@ -60,6 +60,7 @@ export async function importDebug(): Promise<typeof import('debug')> {
* ```
*
* @example
*
* ```
* const log = debug('Page');
*

2
src/common/Dialog.ts
View File

@ -24,6 +24,7 @@ import {Protocol} from 'devtools-protocol';
* @remarks
*
* @example
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -38,6 +39,7 @@ import {Protocol} from 'devtools-protocol';
* page.evaluate(() => alert('1'));
* })();
* ```
*
* @public
*/
export class Dialog {

91
src/common/ElementHandle.ts
View File

@ -43,12 +43,12 @@ const applyOffsetsToQuad = (
* const puppeteer = require('puppeteer');
*
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* await page.goto('https://example.com');
* const hrefElement = await page.$('a');
* await hrefElement.click();
* // ...
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* await page.goto('https://example.com');
* const hrefElement = await page.$('a');
* await hrefElement.click();
* // ...
* })();
* ```
*
@ -142,10 +142,15 @@ export class ElementHandle<
* the promise resolves.
*
* @example
*
* ```ts
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe(
* '100'
* );
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe(
* '10'
* );
* ```
*
* @param selector - The selector to query for.
@ -186,17 +191,21 @@ export class ElementHandle<
*
* @example
* HTML:
*
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* JavaScript:
*
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText)))
* .toEqual(['Hello!', 'Hi!']);
* expect(
* await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))
* ).toEqual(['Hello!', 'Hi!']);
* ```
*
* @param selector - The selector to query for.
@ -251,6 +260,7 @@ export class ElementHandle<
* navigations or if the element is detached from DOM.
*
* @example
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -258,16 +268,22 @@ export class ElementHandle<
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page.mainFrame()
* .waitForSelector('img')
* .then(() => console.log('First URL with image: ' + currentURL));
* page
* .mainFrame()
* .waitForSelector('img')
* .then(() => console.log('First URL with image: ' + currentURL));
*
* for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* })();
* ```
*
* @param selector - The selector to query and wait for.
* @param options - Options for customizing waiting behavior.
* @returns An element matching the given selector.
@ -311,25 +327,27 @@ export class ElementHandle<
* automatically.
*
* This method works across navigation
*
* ```ts
* const puppeteer = require('puppeteer');
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page
* .waitForXPath('//img')
* .then(() => console.log('First URL with image: ' + currentURL));
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page
* .waitForXPath('//img')
* .then(() => console.log('First URL with image: ' + currentURL));
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* })();
* ```
*
* @param xpath - A
* {@link https://developer.mozilla.org/en-US/docs/Web/XPath | xpath} of an
* element to wait for
@ -665,13 +683,15 @@ export class ElementHandle<
* throws an error.
*
* @example
*
* ```ts
* handle.select('blue'); // single selection
* handle.select('red', 'green', 'blue'); // multiple selections
* ```
*
* @param values - Values of options to select. If the `<select>` has the
* `multiple` attribute, all values are considered, otherwise only the first
* one is taken into account.
* `multiple` attribute, all values are considered, otherwise only the first
* one is taken into account.
*/
async select(...values: string[]): Promise<string[]> {
for (const value of values) {
@ -722,10 +742,10 @@ export class ElementHandle<
* {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element}.
*
* @param filePaths - Sets the value of the file input to these paths.
* If a path is relative, then it is resolved against the
* {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}.
* Note for locals script connecting to remote chrome environments,
* paths must be absolute.
* If a path is relative, then it is resolved against the
* {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}.
* Note for locals script connecting to remote chrome environments,
* paths must be absolute.
*/
async uploadFile(
this: ElementHandle<HTMLInputElement>,
@ -814,6 +834,7 @@ export class ElementHandle<
* use {@link ElementHandle.press}.
*
* @example
*
* ```ts
* await elementHandle.type('Hello'); // Types instantly
* await elementHandle.type('World', {delay: 100}); // Types slower, like a user
@ -845,7 +866,7 @@ export class ElementHandle<
* will type the text in upper case.
*
* @param key - Name of key to press, such as `ArrowLeft`.
* See {@link KeyInput} for a list of all key names.
* See {@link KeyInput} for a list of all key names.
*/
async press(key: KeyInput, options?: PressOptions): Promise<void> {
await this.focus();

1
src/common/Errors.ts
View File

@ -65,6 +65,7 @@ export interface PuppeteerErrors {
*
* @example
* An example of handling a timeout error:
*
* ```ts
* try {
* await page.waitForSelector('.foo');

4
src/common/EventEmitter.ts
View File

@ -54,7 +54,7 @@ export class EventEmitter implements CommonEventEmitter {
/**
* Bind an event listener to fire when an event occurs.
* @param event - the event type you'd like to listen to. Can be a string or symbol.
* @param handler - the function to be called when the event occurs.
* @param handler - the function to be called when the event occurs.
* @returns `this` to enable you to chain method calls.
*/
on(event: EventType, handler: Handler): EventEmitter {
@ -65,7 +65,7 @@ export class EventEmitter implements CommonEventEmitter {
/**
* Remove an event listener from firing.
* @param event - the event type you'd like to stop listening to.
* @param handler - the function that should be removed.
* @param handler - the function that should be removed.
* @returns `this` to enable you to chain method calls.
*/
off(event: EventType, handler: Handler): EventEmitter {

24
src/common/ExecutionContext.ts
View File

@ -102,6 +102,7 @@ export class ExecutionContext {
* Evaluates the given function.
*
* @example
*
* ```ts
* const executionContext = await page.mainFrame().executionContext();
* const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ;
@ -110,17 +111,21 @@ export class ExecutionContext {
*
* @example
* A string can also be passed in instead of a function:
*
* ```ts
* console.log(await executionContext.evaluate('1 + 2')); // prints "3"
* ```
*
* @example
* Handles can also be passed as `args`. They resolve to their referenced object:
*
* ```ts
* const oneHandle = await executionContext.evaluateHandle(() => 1);
* const twoHandle = await executionContext.evaluateHandle(() => 2);
* const result = await executionContext.evaluate(
* (a, b) => a + b, oneHandle, twoHandle
* (a, b) => a + b,
* oneHandle,
* twoHandle
* );
* await oneHandle.dispose();
* await twoHandle.dispose();
@ -153,27 +158,29 @@ export class ExecutionContext {
* `Map`) and requires further manipulation.
*
* @example
*
* ```ts
* const context = await page.mainFrame().executionContext();
* const handle: JSHandle<typeof globalThis> = await context.evaluateHandle(() =>
* Promise.resolve(self)
* const handle: JSHandle<typeof globalThis> = await context.evaluateHandle(
* () => Promise.resolve(self)
* );
* ```
*
* @example
* A string can also be passed in instead of a function.
*
* ```ts
* const handle: JSHandle<number> = await context.evaluateHandle('1 + 2');
* ```
*
* @example
* Handles can also be passed as `args`. They resolve to their referenced object:
*
* ```ts
* const bodyHandle: ElementHandle<HTMLBodyElement> = await context.evaluateHandle(
* () => {
* const bodyHandle: ElementHandle<HTMLBodyElement> =
* await context.evaluateHandle(() => {
* return document.body;
* }
* );
* });
* const stringHandle: JSHandle<string> = await context.evaluateHandle(
* body => body.innerHTML,
* body
@ -372,9 +379,10 @@ export class ExecutionContext {
* given prototype.
*
* @example
*
* ```ts
* // Create a Map object
* await page.evaluate(() => window.map = new Map());
* await page.evaluate(() => (window.map = new Map()));
* // Get a handle to the Map object prototype
* const mapPrototype = await page.evaluateHandle(() => Map.prototype);
* // Query all map instances into an array

3
src/common/FileChooser.ts
View File

@ -29,6 +29,7 @@ import {ElementHandle} from './ElementHandle.js';
* subsequent file choosers from appearing.
*
* @example
*
* ```ts
* const [fileChooser] = await Promise.all([
* page.waitForFileChooser(),
@ -67,7 +68,7 @@ export class FileChooser {
/**
* Accept the file chooser request with given paths.
*
* @param filePaths - If some of the `filePaths` are relative paths, then
* @param filePaths - If some of the `filePaths` are relative paths, then
* they are resolved relative to the
* {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}.
*/

3
src/common/FirefoxTargetManager.ts
View File

@ -36,9 +36,10 @@ import {EventEmitter} from './EventEmitter.js';
* because Firefox's CDP implementation does not support auto-attach.
*
* Firefox does not support targetInfoChanged and detachedFromTarget events:
*
* - https://bugzilla.mozilla.org/show_bug.cgi?id=1610855
* - https://bugzilla.mozilla.org/show_bug.cgi?id=1636979
* @internal
* @internal
*/
export class FirefoxTargetManager
extends EventEmitter

29
src/common/FrameManager.ts
View File

@ -630,7 +630,7 @@ export interface FrameAddStyleTagOptions {
* function dumpFrameTree(frame, indent) {
* console.log(indent + frame.url());
* for (const child of frame.childFrames()) {
* dumpFrameTree(child, indent + ' ');
* dumpFrameTree(child, indent + ' ');
* }
* }
* })();
@ -780,7 +780,7 @@ export class Frame {
*
* This method will not throw an error when any valid HTTP status code is
* returned by the remote server, including 404 "Not Found" and 500 "Internal
* Server Error". The status code for such responses can be retrieved by
* Server Error". The status code for such responses can be retrieved by
* calling {@link HTTPResponse.status}.
*/
async goto(
@ -861,6 +861,7 @@ export class Frame {
* to change the URL is considered a navigation.
*
* @example
*
* ```ts
* const [response] = await Promise.all([
* // The navigation promise resolves after navigation has finished
@ -988,6 +989,7 @@ export class Frame {
* the promise resolves.
*
* @example
*
* ```ts
* const searchValue = await frame.$eval('#search', el => el.value);
* ```
@ -1021,6 +1023,7 @@ export class Frame {
* the promise resolves.
*
* @example
*
* ```js
* const divsCounts = await frame.$$eval('div', divs => divs.length);
* ```
@ -1062,6 +1065,7 @@ export class Frame {
* This method works across navigations.
*
* @example
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -1069,16 +1073,22 @@ export class Frame {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* let currentURL;
* page.mainFrame()
* .waitForSelector('img')
* .then(() => console.log('First URL with image: ' + currentURL));
* page
* .mainFrame()
* .waitForSelector('img')
* .then(() => console.log('First URL with image: ' + currentURL));
*
* for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
* for (currentURL of [
* 'https://example.com',
* 'https://google.com',
* 'https://bbc.com',
* ]) {
* await page.goto(currentURL);
* }
* await browser.close();
* })();
* ```
*
* @param selector - The selector to query and wait for.
* @param options - Options for customizing waiting behavior.
* @returns An element matching the given selector.
@ -1115,7 +1125,7 @@ export class Frame {
* an XPath.
*
* @param xpath - the XPath expression to wait for.
* @param options - options to configure the visiblity of the element and how
* @param options - options to configure the visiblity of the element and how
* long to wait before timing out.
*/
async waitForXPath(
@ -1131,6 +1141,7 @@ export class Frame {
/**
* @example
* The `waitForFunction` can be used to observe viewport size change:
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -1152,7 +1163,7 @@ export class Frame {
* selector => !!document.querySelector(selector),
* {}, // empty options object
* selector
*);
* );
* ```
*
* @param pageFunction - the function to evaluate in the frame context.
@ -1326,6 +1337,7 @@ export class Frame {
* `selector`.
*
* @example
*
* ```ts
* frame.select('select#colors', 'blue'); // single selection
* frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections
@ -1361,6 +1373,7 @@ export class Frame {
* {@link Keyboard.press}.
*
* @example
*
* ```ts
* await frame.type('#mytextarea', 'Hello'); // Types instantly
* await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user

19
src/common/HTTPRequest.ts
View File

@ -80,14 +80,13 @@ interface CDPSession extends EventEmitter {
}
/**
*
* Represents an HTTP request sent by a page.
* @remarks
*
* Whenever the page sends a request, such as for a network resource, the
* following events are emitted by Puppeteer's `page`:
*
* - `request`: emitted when the request is issued by the page.
* - `request`: emitted when the request is issued by the page.
* - `requestfinished` - emitted when the response body is downloaded and the
* request is complete.
*
@ -234,14 +233,14 @@ export class HTTPRequest {
/**
* @returns An InterceptResolutionState object describing the current resolution
* action and priority.
* action and priority.
*
* InterceptResolutionState contains:
* action: InterceptResolutionAction
* priority?: number
* InterceptResolutionState contains:
* action: InterceptResolutionAction
* priority?: number
*
* InterceptResolutionAction is one of: `abort`, `respond`, `continue`,
* `disabled`, `none`, or `already-handled`.
* InterceptResolutionAction is one of: `abort`, `respond`, `continue`,
* `disabled`, `none`, or `already-handled`.
*/
interceptResolutionState(): InterceptResolutionState {
if (!this.#allowInterception) {
@ -426,6 +425,7 @@ export class HTTPRequest {
* Exception is immediately thrown if the request interception is not enabled.
*
* @example
*
* ```ts
* await page.setRequestInterception(true);
* page.on('request', request => {
@ -519,13 +519,14 @@ export class HTTPRequest {
*
* @example
* An example of fulfilling all requests with 404 responses:
*
* ```ts
* await page.setRequestInterception(true);
* page.on('request', request => {
* request.respond({
* status: 404,
* contentType: 'text/plain',
* body: 'Not Found!'
* body: 'Not Found!',
* });
* });
* ```

2
src/common/HTTPResponse.ts
View File

@ -160,7 +160,7 @@ export class HTTPResponse {
}
/**
* @returns The status text of the response (e.g. usually an "OK" for a
* @returns The status text of the response (e.g. usually an "OK" for a
* success).
*/
statusText(): string {

47
src/common/Input.ts
View File

@ -40,6 +40,7 @@ type KeyDescription = Required<
*
* @example
* An example of holding down `Shift` in order to select and delete some text:
*
* ```ts
* await page.keyboard.type('Hello World!');
* await page.keyboard.press('ArrowLeft');
@ -55,6 +56,7 @@ type KeyDescription = Required<
*
* @example
* An example of pressing `A`
*
* ```ts
* await page.keyboard.down('Shift');
* await page.keyboard.press('KeyA');
@ -230,6 +232,7 @@ export class Keyboard {
* Holding down `Shift` will not type the text in upper case.
*
* @example
*
* ```ts
* page.keyboard.sendCharacter('嗨');
* ```
@ -256,6 +259,7 @@ export class Keyboard {
* Holding down `Shift` will not type the text in upper case.
*
* @example
*
* ```ts
* await page.keyboard.type('Hello'); // Types instantly
* await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
@ -345,6 +349,7 @@ export interface MouseWheelOptions {
* Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse).
*
* @example
*
* ```ts
* // Using ‘page.mouse’ to trace a 100x100 square.
* await page.mouse.move(0, 0);
@ -365,17 +370,24 @@ export interface MouseWheelOptions {
*
* @example
* For example, if you want to select all content between nodes:
*
* ```ts
* await page.evaluate((from, to) => {
* const selection = from.getRootNode().getSelection();
* const range = document.createRange();
* range.setStartBefore(from);
* range.setEndAfter(to);
* selection.removeAllRanges();
* selection.addRange(range);
* }, fromJSHandle, toJSHandle);
* await page.evaluate(
* (from, to) => {
* const selection = from.getRootNode().getSelection();
* const range = document.createRange();
* range.setStartBefore(from);
* range.setEndAfter(to);
* selection.removeAllRanges();
* selection.addRange(range);
* },
* fromJSHandle,
* toJSHandle
* );
* ```
*
* If you then would want to copy-paste your selection, you can use the clipboard api:
*
* ```ts
* // The clipboard api does not allow you to copy, unless the tab is focused.
* await page.bringToFront();
@ -386,13 +398,19 @@ export interface MouseWheelOptions {
* return navigator.clipboard.readText();
* });
* ```
*
* **Note**: If you want access to the clipboard API,
* you have to give it permission to do so:
*
* ```ts
* await browser.defaultBrowserContext().overridePermissions(
* '<your origin>', ['clipboard-read', 'clipboard-write']
* );
* await browser
* .defaultBrowserContext()
* .overridePermissions('<your origin>', [
* 'clipboard-read',
* 'clipboard-write',
* ]);
* ```
*
* @public
*/
export class Mouse {
@ -504,8 +522,11 @@ export class Mouse {
*
* @example
* An example of zooming into an element:
*
* ```ts
* await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
* await page.goto(
* 'https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366'
* );
*
* const elem = await page.$('div');
* const boundingBox = await elem.boundingBox();
@ -514,7 +535,7 @@ export class Mouse {
* boundingBox.y + boundingBox.height / 2
* );
*
* await page.mouse.wheel({ deltaY: -100 })
* await page.mouse.wheel({deltaY: -100});
* ```
*/
async wheel(options: MouseWheelOptions = {}): Promise<void> {

4
src/common/JSHandle.ts
View File

@ -65,6 +65,7 @@ export interface BoundingBox extends Point {
* They are resolved to their referenced object.
*
* @example
*
* ```ts
* const windowHandle = await page.evaluateHandle(() => window);
* ```
@ -177,6 +178,7 @@ export class JSHandle<T = unknown> {
* Gets a map of handles representing the properties of the current handle.
*
* @example
*
* ```ts
* const listHandle = await page.evaluateHandle(() => document.body.children);
* const properties = await listHandle.getProperties();
@ -214,7 +216,7 @@ export class JSHandle<T = unknown> {
* @throws Throws if the object cannot be serialized due to circularity.
*
* @remarks
* If the object has a `toJSON` function, it *will not* be called.
* If the object has a `toJSON` function, it **will not** be called.
*/
async jsonValue(): Promise<T> {
if (!this.#remoteObject.objectId) {

34
src/common/NetworkEventManager.ts
View File

@ -35,14 +35,14 @@ export type NetworkRequestId = string;
* @internal
*/
export class NetworkEventManager {
/*
/**
* There are four possible orders of events:
* A. `_onRequestWillBeSent`
* B. `_onRequestWillBeSent`, `_onRequestPaused`
* C. `_onRequestPaused`, `_onRequestWillBeSent`
* D. `_onRequestPaused`, `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, `_onRequestPaused`
* (see crbug.com/1196004)
* A. `_onRequestWillBeSent`
* B. `_onRequestWillBeSent`, `_onRequestPaused`
* C. `_onRequestPaused`, `_onRequestWillBeSent`
* D. `_onRequestPaused`, `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, `_onRequestPaused`
* (see crbug.com/1196004)
*
* For `_onRequest` we need the event from `_onRequestWillBeSent` and
* optionally the `interceptionId` from `_onRequestPaused`.
@ -56,16 +56,16 @@ export class NetworkEventManager {
*
* Note that (chains of) redirect requests have the same `requestId` (!) as
* the original request. We have to anticipate series of events like these:
* A. `_onRequestWillBeSent`,
* `_onRequestWillBeSent`, ...
* B. `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, ...
* C. `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestPaused`, `_onRequestWillBeSent`, ...
* D. `_onRequestPaused`, `_onRequestWillBeSent`,
* `_onRequestPaused`, `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, `_onRequestPaused`, ...
* (see crbug.com/1196004)
* A. `_onRequestWillBeSent`,
* `_onRequestWillBeSent`, ...
* B. `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, ...
* C. `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestPaused`, `_onRequestWillBeSent`, ...
* D. `_onRequestPaused`, `_onRequestWillBeSent`,
* `_onRequestPaused`, `_onRequestWillBeSent`, `_onRequestPaused`,
* `_onRequestWillBeSent`, `_onRequestPaused`, `_onRequestPaused`, ...
* (see crbug.com/1196004)
*/
#requestWillBeSentMap = new Map<
NetworkRequestId,

2
src/common/PDFOptions.ts
View File

@ -46,6 +46,7 @@ export type LowerCasePaperFormat =
* @remarks
*
* The sizes of each format are as follows:
*
* - `Letter`: 8.5in x 11in
*
* - `Legal`: 8.5in x 14in
@ -93,6 +94,7 @@ export interface PDFOptions {
/**
* HTML template for the print header. Should be valid HTML with the following
* classes used to inject values into them:
*
* - `date` formatted print date
*
* - `title` document title

580
src/common/Page.ts
View File

File diff suppressed because it is too large Load Diff

21
src/common/Puppeteer.ts
View File

@ -81,8 +81,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { devices } from 'puppeteer';
* import {devices} from 'puppeteer';
* ```
*/
get devices(): typeof devices {
@ -92,8 +93,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { errors } from 'puppeteer';
* import {errors} from 'puppeteer';
* ```
*/
get errors(): typeof errors {
@ -103,8 +105,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { networkConditions } from 'puppeteer';
* import {networkConditions} from 'puppeteer';
* ```
*/
get networkConditions(): typeof networkConditions {
@ -114,8 +117,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { registerCustomQueryHandler } from 'puppeteer';
* import {registerCustomQueryHandler} from 'puppeteer';
* ```
*/
registerCustomQueryHandler(
@ -128,8 +132,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { unregisterCustomQueryHandler } from 'puppeteer';
* import {unregisterCustomQueryHandler} from 'puppeteer';
* ```
*/
unregisterCustomQueryHandler(name: string): void {
@ -139,8 +144,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { customQueryHandlerNames } from 'puppeteer';
* import {customQueryHandlerNames} from 'puppeteer';
* ```
*/
customQueryHandlerNames(): string[] {
@ -150,8 +156,9 @@ export class Puppeteer {
/**
* @deprecated Import directly puppeteer.
* @example
*
* ```ts
* import { clearCustomQueryHandlers } from 'puppeteer';
* import {clearCustomQueryHandlers} from 'puppeteer';
* ```
*/
clearCustomQueryHandlers(): void {

1
src/common/QueryHandler.ts
View File

@ -261,6 +261,7 @@ const QUERY_HANDLERS = new Map<string, RegisteredQueryHandler>();
* allowed to consist of lower- and upper case latin letters.
*
* @example
*
* ```
* puppeteer.registerCustomQueryHandler('text', { … });
* const aHandle = await page.$('text/…');

1
src/common/Tracing.ts
View File

@ -37,6 +37,7 @@ export interface TracingOptions {
* which can be opened in Chrome DevTools or {@link https://chromedevtools.github.io/timeline-viewer/ | timeline viewer}.
*
* @example
*
* ```ts
* await page.tracing.start({path: 'trace.json'});
* await page.goto('https://www.google.com');

9
src/common/WebWorker.ts
View File

@ -49,9 +49,14 @@ type JSHandleFactory = (obj: Protocol.Runtime.RemoteObject) => JSHandle;
* object to signal the worker lifecycle.
*
* @example
*
* ```ts
* page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
* page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
* page.on('workercreated', worker =>
* console.log('Worker created: ' + worker.url())
* );
* page.on('workerdestroyed', worker =>
* console.log('Worker destroyed: ' + worker.url())
* );
*
* console.log('Current workers:');
* for (const worker of page.workers()) {

4
src/node/BrowserFetcher.ts
View File

@ -183,7 +183,9 @@ export interface BrowserFetcherRevisionInfo {
* ```ts
* const browserFetcher = puppeteer.createBrowserFetcher();
* const revisionInfo = await browserFetcher.download('533271');
* const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
* const browser = await puppeteer.launch({
* executablePath: revisionInfo.executablePath,
* });
* ```
*
* **NOTE** BrowserFetcher is not designed to work concurrently with other

4
src/node/Puppeteer.ts
View File

@ -54,6 +54,7 @@ export interface PuppeteerLaunchOptions
*
* @example
* The following is a typical example of using Puppeteer to drive automation:
*
* ```ts
* const puppeteer = require('puppeteer');
*
@ -132,9 +133,10 @@ export class PuppeteerNode extends Puppeteer {
*
* @example
* You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
*
* ```ts
* const browser = await puppeteer.launch({
* ignoreDefaultArgs: ['--mute-audio']
* ignoreDefaultArgs: ['--mute-audio'],
* });
* ```
*

11
test/src/NetworkManager.spec.ts
View File

@ -481,18 +481,19 @@ describeChromeOnly('NetworkManager', () => {
* This sequence was taken from an actual CDP session produced by the following
* test script:
*
* const browser = await puppeteer.launch(\{ headless: false \});
* ```ts
* const browser = await puppeteer.launch({headless: false});
* const page = await browser.newPage();
* await page.setCacheEnabled(false);
*
* await page.setRequestInterception(true)
* page.on('request', (interceptedRequest) =\> \{
* await page.setRequestInterception(true);
* page.on('request', interceptedRequest => {
* interceptedRequest.continue();
* \});
* });
*
* await page.goto('https://www.google.com');
* await browser.close();
*
* ```
*/
mockCDPSession.emit('Network.requestWillBeSent', {
requestId: '11ACE9783588040D644B905E8B55285B',

3
utils/internal/custom_markdown_documenter.ts
View File

@ -95,7 +95,7 @@ export interface IMarkdownDocumenterOptions {
/**
* Renders API documentation in the Markdown file format.
* For more info: https://en.wikipedia.org/wiki/Markdown
* For more info: https://en.wikipedia.org/wiki/Markdown
*/
export class MarkdownDocumenter {
private readonly _apiModel: ApiModel;
@ -392,6 +392,7 @@ export class MarkdownDocumenter {
pageContent;
pageContent = pageContent.replace('##', '#');
pageContent = pageContent.replace(/<!-- -->/g, '');
pageContent = pageContent.replace(/\\\*\\\*/g, '**');
pageContent = pageContent.replace(/<b>|<\/b>/g, '**');
FileSystem.writeFile(filename, pageContent, {
convertLineEndings: this._documenterConfig

3763
website/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

18
website/package.json
View File

@ -15,17 +15,17 @@
"archive": "node archive.js"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.21",
"@docusaurus/preset-classic": "2.0.0-beta.21",
"@easyops-cn/docusaurus-search-local": "^0.28.0",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.1.1",
"prism-react-renderer": "^1.3.3",
"react": "^17.0.2",
"react-dom": "^17.0.2"
"@docusaurus/core": "2.0.1",
"@docusaurus/preset-classic": "2.0.1",
"@easyops-cn/docusaurus-search-local": "0.26.1",
"@mdx-js/react": "1.6.22",
"clsx": "^1.2.1",
"prism-react-renderer": "1.3.5",
"react": "17.0.2",
"react-dom": "17.0.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.21"
"@docusaurus/module-type-aliases": "2.0.1"
},
"browserslist": {
"production": [