From 123c3775125c06500cb3a006b6cfc1704a782445 Mon Sep 17 00:00:00 2001 From: Yang Guo Date: Mon, 29 Jun 2020 10:53:28 +0200 Subject: [PATCH] docs(new): Add TSDoc to Coverage class (#6106) --- new-docs/puppeteer.coverage._jscoverage.md | 11 -- new-docs/puppeteer.coverage.md | 42 +++++- .../puppeteer.coverage.startcsscoverage.md | 8 +- .../puppeteer.coverage.startjscoverage.md | 13 +- .../puppeteer.coverage.stopcsscoverage.md | 8 +- new-docs/puppeteer.coverage.stopjscoverage.md | 8 +- new-docs/puppeteer.coverageentry.md | 22 +++ new-docs/puppeteer.coverageentry.ranges.md | 16 +++ new-docs/puppeteer.coverageentry.text.md | 13 ++ ...rage.md => puppeteer.coverageentry.url.md} | 8 +- new-docs/puppeteer.csscoverageoptions.md | 20 +++ ...er.csscoverageoptions.resetonnavigation.md | 13 ++ new-docs/puppeteer.jscoverageoptions.md | 21 +++ ...scoverageoptions.reportanonymousscripts.md | 13 ++ ...eer.jscoverageoptions.resetonnavigation.md | 13 ++ new-docs/puppeteer.md | 5 +- src/common/Coverage.ts | 126 ++++++++++++++++-- utils/doclint/check_public_api/index.js | 14 ++ 18 files changed, 329 insertions(+), 45 deletions(-) delete mode 100644 new-docs/puppeteer.coverage._jscoverage.md create mode 100644 new-docs/puppeteer.coverageentry.md create mode 100644 new-docs/puppeteer.coverageentry.ranges.md create mode 100644 new-docs/puppeteer.coverageentry.text.md rename new-docs/{puppeteer.coverage._csscoverage.md => puppeteer.coverageentry.url.md} (50%) create mode 100644 new-docs/puppeteer.csscoverageoptions.md create mode 100644 new-docs/puppeteer.csscoverageoptions.resetonnavigation.md create mode 100644 new-docs/puppeteer.jscoverageoptions.md create mode 100644 new-docs/puppeteer.jscoverageoptions.reportanonymousscripts.md create mode 100644 new-docs/puppeteer.jscoverageoptions.resetonnavigation.md diff --git a/new-docs/puppeteer.coverage._jscoverage.md b/new-docs/puppeteer.coverage._jscoverage.md deleted file mode 100644 index d3b3dd4095e24..0000000000000 --- a/new-docs/puppeteer.coverage._jscoverage.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Coverage](./puppeteer.coverage.md) > [\_jsCoverage](./puppeteer.coverage._jscoverage.md) - -## Coverage.\_jsCoverage property - -Signature: - -```typescript -_jsCoverage: JSCoverage; -``` diff --git a/new-docs/puppeteer.coverage.md b/new-docs/puppeteer.coverage.md index 947f94e9ed27d..eb041d32a4cc1 100644 --- a/new-docs/puppeteer.coverage.md +++ b/new-docs/puppeteer.coverage.md @@ -4,25 +4,53 @@ ## Coverage class +The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. + Signature: ```typescript export declare class Coverage ``` +## Remarks + +To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul). + +## Example + +An example of using JavaScript and CSS coverage to get percentage of initially executed code: + +```js +// Enable both JavaScript and CSS coverage +await Promise.all([ + page.coverage.startJSCoverage(), + page.coverage.startCSSCoverage() +]); +// Navigate to page +await page.goto('https://example.com'); +// Disable both JavaScript and CSS coverage +const [jsCoverage, cssCoverage] = await Promise.all([ + page.coverage.stopJSCoverage(), + page.coverage.stopCSSCoverage(), +]); +let totalBytes = 0; +let usedBytes = 0; +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; +} +console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`); + +``` + ## Constructors | Constructor | Modifiers | Description | | --- | --- | --- | | [(constructor)(client)](./puppeteer.coverage._constructor_.md) | | Constructs a new instance of the Coverage class | -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_cssCoverage](./puppeteer.coverage._csscoverage.md) | | CSSCoverage | | -| [\_jsCoverage](./puppeteer.coverage._jscoverage.md) | | JSCoverage | | - ## Methods | Method | Modifiers | Description | diff --git a/new-docs/puppeteer.coverage.startcsscoverage.md b/new-docs/puppeteer.coverage.startcsscoverage.md index 5091ba68695b9..673535d72d88c 100644 --- a/new-docs/puppeteer.coverage.startcsscoverage.md +++ b/new-docs/puppeteer.coverage.startcsscoverage.md @@ -7,18 +7,18 @@ Signature: ```typescript -startCSSCoverage(options?: { - resetOnNavigation?: boolean; - }): Promise; +startCSSCoverage(options?: CSSCoverageOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { resetOnNavigation?: boolean; } | | +| options | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) | defaults to { resetOnNavigation : true } | Returns: Promise<void> +Promise that resolves when coverage is started. + diff --git a/new-docs/puppeteer.coverage.startjscoverage.md b/new-docs/puppeteer.coverage.startjscoverage.md index c7b878cdf17bb..cc24db4b1de97 100644 --- a/new-docs/puppeteer.coverage.startjscoverage.md +++ b/new-docs/puppeteer.coverage.startjscoverage.md @@ -7,19 +7,22 @@ Signature: ```typescript -startJSCoverage(options?: { - resetOnNavigation?: boolean; - reportAnonymousScripts?: boolean; - }): Promise; +startJSCoverage(options?: JSCoverageOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { resetOnNavigation?: boolean; reportAnonymousScripts?: boolean; } | | +| options | [JSCoverageOptions](./puppeteer.jscoverageoptions.md) | defaults to { resetOnNavigation : true, reportAnonymousScripts : false } | Returns: Promise<void> +Promise that resolves when coverage is started. + +## Remarks + +Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts will have `__puppeteer_evaluation_script__` as their URL. + diff --git a/new-docs/puppeteer.coverage.stopcsscoverage.md b/new-docs/puppeteer.coverage.stopcsscoverage.md index 1134d25f091f9..9b9537ce4eb15 100644 --- a/new-docs/puppeteer.coverage.stopcsscoverage.md +++ b/new-docs/puppeteer.coverage.stopcsscoverage.md @@ -11,5 +11,11 @@ stopCSSCoverage(): Promise; ``` Returns: -Promise<CoverageEntry\[\]> +Promise<[CoverageEntry](./puppeteer.coverageentry.md)\[\]> + +Promise that resolves to the array of coverage reports for all stylesheets. + +## Remarks + +CSS Coverage doesn't include dynamically injected style tags without sourceURLs. diff --git a/new-docs/puppeteer.coverage.stopjscoverage.md b/new-docs/puppeteer.coverage.stopjscoverage.md index aec5c0dd8ae8e..6f126873878ff 100644 --- a/new-docs/puppeteer.coverage.stopjscoverage.md +++ b/new-docs/puppeteer.coverage.stopjscoverage.md @@ -11,5 +11,11 @@ stopJSCoverage(): Promise; ``` Returns: -Promise<CoverageEntry\[\]> +Promise<[CoverageEntry](./puppeteer.coverageentry.md)\[\]> + +Promise that resolves to the array of coverage reports for all scripts. + +## Remarks + +JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are reported. diff --git a/new-docs/puppeteer.coverageentry.md b/new-docs/puppeteer.coverageentry.md new file mode 100644 index 0000000000000..96a6b6742160d --- /dev/null +++ b/new-docs/puppeteer.coverageentry.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CoverageEntry](./puppeteer.coverageentry.md) + +## CoverageEntry interface + +The CoverageEntry class represents one entry of the coverage report. + +Signature: + +```typescript +export interface CoverageEntry +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [ranges](./puppeteer.coverageentry.ranges.md) | Array<{ start: number; end: number; }> | The covered range as start and end positions. | +| [text](./puppeteer.coverageentry.text.md) | string | The content of the style sheet or script. | +| [url](./puppeteer.coverageentry.url.md) | string | The URL of the style sheet or script. | + diff --git a/new-docs/puppeteer.coverageentry.ranges.md b/new-docs/puppeteer.coverageentry.ranges.md new file mode 100644 index 0000000000000..2e0cfae91842b --- /dev/null +++ b/new-docs/puppeteer.coverageentry.ranges.md @@ -0,0 +1,16 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CoverageEntry](./puppeteer.coverageentry.md) > [ranges](./puppeteer.coverageentry.ranges.md) + +## CoverageEntry.ranges property + +The covered range as start and end positions. + +Signature: + +```typescript +ranges: Array<{ + start: number; + end: number; + }>; +``` diff --git a/new-docs/puppeteer.coverageentry.text.md b/new-docs/puppeteer.coverageentry.text.md new file mode 100644 index 0000000000000..c01b4246d4d43 --- /dev/null +++ b/new-docs/puppeteer.coverageentry.text.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CoverageEntry](./puppeteer.coverageentry.md) > [text](./puppeteer.coverageentry.text.md) + +## CoverageEntry.text property + +The content of the style sheet or script. + +Signature: + +```typescript +text: string; +``` diff --git a/new-docs/puppeteer.coverage._csscoverage.md b/new-docs/puppeteer.coverageentry.url.md similarity index 50% rename from new-docs/puppeteer.coverage._csscoverage.md rename to new-docs/puppeteer.coverageentry.url.md index df7c773d61e3e..cfd89f611fdbd 100644 --- a/new-docs/puppeteer.coverage._csscoverage.md +++ b/new-docs/puppeteer.coverageentry.url.md @@ -1,11 +1,13 @@ -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Coverage](./puppeteer.coverage.md) > [\_cssCoverage](./puppeteer.coverage._csscoverage.md) +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CoverageEntry](./puppeteer.coverageentry.md) > [url](./puppeteer.coverageentry.url.md) -## Coverage.\_cssCoverage property +## CoverageEntry.url property + +The URL of the style sheet or script. Signature: ```typescript -_cssCoverage: CSSCoverage; +url: string; ``` diff --git a/new-docs/puppeteer.csscoverageoptions.md b/new-docs/puppeteer.csscoverageoptions.md new file mode 100644 index 0000000000000..875f9f0425850 --- /dev/null +++ b/new-docs/puppeteer.csscoverageoptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) + +## CSSCoverageOptions interface + +Set of configurable options for CSS coverage. + +Signature: + +```typescript +export interface CSSCoverageOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [resetOnNavigation](./puppeteer.csscoverageoptions.resetonnavigation.md) | boolean | Whether to reset coverage on every navigation. | + diff --git a/new-docs/puppeteer.csscoverageoptions.resetonnavigation.md b/new-docs/puppeteer.csscoverageoptions.resetonnavigation.md new file mode 100644 index 0000000000000..7bc036974910c --- /dev/null +++ b/new-docs/puppeteer.csscoverageoptions.resetonnavigation.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) > [resetOnNavigation](./puppeteer.csscoverageoptions.resetonnavigation.md) + +## CSSCoverageOptions.resetOnNavigation property + +Whether to reset coverage on every navigation. + +Signature: + +```typescript +resetOnNavigation?: boolean; +``` diff --git a/new-docs/puppeteer.jscoverageoptions.md b/new-docs/puppeteer.jscoverageoptions.md new file mode 100644 index 0000000000000..300d4648633c0 --- /dev/null +++ b/new-docs/puppeteer.jscoverageoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [JSCoverageOptions](./puppeteer.jscoverageoptions.md) + +## JSCoverageOptions interface + +Set of configurable options for JS coverage. + +Signature: + +```typescript +export interface JSCoverageOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [reportAnonymousScripts](./puppeteer.jscoverageoptions.reportanonymousscripts.md) | boolean | Whether anonymous scripts generated by the page should be reported. | +| [resetOnNavigation](./puppeteer.jscoverageoptions.resetonnavigation.md) | boolean | Whether to reset coverage on every navigation. | + diff --git a/new-docs/puppeteer.jscoverageoptions.reportanonymousscripts.md b/new-docs/puppeteer.jscoverageoptions.reportanonymousscripts.md new file mode 100644 index 0000000000000..ce2cac9cddb81 --- /dev/null +++ b/new-docs/puppeteer.jscoverageoptions.reportanonymousscripts.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [JSCoverageOptions](./puppeteer.jscoverageoptions.md) > [reportAnonymousScripts](./puppeteer.jscoverageoptions.reportanonymousscripts.md) + +## JSCoverageOptions.reportAnonymousScripts property + +Whether anonymous scripts generated by the page should be reported. + +Signature: + +```typescript +reportAnonymousScripts?: boolean; +``` diff --git a/new-docs/puppeteer.jscoverageoptions.resetonnavigation.md b/new-docs/puppeteer.jscoverageoptions.resetonnavigation.md new file mode 100644 index 0000000000000..e6599c38c9d3d --- /dev/null +++ b/new-docs/puppeteer.jscoverageoptions.resetonnavigation.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [JSCoverageOptions](./puppeteer.jscoverageoptions.md) > [resetOnNavigation](./puppeteer.jscoverageoptions.resetonnavigation.md) + +## JSCoverageOptions.resetOnNavigation property + +Whether to reset coverage on every navigation. + +Signature: + +```typescript +resetOnNavigation?: boolean; +``` diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 5efbc184623f3..13db4adb2f1f2 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -15,7 +15,7 @@ | [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | | [Connection](./puppeteer.connection.md) | | | [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | -| [Coverage](./puppeteer.coverage.md) | | +| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. | | [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | | [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | | [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | @@ -52,7 +52,10 @@ | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | | [ClickOptions](./puppeteer.clickoptions.md) | | | [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | +| [CoverageEntry](./puppeteer.coverageentry.md) | The CoverageEntry class represents one entry of the coverage report. | +| [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) | Set of configurable options for CSS coverage. | | [GeolocationOptions](./puppeteer.geolocationoptions.md) | | +| [JSCoverageOptions](./puppeteer.jscoverageoptions.md) | Set of configurable options for JS coverage. | | [JSONObject](./puppeteer.jsonobject.md) | | | [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | | [Metrics](./puppeteer.metrics.md) | | diff --git a/src/common/Coverage.ts b/src/common/Coverage.ts index d9537dd0ddbff..5b590a0a2be8d 100644 --- a/src/common/Coverage.ts +++ b/src/common/Coverage.ts @@ -21,14 +21,95 @@ import { CDPSession } from './Connection'; import { EVALUATION_SCRIPT_URL } from './ExecutionContext'; -interface CoverageEntry { +/** + * The CoverageEntry class represents one entry of the coverage report. + * @public + */ +export interface CoverageEntry { + /** + * The URL of the style sheet or script. + */ url: string; + /** + * The content of the style sheet or script. + */ text: string; + /** + * The covered range as start and end positions. + */ ranges: Array<{ start: number; end: number }>; } +/** + * Set of configurable options for JS coverage. + * @public + */ +export interface JSCoverageOptions { + /** + * Whether to reset coverage on every navigation. + */ + resetOnNavigation?: boolean; + /** + * Whether anonymous scripts generated by the page should be reported. + */ + reportAnonymousScripts?: boolean; +} + +/** + * Set of configurable options for CSS coverage. + * @public + */ +export interface CSSCoverageOptions { + /** + * Whether to reset coverage on every navigation. + */ + resetOnNavigation?: boolean; +} + +/** + * The Coverage class provides methods to gathers information about parts of + * JavaScript and CSS that were used by the page. + * + * @remarks + * To output coverage in a form consumable by {@link https://github.com/istanbuljs | Istanbul}, + * see {@link https://github.com/istanbuljs/puppeteer-to-istanbul | puppeteer-to-istanbul}. + * + * @example + * An example of using JavaScript and CSS coverage to get percentage of initially + * executed code: + * ```js + * // Enable both JavaScript and CSS coverage + * await Promise.all([ + * page.coverage.startJSCoverage(), + * page.coverage.startCSSCoverage() + * ]); + * // Navigate to page + * await page.goto('https://example.com'); + * // Disable both JavaScript and CSS coverage + * const [jsCoverage, cssCoverage] = await Promise.all([ + * page.coverage.stopJSCoverage(), + * page.coverage.stopCSSCoverage(), + * ]); + * let totalBytes = 0; + * let usedBytes = 0; + * 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; + * } + * console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`); + * ``` + * @public + */ export class Coverage { + /** + * @internal + */ _jsCoverage: JSCoverage; + /** + * @internal + */ _cssCoverage: CSSCoverage; constructor(client: CDPSession) { @@ -36,27 +117,48 @@ export class Coverage { this._cssCoverage = new CSSCoverage(client); } - async startJSCoverage( - options: { - resetOnNavigation?: boolean; - reportAnonymousScripts?: boolean; - } = {} - ): Promise { + /** + * @param options - defaults to + * `{ resetOnNavigation : true, reportAnonymousScripts : false }` + * @returns Promise that resolves when coverage is started. + * + * @remarks + * Anonymous scripts are ones that don't have an associated url. These are + * scripts that are dynamically created on the page using `eval` or + * `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous + * scripts will have `__puppeteer_evaluation_script__` as their URL. + */ + async startJSCoverage(options: JSCoverageOptions = {}): Promise { return await this._jsCoverage.start(options); } + /** + * @returns Promise that resolves to the array of coverage reports for + * all scripts. + * + * @remarks + * JavaScript Coverage doesn't include anonymous scripts by default. + * However, scripts with sourceURLs are reported. + */ async stopJSCoverage(): Promise { return await this._jsCoverage.stop(); } - async startCSSCoverage( - options: { - resetOnNavigation?: boolean; - } = {} - ): Promise { + /** + * @param options - defaults to `{ resetOnNavigation : true }` + * @returns Promise that resolves when coverage is started. + */ + async startCSSCoverage(options: CSSCoverageOptions = {}): Promise { return await this._cssCoverage.start(options); } + /** + * @returns Promise that resolves to the array of coverage reports + * for all stylesheets. + * @remarks + * CSS Coverage doesn't include dynamically injected style tags + * without sourceURLs. + */ async stopCSSCoverage(): Promise { return await this._cssCoverage.stop(); } diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index b41c27852d0dc..45021b1993bb1 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -710,6 +710,20 @@ function compareDocumentations(actual, expected) { expectedName: 'Object', }, ], + [ + 'Method Coverage.startCSSCoverage() options', + { + actualName: 'Object', + expectedName: 'CSSCoverageOptions', + }, + ], + [ + 'Method Coverage.startJSCoverage() options', + { + actualName: 'Object', + expectedName: 'JSCoverageOptions', + }, + ], ]); const expectedForSource = expectedNamingMismatches.get(source);