Report v2: check/x boolean audits, expand details failing audits, optimal val

lighthouse-core/report/v2/report-generator.js

@@ -23,6 +23,7 @@ const REPORT_TEMPLATE = fs.readFileSync(path.join(__dirname, './report-template.
 // TODO: Setup a gulp pipeline to concat and minify the renderer files?
 const REPORT_JAVASCRIPT = fs.readFileSync(path.join(__dirname, './report-renderer.js'), 'utf8');
 const REPORT_CSS = fs.readFileSync(path.join(__dirname, './report-styles.css'), 'utf8');
+const REPORT_TEMPLATES = fs.readFileSync(path.join(__dirname, './templates.html'), 'utf8');
 
 class ReportGeneratorV2 {
   /**
@@ -97,11 +98,14 @@ class ReportGeneratorV2 {
   generateReportHtml(reportAsJson) {
     const sanitizedJson = JSON.stringify(reportAsJson).replace(/</g, '\\u003c');
     const sanitizedJavascript = REPORT_JAVASCRIPT.replace(/<\//g, '\\u003c/');
+    // Remove script in templates files just to be safe.
+    const sanitizedTemplates = REPORT_TEMPLATES.replace(/<script>([\s\S]*?)<\/script>/g, '');
 
     return ReportGeneratorV2.replaceStrings(REPORT_TEMPLATE, [
       {search: '%%LIGHTHOUSE_JSON%%', replacement: sanitizedJson},
       {search: '%%LIGHTHOUSE_JAVASCRIPT%%', replacement: sanitizedJavascript},
       {search: '/*%%LIGHTHOUSE_CSS%%*/', replacement: REPORT_CSS},
+      {search: '%%LIGHTHOUSE_TEMPLATES%%', replacement: sanitizedTemplates},
     ]);
   }
 }

lighthouse-core/report/v2/report-renderer.js

@@ -15,47 +15,54 @@
  */
 'use strict';
 
+/**
+ * @fileoverview The entry point for rendering the Lighthouse report based on the JSON output.
+ *    This file is injected into the report HTML along with the JSON report.
+ *
+ * Dummy text for ensuring report robustness: </script> pre$`post %%LIGHTHOUSE_JSON%%
+ */
+
 /* eslint-env browser */
 /* eslint indent: [2, 2, { "SwitchCase": 1, "outerIIFEBody": 0 }] */
 
 (function() {
 const RATINGS = {
-  GOOD: {label: 'good', minScore: 75},
+  PASS: {label: 'pass', minScore: 75},
   AVERAGE: {label: 'average', minScore: 45},
-  POOR: {label: 'poor'}
+  FAIL: {label: 'fail'}
 };
 
 /**
  * Convert a score to a rating label.
- * @param {number} value
- * @return {string}
+ * @param {!number} score
+ * @param {!string} scoringMode One of Audit.SCORING_MODES.
+ * @return {!string}
  */
-function calculateRating(value) {
-  let rating = RATINGS.POOR.label;
-  if (value >= RATINGS.GOOD.minScore) {
-    rating = RATINGS.GOOD.label;
-  } else if (value >= RATINGS.AVERAGE.minScore) {
-    rating = RATINGS.AVERAGE.label;
-  }
-  return rating;
+function calculateRating(score, scoringMode) {
+  if (scoringMode === 'numeric') {
+    let rating = RATINGS.FAIL.label;
+    if (score >= RATINGS.PASS.minScore) {
+      rating = RATINGS.PASS.label;
+    } else if (score >= RATINGS.AVERAGE.minScore) {
+      rating = RATINGS.AVERAGE.label;
+    }
+    return rating;
+  }
+
+  // Treat as binary by default.
+  return score === 100 ? RATINGS.PASS.label : RATINGS.FAIL.label;
 }
 
 /**
  * Format number.
- * @param {number} number
- * @return {string}
+ * @param {!number} number
+ * @return {!string}
  */
 function formatNumber(number) {
   return number.toLocaleString(undefined, {maximumFractionDigits: 1});
 }
 
-/**
- * @fileoverview The entry point for rendering the Lighthouse report based on the JSON output.
- *    This file is injected into the report HTML along with the JSON report.
- *
- * Dummy text for ensuring report robustness: </script> pre$`post %%LIGHTHOUSE_JSON%%
- */
-window.ReportRenderer = class ReportRenderer {
+class DOM {
   /**
    * @param {!Document} document
    */
@@ -64,15 +71,31 @@ window.ReportRenderer = class ReportRenderer {
   }
 
   /**
-   * @param {!ReportJSON} report
-   * @return {!Element}
+   * Sets the text content of an element, safely. If the element does not exist,
+   * results in a noop.
+   * @param {Element} element
+   * @param {!string} text
+   * @return {Element}
    */
-  renderReport(report) {
-    try {
-      return this._renderReport(report);
-    } catch (e) {
-      return this._renderException(e);
+  static setText(element, text) {
+    if (element) {
+      element.textContent = text;
+    }
+    return element;
+  }
+
+  /**
+   * Adds a class to an element, safely. If the element does not exist, results
+   * in a noop.
+   * @param {Element} element
+   * @param {...!string} classes
+   * @return {Element}
+   */
+  static addClass(element, ...classes) {
+    if (element) {
+      element.classList.add(...classes);
     }
+    return element;
   }
 
   /**
@@ -81,7 +104,7 @@ window.ReportRenderer = class ReportRenderer {
    * @param {!Object<string, string>=} attrs Attribute key/val pairs.
    * @return {!Element}
    */
-  _createElement(name, className, attrs = {}) {
+  createElement(name, className, attrs = {}) {
     const element = this._document.createElement(name);
     if (className) {
       element.className = className;
@@ -93,24 +116,81 @@ window.ReportRenderer = class ReportRenderer {
   }
 
   /**
-   * @param {number} score
-   * @param {string} title
-   * @param {string} description
+   * @param {!string} selector
+   * @return {!DocumentFragment} A clone of the template content.
+   * @throws {Error}
+   */
+  cloneTemplate(selector) {
+    const template = this._document.querySelector(selector);
+    if (!template) {
+      throw new Error(`Template not found: template${selector}`);
+    }
+    return this._document.importNode(template.content, true);
+  }
+}
+
+class ReportRenderer {
+  /**
+   * @param {!Document} document
+   */
+  constructor(document) {
+    this._dom = new DOM(document);
+  }
+
+  /**
+   * @param {!ReportJSON} report
    * @return {!Element}
    */
-  _renderScore(score, title, description) {
-    const element = this._createElement('div', 'lighthouse-score');
+  renderReport(report) {
+    try {
+      return this._renderReport(report);
+    } catch (e) {
+      return this._renderException(e);
+    }
+  }
 
-    const value = element.appendChild(this._createElement('div', 'lighthouse-score__value'));
-    value.textContent = formatNumber(score);
-    value.classList.add(`lighthouse-score__value--${calculateRating(score)}`);
+  /**
+   * @param {!Element} tmpl Parent node to populate with values.
+   * @param {!{value: string, scoringMode: string}} score
+   * @param {!string} title
+   * @param {!string} description
+   * @return {!Element}
+   */
+  _populateScore(tmpl, score, title, description) {
+    const rating = calculateRating(score.value, score.scoringMode);
 
-    const column = element.appendChild(this._createElement('div', 'lighthouse-score__text'));
-    column.appendChild(this._createElement('div', 'lighthouse-score__title')).textContent = title;
-    column.appendChild(
-      this._createElement('div', 'lighthouse-score__description')).textContent = description;
+    // Fill in the blanks.
+    const value = tmpl.querySelector('.lighthouse-score__value');
+    DOM.setText(value, formatNumber(score.value));
+    DOM.addClass(value, `lighthouse-score__value--${rating}`,
+                        `lighthouse-score__value--${score.scoringMode}`);
 
-    return element;
+    DOM.setText(tmpl.querySelector('.lighthouse-score__title'), title);
+    DOM.setText(tmpl.querySelector('.lighthouse-score__description'), description);
+
+    return tmpl;
+  }
+
+  /**
+   * @param {!{value: string, scoringMode: string}} score
+   * @param {!string} title
+   * @param {!string} description
+   * @return {!Element}
+   */
+  _renderAuditScore(score, title, description) {
+    const tmpl = this._dom.cloneTemplate('#tmpl-lighthouse-audit-score');
+    return this._populateScore(tmpl, score, title, description);
+  }
+
+  /**
+   * @param {!{value: string, scoringMode: string}} score
+   * @param {!string} title
+   * @param {!string} description
+   * @return {!Element}
+   */
+  _renderCategoryScore(score, title, description) {
+    const tmpl = this._dom.cloneTemplate('#tmpl-lighthouse-category-score');
+    return this._populateScore(tmpl, score, title, description);
   }
 
   /**
@@ -135,7 +215,7 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderText(text) {
-    const element = this._createElement('div', 'lighthouse-text');
+    const element = this._dom.createElement('div', 'lighthouse-text');
     element.textContent = text.text;
     return element;
   }
@@ -145,7 +225,7 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderBlock(block) {
-    const element = this._createElement('div', 'lighthouse-block');
+    const element = this._dom.createElement('div', 'lighthouse-block');
     for (const item of block.items) {
       element.appendChild(this._renderDetails(item));
     }
@@ -157,14 +237,14 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderList(list) {
-    const element = this._createElement('details', 'lighthouse-list');
+    const element = this._dom.createElement('details', 'lighthouse-list');
     if (list.header) {
-      const summary = this._createElement('summary', 'lighthouse-list__header');
+      const summary = this._dom.createElement('summary', 'lighthouse-list__header');
       summary.textContent = list.header.text;
       element.appendChild(summary);
     }
 
-    const items = this._createElement('div', 'lighthouse-list__items');
+    const items = this._dom.createElement('div', 'lighthouse-list__items');
     for (const item of list.items) {
       items.appendChild(this._renderDetails(item));
     }
@@ -177,7 +257,7 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderException(e) {
-    const element = this._createElement('div', 'lighthouse-exception');
+    const element = this._dom.createElement('div', 'lighthouse-exception');
     element.textContent = String(e.stack);
     return element;
   }
@@ -187,7 +267,7 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderReport(report) {
-    const element = this._createElement('div', 'lighthouse-report');
+    const element = this._dom.createElement('div', 'lighthouse-report');
     for (const category of report.reportCategories) {
       element.appendChild(this._renderCategory(category));
     }
@@ -199,8 +279,10 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderCategory(category) {
-    const element = this._createElement('div', 'lighthouse-category');
-    element.appendChild(this._renderScore(category.score, category.name, category.description));
+    const element = this._dom.createElement('div', 'lighthouse-category');
+    const score = {value: Math.round(category.score), scoringMode: 'numeric'};
+    element.appendChild(
+        this._renderAuditScore(score, category.name, category.description, category));
     for (const audit of category.audits) {
       element.appendChild(this._renderAudit(audit));
     }
@@ -212,19 +294,35 @@ window.ReportRenderer = class ReportRenderer {
    * @return {!Element}
    */
   _renderAudit(audit) {
-    const element = this._createElement('div', 'lighthouse-audit');
+    const element = this._dom.createElement('div', 'lighthouse-audit');
     let title = audit.result.description;
     if (audit.result.displayValue) {
-      title += ': ' + audit.result.displayValue;
+      title += `:  ${audit.result.displayValue}`;
+    }
+    if (audit.result.optimalValue) {
+      title += ` (target: ${audit.result.optimalValue})`;
     }
-    element.appendChild(this._renderScore(audit.score, title, audit.result.helpText));
-    if (audit.result.details) {
-      element.appendChild(this._renderDetails(audit.result.details));
+
+    const score = {value: audit.score, scoringMode: audit.result.scoringMode};
+    element.appendChild(this._renderAuditScore(score, title, audit.result.helpText, audit));
+
+    // Append audit details to to header section so the entire audit is within one <details>.
+    const header = element.querySelector('.lighthouse-score__header');
+    if (header) {
+      header.open = audit.score < 100; // expand failed audits
+      if (audit.result.details) {
+        header.appendChild(this._renderDetails(audit.result.details));
+      }
     }
+
     return element;
   }
-};
-})();
+}
+
+// Exports
+self.ReportRenderer = ReportRenderer;
+self.DOM = DOM;
+})(self);
 
 /** @typedef {{type: string, text: string|undefined, header: DetailsJSON|undefined, items: Array<DetailsJSON>|undefined}} */
 let DetailsJSON; // eslint-disable-line no-unused-vars