docs(new): Add TSDoc to Coverage class (#6106)

new-docs/puppeteer.coverage._jscoverage.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Coverage](./puppeteer.coverage.md) &gt; [\_jsCoverage](./puppeteer.coverage._jscoverage.md)
-
-## Coverage.\_jsCoverage property
-
-<b>Signature:</b>
-
-```typescript
-_jsCoverage: JSCoverage;
-```

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.
+
 <b>Signature:</b>
 
 ```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 <code>Coverage</code> class |
 
-## Properties
-
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [\_cssCoverage](./puppeteer.coverage._csscoverage.md) |  | CSSCoverage |  |
-|  [\_jsCoverage](./puppeteer.coverage._jscoverage.md) |  | JSCoverage |  |
-
 ## Methods
 
 |  Method | Modifiers | Description |

new-docs/puppeteer.coverage.startcsscoverage.md

@@ -7,18 +7,18 @@
 <b>Signature:</b>
 
 ```typescript
-startCSSCoverage(options?: {
-        resetOnNavigation?: boolean;
-    }): Promise<void>;
+startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { resetOnNavigation?: boolean; } |  |
+|  options | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) | defaults to <code>{ resetOnNavigation : true }</code> |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+Promise that resolves when coverage is started.
+

new-docs/puppeteer.coverage.startjscoverage.md

@@ -7,19 +7,22 @@
 <b>Signature:</b>
 
 ```typescript
-startJSCoverage(options?: {
-        resetOnNavigation?: boolean;
-        reportAnonymousScripts?: boolean;
-    }): Promise<void>;
+startJSCoverage(options?: JSCoverageOptions): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { resetOnNavigation?: boolean; reportAnonymousScripts?: boolean; } |  |
+|  options | [JSCoverageOptions](./puppeteer.jscoverageoptions.md) | defaults to <code>{ resetOnNavigation : true, reportAnonymousScripts : false }</code> |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+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.
+

new-docs/puppeteer.coverage.stopcsscoverage.md

@@ -11,5 +11,11 @@ stopCSSCoverage(): Promise<CoverageEntry[]>;
 ```
 <b>Returns:</b>
 
-Promise&lt;CoverageEntry\[\]&gt;
+Promise&lt;[CoverageEntry](./puppeteer.coverageentry.md)<!-- -->\[\]&gt;
+
+Promise that resolves to the array of coverage reports for all stylesheets.
+
+## Remarks
+
+CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
 

new-docs/puppeteer.coverage.stopjscoverage.md

@@ -11,5 +11,11 @@ stopJSCoverage(): Promise<CoverageEntry[]>;
 ```
 <b>Returns:</b>
 
-Promise&lt;CoverageEntry\[\]&gt;
+Promise&lt;[CoverageEntry](./puppeteer.coverageentry.md)<!-- -->\[\]&gt;
+
+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.
 

new-docs/puppeteer.coverageentry.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CoverageEntry](./puppeteer.coverageentry.md)
+
+## CoverageEntry interface
+
+The CoverageEntry class represents one entry of the coverage report.
+
+<b>Signature:</b>
+
+```typescript
+export interface CoverageEntry 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [ranges](./puppeteer.coverageentry.ranges.md) | Array&lt;{ start: number; end: number; }&gt; | 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. |
+

new-docs/puppeteer.coverageentry.ranges.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CoverageEntry](./puppeteer.coverageentry.md) &gt; [ranges](./puppeteer.coverageentry.ranges.md)
+
+## CoverageEntry.ranges property
+
+The covered range as start and end positions.
+
+<b>Signature:</b>
+
+```typescript
+ranges: Array<{
+        start: number;
+        end: number;
+    }>;
+```

new-docs/puppeteer.coverageentry.text.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CoverageEntry](./puppeteer.coverageentry.md) &gt; [text](./puppeteer.coverageentry.text.md)
+
+## CoverageEntry.text property
+
+The content of the style sheet or script.
+
+<b>Signature:</b>
+
+```typescript
+text: string;
+```

new-docs/puppeteer.coverageentry.url.md

@@ -1,11 +1,13 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Coverage](./puppeteer.coverage.md) &gt; [\_cssCoverage](./puppeteer.coverage._csscoverage.md)
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CoverageEntry](./puppeteer.coverageentry.md) &gt; [url](./puppeteer.coverageentry.url.md)
 
-## Coverage.\_cssCoverage property
+## CoverageEntry.url property
+
+The URL of the style sheet or script.
 
 <b>Signature:</b>
 
 ```typescript
-_cssCoverage: CSSCoverage;
+url: string;
 ```

new-docs/puppeteer.csscoverageoptions.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CSSCoverageOptions](./puppeteer.csscoverageoptions.md)
+
+## CSSCoverageOptions interface
+
+Set of configurable options for CSS coverage.
+
+<b>Signature:</b>
+
+```typescript
+export interface CSSCoverageOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [resetOnNavigation](./puppeteer.csscoverageoptions.resetonnavigation.md) | boolean | Whether to reset coverage on every navigation. |
+

new-docs/puppeteer.csscoverageoptions.resetonnavigation.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) &gt; [resetOnNavigation](./puppeteer.csscoverageoptions.resetonnavigation.md)
+
+## CSSCoverageOptions.resetOnNavigation property
+
+Whether to reset coverage on every navigation.
+
+<b>Signature:</b>
+
+```typescript
+resetOnNavigation?: boolean;
+```

new-docs/puppeteer.jscoverageoptions.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [JSCoverageOptions](./puppeteer.jscoverageoptions.md)
+
+## JSCoverageOptions interface
+
+Set of configurable options for JS coverage.
+
+<b>Signature:</b>
+
+```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. |
+

new-docs/puppeteer.jscoverageoptions.reportanonymousscripts.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [JSCoverageOptions](./puppeteer.jscoverageoptions.md) &gt; [reportAnonymousScripts](./puppeteer.jscoverageoptions.reportanonymousscripts.md)
+
+## JSCoverageOptions.reportAnonymousScripts property
+
+Whether anonymous scripts generated by the page should be reported.
+
+<b>Signature:</b>
+
+```typescript
+reportAnonymousScripts?: boolean;
+```

new-docs/puppeteer.jscoverageoptions.resetonnavigation.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [JSCoverageOptions](./puppeteer.jscoverageoptions.md) &gt; [resetOnNavigation](./puppeteer.jscoverageoptions.resetonnavigation.md)
+
+## JSCoverageOptions.resetOnNavigation property
+
+Whether to reset coverage on every navigation.
+
+<b>Signature:</b>
+
+```typescript
+resetOnNavigation?: boolean;
+```

new-docs/puppeteer.md

@@ -15,7 +15,7 @@
 |  [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> 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 <code>dialog</code> 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 at<!-- -->http://www.apache.org/licenses/LICENSE-2.0<!-- -->Unless 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) |  |

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<void> {
+  /**
+   * @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<void> {
     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<CoverageEntry[]> {
     return await this._jsCoverage.stop();
   }
 
-  async startCSSCoverage(
-    options: {
-      resetOnNavigation?: boolean;
-    } = {}
-  ): Promise<void> {
+  /**
+   * @param options - defaults to `{ resetOnNavigation : true }`
+   * @returns Promise that resolves when coverage is started.
+   */
+  async startCSSCoverage(options: CSSCoverageOptions = {}): Promise<void> {
     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<CoverageEntry[]> {
     return await this._cssCoverage.stop();
   }

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);