report: link to calculator w/ values (#10754)

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

@@ -1610,6 +1610,9 @@
   "lighthouse-core/report/html/renderer/util.js | auditGroupExpandTooltip": {
     "message": "Show audits"
   },
+  "lighthouse-core/report/html/renderer/util.js | calculatorLink": {
+    "message": "See calculator."
+  },
   "lighthouse-core/report/html/renderer/util.js | crcInitialNavigation": {
     "message": "Initial Navigation"
   },

lighthouse-core/lib/i18n/locales/en-XL.json

@@ -1610,6 +1610,9 @@
   "lighthouse-core/report/html/renderer/util.js | auditGroupExpandTooltip": {
     "message": "Ŝh́ôẃ âúd̂ít̂ś"
   },
+  "lighthouse-core/report/html/renderer/util.js | calculatorLink": {
+    "message": "Ŝéê ćâĺĉúl̂át̂ór̂."
+  },
   "lighthouse-core/report/html/renderer/util.js | crcInitialNavigation": {
     "message": "Îńît́îál̂ Ńâv́îǵât́îón̂"
   },

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

@@ -104,6 +104,28 @@ class PerformanceCategoryRenderer extends CategoryRenderer {
     }
   }
 
+  /**
+   * Get a link to the interactive scoring calculator with the metric values.
+   * @param {LH.ReportResult.AuditRef[]} auditRefs
+   * @return {string}
+   */
+  _getScoringCalculatorHref(auditRefs) {
+    const v5andv6metrics = auditRefs.filter(audit => audit.group === 'metrics');
+    const fci = auditRefs.find(audit => audit.id === 'first-cpu-idle');
+    const fmp = auditRefs.find(audit => audit.id === 'first-meaningful-paint');
+    if (fci) v5andv6metrics.push(fci);
+    if (fmp) v5andv6metrics.push(fmp);
+
+    const metricPairs = v5andv6metrics.map(audit => {
+      const value = audit.result.numericValue ? audit.result.numericValue.toString() : 'null';
+      return [audit.id, value];
+    });
+    const params = new URLSearchParams(metricPairs);
+    const url = new URL('https://googlechrome.github.io/lighthouse/scorecalc/');
+    url.hash = params.toString();
+    return url.href;
+  }
+
   /**
    * @param {LH.ReportResult.Category} category
    * @param {Object<string, LH.Result.ReportGroup>} groups
@@ -143,6 +165,12 @@ class PerformanceCategoryRenderer extends CategoryRenderer {
       const estValuesEl = this.dom.createChildOf(metricAuditsEl, 'div', 'lh-metrics__disclaimer');
       const disclaimerEl = this.dom.convertMarkdownLinkSnippets(strings.varianceDisclaimer);
       estValuesEl.appendChild(disclaimerEl);
+
+      // Add link to score calculator.
+      const calculatorLink = this.dom.createChildOf(estValuesEl, 'a', 'lh-calclink');
+      calculatorLink.target = '_blank';
+      calculatorLink.textContent = strings.calculatorLink;
+      calculatorLink.href = this._getScoringCalculatorHref(category.auditRefs);
     }
 
     metricAuditsEl.classList.add('lh-audit-group--metrics');

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

@@ -497,6 +497,8 @@ Util.i18n = null;
 Util.UIStrings = {
   /** Disclaimer shown to users below the metric values (First Contentful Paint, Time to Interactive, etc) to warn them that the numbers they see will likely change slightly the next time they run Lighthouse. */
   varianceDisclaimer: 'Values are estimated and may vary. The [performance score is calculated](https://web.dev/performance-scoring/) directly from these metrics.',
+  /** Text link pointing to an interactive calculator that explains Lighthouse scoring. The link text should be fairly short. */
+  calculatorLink: 'See calculator.',
   /** Column heading label for the listing of opportunity audits. Each audit title represents an opportunity. There are only 2 columns, so no strict character limit.  */
   opportunityResourceColumnLabel: 'Opportunity',
   /** Column heading label for the estimated page load savings of opportunity audits. Estimated Savings is the total amount of time (in seconds) that Lighthouse computed could be reduced from the total page load time, if the suggested action is taken. There are only 2 columns, so no strict character limit. */

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

@@ -92,6 +92,9 @@ describe('PerfCategoryRenderer', () => {
     assert.ok(disclamerLink, 'disclaimer contains coverted markdown link');
     const disclamerUrl = new URL(disclamerLink.href);
     assert.strictEqual(disclamerUrl.hostname, 'web.dev');
+    const calcLink = disclaimerEl.querySelector('a.lh-calclink');
+    assert.ok(calcLink, 'disclaimer contains scorecalc link');
+    assert.strictEqual(new URL(calcLink.href).hostname, 'googlechrome.github.io');
   });
 
   it('renders the failing performance opportunities', () => {
@@ -234,6 +237,34 @@ describe('PerfCategoryRenderer', () => {
     });
   });
 
+  describe('_getScoringCalculatorHref', () => {
+    it('creates a working link given some auditRefs', () => {
+      const href = renderer._getScoringCalculatorHref(category.auditRefs);
+      const url = new URL(href);
+      expect(url.hash.split('&')).toMatchInlineSnapshot(`
+        Array [
+          "#first-contentful-paint=3969.135",
+          "speed-index=4417",
+          "largest-contentful-paint=4927.278",
+          "interactive=4927.278",
+          "total-blocking-time=116.79800000000023",
+          "cumulative-layout-shift=0.42",
+          "first-cpu-idle=4927.278",
+          "first-meaningful-paint=3969.136",
+        ]
+      `);
+    });
+
+    it('uses null if the metric is missing its value', () => {
+      const categoryClone = JSON.parse(JSON.stringify(category));
+      const lcp = categoryClone.auditRefs.find(audit => audit.id === 'largest-contentful-paint');
+      lcp.result.numericValue = undefined;
+      lcp.result.score = null;
+      const href = renderer._getScoringCalculatorHref(categoryClone.auditRefs);
+      expect(href).toContain('largest-contentful-paint=null');
+    });
+  });
+
   // This is done all in CSS, but tested here.
   describe('metric description toggles', () => {
     let container;

lighthouse-core/test/results/sample_v2.json

@@ -5719,6 +5719,7 @@
   "i18n": {
     "rendererFormattedStrings": {
       "auditGroupExpandTooltip": "Show audits",
+      "calculatorLink": "See calculator.",
       "crcInitialNavigation": "Initial Navigation",
       "crcLongestDurationLabel": "Maximum critical path latency:",
       "dropdownCopyJSON": "Copy JSON",

proto/lighthouse-result.proto

@@ -438,6 +438,9 @@ message I18n {
 
     // Label for a row in a table that shows in what tool Lighthouse is being run (e.g. The lighthouse CLI, Chrome DevTools, Lightrider, WebPageTest, etc).
     string runtime_settings_channel = 44;
+
+    // Text link pointing to the Lighthouse scoring calculator. This link immediately follows a sentence stating the performance score is calculated from the perf metrics.
+    string calculator_link = 45;
   }
 
   // The message holding all formatted strings