feat: implement CSS Coverage (#1714)

This patch adds two new methods to the `page.coverage` namespace:
- `page.coverage.startCSSCoverage()` - to initiate css coverage
- `page.coverage.stopCSSCoverage()` - to stop css coverage

The coverage format is consistent with the JavaScript coverage.

docs/api.md

@@ -199,7 +199,9 @@
   * [target.type()](#targettype)
   * [target.url()](#targeturl)
 - [class: Coverage](#class-coverage)
+  * [coverage.startCSSCoverage(options)](#coveragestartcsscoverageoptions)
   * [coverage.startJSCoverage(options)](#coveragestartjscoverageoptions)
+  * [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
   * [coverage.stopJSCoverage()](#coveragestopjscoverage)
 
 <!-- tocstop -->
@@ -2155,11 +2157,56 @@ Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, or
 
 ### 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.startJSCoverage(),
+  page.startCSSCoverage()
+]);
+// Navigate to page
+await page.goto('https://example.com');
+// Disable both JavaScript and CSS coverage
+const [jsCoverage, cssCoverage] = await Promise.all([
+  page.stopJSCoverage(),
+  page.stopCSSCoverage(),
+]);
+let totalBytes = 0;
+let usedBytes = 0;
+const coverage = [].concat(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}%`);
+```
+
+#### 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`.
 - returns: <[Promise]> Promise that resolves when coverage is started
 
+#### 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 non-anonymous scripts
   - `url` <[string]> Script URL
@@ -2171,22 +2218,6 @@ Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, or
 > **NOTE** JavaScript Coverage doesn't include anonymous scripts; however, scripts with sourceURLs are
 reported.
 
-An example of using JavaScript coverage to get percentage of executed
-code:
-
-```js
-await page.startJSCoverage();
-await page.goto('https://example.com');
-const coverage = await page.stopJSCoverage();
-let totalBytes = 0;
-let usedBytes = 0;
-for (const entry of coverage) {
-  totalBytes += entry.text.length;
-  for (const range of entry.ranges)
-    usedBytes += range.end - range.start - 1;
-}
-console.log(`Coverage is ${usedBytes / totalBytes * 100}%`);
-```
 
 [Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
 [boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean"

lib/Coverage.js

@@ -16,12 +16,20 @@
 
 const {helper, debugError} = require('./helper');
 
+/**
+ * @typedef {Object} CoverageEntry
+ * @property {string} url
+ * @property {string} text
+ * @property {!Array<!{start: number, end: number}>} ranges
+ */
+
 class Coverage {
   /**
    * @param {!Puppeteer.Session} client
    */
   constructor(client) {
     this._jsCoverage = new JSCoverage(client);
+    this._cssCoverage = new CSSCoverage(client);
   }
 
   /**
@@ -31,9 +39,26 @@ class Coverage {
     return await this._jsCoverage.start(options);
   }
 
+  /**
+   * @return {!Promise<!Array<!CoverageEntry>>}
+   */
   async stopJSCoverage() {
     return await this._jsCoverage.stop();
   }
+
+  /**
+   * @param {!Object} options
+   */
+  async startCSSCoverage(options) {
+    return await this._cssCoverage.start(options);
+  }
+
+  /**
+   * @return {!Promise<!Array<!CoverageEntry>>}
+   */
+  async stopCSSCoverage() {
+    return await this._cssCoverage.stop();
+  }
 }
 
 module.exports = {Coverage};
@@ -98,7 +123,7 @@ class JSCoverage {
   }
 
   /**
-   * @return {!Promise<!Array<!{url:string, text:string, ranges:!Array<!{start:number, end:number}>}>>}
+   * @return {!Promise<!Array<!CoverageEntry>>}
    */
   async stop() {
     console.assert(this._enabled, 'JSCoverage is not enabled');
@@ -127,6 +152,104 @@ class JSCoverage {
   }
 }
 
+class CSSCoverage {
+  /**
+   * @param {!Puppeteer.Session} client
+   */
+  constructor(client) {
+    this._client = client;
+    this._enabled = false;
+    this._stylesheetURLs = new Map();
+    this._stylesheetSources = new Map();
+    this._eventListeners = [];
+    this._resetOnNavigation = false;
+  }
+
+  /**
+   * @param {!Object} options
+   */
+  async start(options = {}) {
+    console.assert(!this._enabled, 'CSSCoverage is already enabled');
+    this._resetOnNavigation = options.resetOnNavigation === undefined ? true : !!options.resetOnNavigation;
+    this._enabled = true;
+    this._stylesheetURLs.clear();
+    this._stylesheetSources.clear();
+    this._eventListeners = [
+      helper.addEventListener(this._client, 'CSS.styleSheetAdded', this._onStyleSheet.bind(this)),
+      helper.addEventListener(this._client, 'Runtime.executionContextsCleared', this._onExecutionContextsCleared.bind(this)),
+    ];
+    await Promise.all([
+      this._client.send('DOM.enable'),
+      this._client.send('CSS.enable'),
+      this._client.send('CSS.startRuleUsageTracking'),
+    ]);
+  }
+
+  _onExecutionContextsCleared() {
+    if (!this._resetOnNavigation)
+      return;
+    this._stylesheetURLs.clear();
+    this._stylesheetSources.clear();
+  }
+
+  /**
+   * @param {!Object} event
+   */
+  async _onStyleSheet(event) {
+    const header = event.header;
+    // Ignore anonymous scripts
+    if (!header.sourceURL)
+      return;
+    try {
+      const response = await this._client.send('CSS.getStyleSheetText', {styleSheetId: header.styleSheetId});
+      this._stylesheetURLs.set(header.styleSheetId, header.sourceURL);
+      this._stylesheetSources.set(header.styleSheetId, response.text);
+    } catch (e) {
+      // This might happen if the page has already navigated away.
+      debugError(e);
+    }
+  }
+
+  /**
+   * @return {!Promise<!Array<!CoverageEntry>>}
+   */
+  async stop() {
+    console.assert(this._enabled, 'CSSCoverage is not enabled');
+    this._enabled = false;
+    const [ruleTrackingResponse] = await Promise.all([
+      this._client.send('CSS.stopRuleUsageTracking'),
+      this._client.send('CSS.disable'),
+      this._client.send('DOM.disable'),
+    ]);
+    helper.removeEventListeners(this._eventListeners);
+
+    // aggregarte by styleSheetId
+    const styleSheetIdToCoverage = new Map();
+    for (const entry of ruleTrackingResponse.ruleUsage) {
+      let ranges = styleSheetIdToCoverage.get(entry.styleSheetId);
+      if (!ranges) {
+        ranges = [];
+        styleSheetIdToCoverage.set(entry.styleSheetId, ranges);
+      }
+      ranges.push({
+        startOffset: entry.startOffset,
+        endOffset: entry.endOffset,
+        count: entry.used ? 1 : 0,
+      });
+    }
+
+    const coverage = [];
+    for (const styleSheetId of this._stylesheetURLs.keys()) {
+      const url = this._stylesheetURLs.get(styleSheetId);
+      const text = this._stylesheetSources.get(styleSheetId);
+      const ranges = convertToDisjointRanges(styleSheetIdToCoverage.get(styleSheetId) || []);
+      coverage.push({url, ranges, text});
+    }
+
+    return coverage;
+  }
+}
+
 /**
  * @param {!Array<!{startOffset:number, endOffset:number, count:number}>} nestedRanges
  * @return {!Array<!{start:number, end:number}>}

test/assets/csscoverage/OFL.txt

@@ -0,0 +1,95 @@
+Copyright (c) 2011, Edgar Tolentino and Pablo Impallari (www.impallari.com|impallari@gmail.com),
+Copyright (c) 2011, Igino Marini. (www.ikern.com|mail@iginomarini.com),
+with Reserved Font Names "Dosis".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

test/assets/csscoverage/involved.html

@@ -0,0 +1,26 @@
+<style>
+@charset "utf-8";
+@namespace svg url(http://www.w3.org/2000/svg);
+@font-face {
+  font-family: "Example Font";
+  src: url("./Dosis-Regular.ttf");
+}
+
+#fluffy {
+  border: 1px solid black;
+  z-index: 1;
+  /* -webkit-disabled-property: rgb(1, 2, 3) */
+  -lol-cats: "dogs" /* non-existing property */
+}
+
+@media (min-width: 1px) {
+  span {
+    -webkit-border-radius: 10px;
+    font-family: "Example Font";
+    animation: 1s identifier;
+  }
+}
+</style>
+<div id="fluffy">woof!</div>
+<span>fancy text</span>
+

test/assets/csscoverage/media.html

@@ -0,0 +1,4 @@
+<style>
+@media screen { div { color: green; } } </style>
+<div>hello, world</div>
+

test/assets/csscoverage/multiple.html

@@ -0,0 +1,8 @@
+<link rel="stylesheet" href="stylesheet1.css">
+<link rel="stylesheet" href="stylesheet2.css">
+<script>
+window.addEventListener('DOMContentLoaded', () => {
+  // Force stylesheets to load.
+  console.log(window.getComputedStyle(document.body).color);
+}, false);
+</script>

test/assets/csscoverage/simple.html

@@ -0,0 +1,6 @@
+<style>
+div { color: green; }
+a { color: blue; }
+</style>
+<div>hello, world</div>
+

test/assets/csscoverage/sourceurl.html

@@ -0,0 +1,7 @@
+<style>
+body {
+  padding: 10px;
+}
+/*# sourceURL=nicename.css */
+</style>
+

test/assets/csscoverage/stylesheet1.css

@@ -0,0 +1,3 @@
+body {
+  color: red;
+}

test/assets/csscoverage/stylesheet2.css

@@ -0,0 +1,4 @@
+html {
+  margin: 0;
+  padding: 0;
+}

test/assets/csscoverage/unused.html

@@ -0,0 +1,7 @@
+<style>
+@media screen {
+  a { color: green; }
+}
+/*# sourceURL=unused.css */
+</style>
+

test/golden/csscoverage-involved.txt

@@ -0,0 +1,16 @@
+[
+  {
+    "url": "http://localhost:8907/csscoverage/involved.html",
+    "ranges": [
+      {
+        "start": 149,
+        "end": 297
+      },
+      {
+        "start": 327,
+        "end": 433
+      }
+    ],
+    "text": "\n@charset \"utf-8\";\n@namespace svg url(http://www.w3.org/2000/svg);\n@font-face {\n  font-family: \"Example Font\";\n  src: url(\"./Dosis-Regular.ttf\");\n}\n\n#fluffy {\n  border: 1px solid black;\n  z-index: 1;\n  /* -webkit-disabled-property: rgb(1, 2, 3) */\n  -lol-cats: \"dogs\" /* non-existing property */\n}\n\n@media (min-width: 1px) {\n  span {\n    -webkit-border-radius: 10px;\n    font-family: \"Example Font\";\n    animation: 1s identifier;\n  }\n}\n"
+  }
+]

test/test.js

@@ -3495,6 +3495,85 @@ describe('Page', function() {
       });
     });
   });
+  describe('CSSCoverage', function() {
+    it('should work', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/simple.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(1);
+      expect(coverage[0].url).toContain('/csscoverage/simple.html');
+      expect(coverage[0].ranges).toEqual([
+        {start: 1, end: 22}
+      ]);
+      const range = coverage[0].ranges[0];
+      expect(coverage[0].text.substring(range.start, range.end)).toBe('div { color: green; }');
+    });
+    it('should report sourceURLs', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/sourceurl.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(1);
+      expect(coverage[0].url).toBe('nicename.css');
+    });
+    it('should report multiple stylesheets', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/multiple.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(2);
+      coverage.sort((a, b) => a.url.localeCompare(b.url));
+      expect(coverage[0].url).toContain('/csscoverage/stylesheet1.css');
+      expect(coverage[1].url).toContain('/csscoverage/stylesheet2.css');
+    });
+    it('should report stylesheets that have no coverage', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/unused.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(1);
+      expect(coverage[0].url).toBe('unused.css');
+      expect(coverage[0].ranges.length).toBe(0);
+    });
+    it('should work with media queries', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/media.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(1);
+      expect(coverage[0].url).toContain('/csscoverage/media.html');
+      expect(coverage[0].ranges).toEqual([
+        {start: 17, end: 38}
+      ]);
+    });
+    it('should work with complicated usecases', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.goto(server.PREFIX + '/csscoverage/involved.html');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(JSON.stringify(coverage, null, 2)).toBeGolden('csscoverage-involved.txt');
+    });
+    it('should ignore injected stylesheets', async function({page, server}) {
+      await page.coverage.startCSSCoverage();
+      await page.addStyleTag({content: 'body { margin: 10px;}'});
+      // trigger style recalc
+      const margin = await page.evaluate(() => window.getComputedStyle(document.body).margin);
+      expect(margin).toBe('10px');
+      const coverage = await page.coverage.stopCSSCoverage();
+      expect(coverage.length).toBe(0);
+    });
+    describe('resetOnNavigation', function() {
+      it('should report stylesheets across navigations', async function({page, server}) {
+        await page.coverage.startCSSCoverage({resetOnNavigation: false});
+        await page.goto(server.PREFIX + '/csscoverage/multiple.html');
+        await page.goto(server.EMPTY_PAGE);
+        const coverage = await page.coverage.stopCSSCoverage();
+        expect(coverage.length).toBe(2);
+      });
+      it('should NOT report scripts across navigations', async function({page, server}) {
+        await page.coverage.startCSSCoverage(); // Enabled by default.
+        await page.goto(server.PREFIX + '/csscoverage/multiple.html');
+        await page.goto(server.EMPTY_PAGE);
+        const coverage = await page.coverage.stopCSSCoverage();
+        expect(coverage.length).toBe(0);
+      });
+    });
+  });
 });
 
 if (process.env.COVERAGE) {

utils/doclint/check_public_api/index.js

@@ -20,6 +20,7 @@ const Documentation = require('./Documentation');
 const Message = require('../Message');
 
 const EXCLUDE_CLASSES = new Set([
+  'CSSCoverage',
   'Connection',
   'Downloader',
   'EmulationManager',