report(psi): add lab data summary sentence (#5961)

lighthouse-core/lib/locales/en-US.json

@@ -431,6 +431,14 @@
     "message": "Report error: no audit information",
     "description": "An error string displayed next to a particular audit when it has errored, but not provided any specific error message."
   },
+  "lighthouse-core/report/html/renderer/util.js | labDataTitle": {
+    "message": "Lab Data",
+    "description": "Title of the lab data section of the Performance category. Within this section are various speed metrics which quantify the pageload performance into values presented in seconds and milliseconds. \"Lab\" is an abbreviated form of \"laboratory\", and refers to the fact that the data is from a controlled test of a website, not measurements from real users visiting that site."
+  },
+  "lighthouse-core/report/html/renderer/util.js | lsPerformanceCategoryDescription": {
+    "message": "[Lighthouse](https://developers.google.com/web/tools/lighthouse/) analysis of the current page on emulated 3G. Values are estimated and may vary.",
+    "description": "Explanation shown to users below performance results to inform them that the test was done with a 3G network connection and to warn them that the numbers they see will likely change slightly the next time they run Lighthouse. 'Lighthouse' becomes link text to additional documentation."
+  },
   "lighthouse-core/report/html/renderer/util.js | manualAuditsGroupTitle": {
     "message": "Additional items to manually check",
     "description": "Section heading shown above a list of audits that were not computed by Lighthouse. They serve as a list of suggestions for the user to go and manually check. For example, Lighthouse can't automate testing cross-browser compatibility, so that is listed within this section, so the user is reminded to test it themselves. This section is collapsed by default, as the user should be focusing on the failed audits instead. Users can click this heading to reveal the list."

lighthouse-core/report/html/renderer/performance-category-renderer.js

@@ -129,7 +129,7 @@ class PerformanceCategoryRenderer extends CategoryRenderer {
 
     // Metrics
     const metricAudits = category.auditRefs.filter(audit => audit.group === 'metrics');
-    const metricAuditsEl = this.renderAuditGroup(groups['metrics'], {expandable: false});
+    const metricAuditsEl = this.renderAuditGroup(groups.metrics, {expandable: false});
 
     const keyMetrics = metricAudits.filter(a => a.weight >= 3);
     const otherMetrics = metricAudits.filter(a => a.weight < 3);

lighthouse-core/report/html/renderer/psi.js

@@ -34,7 +34,7 @@
  * @return {{scoreGaugeEl: Element, perfCategoryEl: Element, finalScreenshotDataUri: string|null}}
  */
 function prepareLabData(LHResultJsonString, document) {
-  const lhResult = /** @type {LH.Result} */ JSON.parse(LHResultJsonString);
+  const lhResult = /** @type {LH.Result} */ (JSON.parse(LHResultJsonString));
   const dom = new DOM(document);
 
   // Assume fresh styles needed on every call, so mark all template styles as unused.
@@ -45,6 +45,11 @@ function prepareLabData(LHResultJsonString, document) {
   if (!perfCategory) throw new Error(`No performance category. Can't make lab data section`);
   if (!reportLHR.categoryGroups) throw new Error(`No category groups found.`);
 
+  // Use custom title and description.
+  reportLHR.categoryGroups.metrics.title = lhResult.i18n.rendererFormattedStrings.labDataTitle;
+  reportLHR.categoryGroups.metrics.description =
+      lhResult.i18n.rendererFormattedStrings.lsPerformanceCategoryDescription;
+
   const perfRenderer = new PerformanceCategoryRenderer(dom, new DetailsRenderer(dom));
   // PSI environment string will ensure the categoryHeader and permalink elements are excluded
   const perfCategoryEl = perfRenderer.render(perfCategory, reportLHR.categoryGroups, 'PSI');

lighthouse-core/report/html/renderer/util.js

@@ -481,6 +481,11 @@ Util.UIStrings = {
   crcInitialNavigation: 'Initial Navigation',
   /** Label of value shown in the summary of critical request chains. Refers to the total amount of time (milliseconds) of the longest critical path chain/sequence of network requests. Example value: 2310 ms */
   crcLongestDurationLabel: 'Maximum critical path latency:',
+
+  /** Explanation shown to users below performance results to inform them that the test was done with a 3G network connection and to warn them that the numbers they see will likely change slightly the next time they run Lighthouse. 'Lighthouse' becomes link text to additional documentation. */
+  lsPerformanceCategoryDescription: '[Lighthouse](https://developers.google.com/web/tools/lighthouse/) analysis of the current page on emulated 3G. Values are estimated and may vary.',
+  /** Title of the lab data section of the Performance category. Within this section are various speed metrics which quantify the pageload performance into values presented in seconds and milliseconds. "Lab" is an abbreviated form of "laboratory", and refers to the fact that the data is from a controlled test of a website, not measurements from real users visiting that site.  */
+  labDataTitle: 'Lab Data',
 };
 
 if (typeof module !== 'undefined' && module.exports) {

lighthouse-core/runner.js

@@ -138,12 +138,14 @@ class Runner {
         categories,
         categoryGroups: runOpts.config.groups || undefined,
         timing: {total: Date.now() - startTime},
+        i18n: {
+          rendererFormattedStrings: i18n.getRendererFormattedStrings(settings.locale),
+          icuMessagePaths: {},
+        },
       };
 
-      lhr.i18n = {
-        rendererFormattedStrings: i18n.getRendererFormattedStrings(settings.locale),
-        icuMessagePaths: i18n.replaceIcuMessageInstanceIds(lhr, settings.locale),
-      };
+      // Replace ICU message references with localized strings; save replaced paths in lhr.
+      lhr.i18n.icuMessagePaths = i18n.replaceIcuMessageInstanceIds(lhr, settings.locale);
 
       const report = generateReport(lhr, settings.output);
       return {lhr, artifacts, report};

lighthouse-core/test/report/html/renderer/psi-test.js

@@ -94,6 +94,21 @@ describe('DOM', () => {
           prepareLabData(lhrWithoutGroupsStr, document);
         }, /no category groups/i);
       });
+
+      it('includes custom title and description', () => {
+        const {perfCategoryEl} = prepareLabData(sampleResultsStr, document);
+        const metricsGroupEl = perfCategoryEl.querySelector('.lh-audit-group--metrics');
+
+        // Assume using default locale.
+        const titleEl = metricsGroupEl.querySelector('.lh-audit-group__header');
+        assert.equal(titleEl.textContent, Util.UIStrings.labDataTitle);
+
+        // Description supports markdown links, so take everything after the last link.
+        const descriptionEnd = /[^)]+$/.exec(Util.UIStrings.lsPerformanceCategoryDescription)[0];
+        assert.ok(descriptionEnd.length > 6); // If this gets too short, pick a different comparison :)
+        const descriptionEl = metricsGroupEl.querySelector('.lh-audit-group__description');
+        assert.ok(descriptionEl.textContent.endsWith(descriptionEnd));
+      });
     });
   });
 

lighthouse-core/test/results/sample_v2.json

@@ -3412,6 +3412,8 @@
       "crcLongestDurationLabel": "Maximum critical path latency:",
       "errorLabel": "Error!",
       "errorMissingAuditInfo": "Report error: no audit information",
+      "labDataTitle": "Lab Data",
+      "lsPerformanceCategoryDescription": "[Lighthouse](https://developers.google.com/web/tools/lighthouse/) analysis of the current page on emulated 3G. Values are estimated and may vary.",
       "manualAuditsGroupTitle": "Additional items to manually check",
       "notApplicableAuditsGroupTitle": "Not applicable",
       "opportunityResourceColumnLabel": "Opportunity",

typings/lhr.d.ts

@@ -57,7 +57,7 @@ declare global {
       /** Execution timings for the Lighthouse run */
       timing: {total: number, [t: string]: number};
       /** The record of all formatted string locations in the LHR and their corresponding source values. */
-      i18n?: {rendererFormattedStrings: I18NRendererStrings, icuMessagePaths: I18NMessages};
+      i18n: {rendererFormattedStrings: I18NRendererStrings, icuMessagePaths: I18NMessages};
     }
 
     // Result namespace