feat(coverage): expose raw v8 coverage

Author: pavelfeldman

docs/api.md

@@ -21,11 +21,11 @@
 - [class: Selectors](#class-selectors)
 - [class: TimeoutError](#class-timeouterror)
 - [class: Accessibility](#class-accessibility)
-- [class: Coverage](#class-coverage)
 - [class: Worker](#class-worker)
 - [class: BrowserServer](#class-browserserver)
 - [class: BrowserType](#class-browsertype)
 - [class: ChromiumBrowser](#class-chromiumbrowser)
+- [class: ChromiumCoverage](#class-chromiumcoverage)
 - [class: ChromiumSession](#class-chromiumsession)
 - [class: ChromiumTarget](#class-chromiumtarget)
 - [class: FirefoxBrowser](#class-firefoxbrowser)
@@ -796,9 +796,9 @@ Get the browser context that the page belongs to.
 
 #### page.coverage
 
-- returns: <[Coverage]>
+- returns: <?[any]>
 
-> **NOTE** Code coverage is currently only supported in Chromium.
+Browser-specific Coverage implementation, only available for Chromium atm. See [ChromiumCoverage](#class-chromiumcoverage) for more details.
 
 #### page.dblclick(selector[, options])
 - `selector` <[string]> A selector to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked.
@@ -3246,78 +3246,6 @@ function findFocusedNode(node) {
 }
 ```
 
-### class: Coverage
-
-Coverage gathers information about parts of JavaScript and CSS that were used by the page.
-
-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}%`);
-```
-
-<!-- GEN:toc -->
-- [coverage.startCSSCoverage([options])](#coveragestartcsscoverageoptions)
-- [coverage.startJSCoverage([options])](#coveragestartjscoverageoptions)
-- [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
-- [coverage.stopJSCoverage()](#coveragestopjscoverage)
-<!-- GEN:stop -->
-
-#### coverage.startCSSCoverage([options])
-- `options` <[Object]>  Set of configurable options for coverage
-  - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
-- returns: <[Promise]> Promise that resolves when coverage is started
-
-#### coverage.startJSCoverage([options])
-- `options` <[Object]>  Set of configurable options for coverage
-  - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
-  - `reportAnonymousScripts` <[boolean]> Whether anonymous scripts generated by the page should be reported. Defaults to `false`.
-- returns: <[Promise]> Promise that resolves when coverage is started
-
-> **NOTE** 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 `__playwright_evaluation_script__` as their URL.
-
-#### coverage.stopCSSCoverage()
-- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets
-  - `url` <[string]> StyleSheet URL
-  - `text` <[string]> StyleSheet content
-  - `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping.
-    - `start` <[number]> A start offset in text, inclusive
-    - `end` <[number]> An end offset in text, exclusive
-
-> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
-
-#### coverage.stopJSCoverage()
-- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all scripts
-  - `url` <[string]> Script URL
-  - `text` <[string]> Script content
-  - `ranges` <[Array]<[Object]>> Script ranges that were executed. Ranges are sorted and non-overlapping.
-    - `start` <[number]> A start offset in text, inclusive
-    - `end` <[number]> An end offset in text, exclusive
-
-> **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
-reported.
-
 ### class: Worker
 
 The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
@@ -3672,6 +3600,71 @@ await page.evaluate(() => window.open('https://www.example.com/'));
 const newWindowTarget = await browser.chromium.waitForTarget(target => target.url() === 'https://www.example.com/');
 ```
 
+### class: ChromiumCoverage
+
+Coverage gathers information about parts of JavaScript and CSS that were used by the page.
+
+An example of using JavaScript coverage to produce Istambul report for page load:
+
+```js
+const { chromium } = require('.');
+const v8toIstanbul = require('v8-to-istanbul');
+
+(async() => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.coverage.startJSCoverage();
+  await page.goto('https://chromium.org');
+  const coverage = await page.coverage.stopJSCoverage();
+  for (const entry of coverage) {
+    const converter = new v8toIstanbul('', 0, { source: entry.source });
+    await converter.load();
+    converter.applyCoverage(entry.functions);
+    console.log(JSON.stringify(converter.toIstanbul()));
+  }
+  await browser.close();
+})();
+```
+
+<!-- GEN:toc -->
+- [chromiumCoverage.startCSSCoverage([options])](#chromiumcoveragestartcsscoverageoptions)
+- [chromiumCoverage.startJSCoverage([options])](#chromiumcoveragestartjscoverageoptions)
+- [chromiumCoverage.stopCSSCoverage()](#chromiumcoveragestopcsscoverage)
+- [chromiumCoverage.stopJSCoverage()](#chromiumcoveragestopjscoverage)
+<!-- GEN:stop -->
+
+#### chromiumCoverage.startCSSCoverage([options])
+- `options` <[Object]>  Set of configurable options for coverage
+  - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
+- returns: <[Promise]> Promise that resolves when coverage is started
+
+#### chromiumCoverage.startJSCoverage([options])
+- `options` <[Object]>  Set of configurable options for coverage
+  - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
+  - `reportAnonymousScripts` <[boolean]> Whether anonymous scripts generated by the page should be reported. Defaults to `false`.
+- returns: <[Promise]> Promise that resolves when coverage is started
+
+> **NOTE** 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 `__playwright_evaluation_script__` as their URL.
+
+#### chromiumCoverage.stopCSSCoverage()
+- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets
+  - `url` <[string]> StyleSheet URL
+  - `source` <[string]> StyleSheet content
+  - `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping.
+    - `start` <[number]> A start offset in text, inclusive
+    - `end` <[number]> An end offset in text, exclusive
+
+> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
+
+#### chromiumCoverage.stopJSCoverage()
+- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all scripts
+  - `url` <[string]> Script URL
+  - `source` <[string]> Script content
+  - `functions` <[Array]<[Object]>> V8-specific coverage format.
+
+> **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
+reported.
+
 ### class: ChromiumSession
 
 * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)

src/api.ts

@@ -25,10 +25,11 @@ export { Frame } from './frames';
 export { Keyboard, Mouse } from './input';
 export { JSHandle } from './javascript';
 export { Request, Response } from './network';
-export { Coverage, FileChooser, Page, Worker } from './page';
+export { FileChooser, Page, Worker } from './page';
 export { Selectors } from './selectors';
 
 export { CRBrowser as ChromiumBrowser } from './chromium/crBrowser';
+export { CRCoverage as ChromiumCoverage } from './chromium/crCoverage';
 export { CRSession as ChromiumSession } from './chromium/crConnection';
 export { CRTarget as ChromiumTarget } from './chromium/crTarget';