core: add metric savings to audit result

core/audits/audit.js

@@ -410,6 +410,7 @@ class Audit {
       warnings: product.warnings,
 
       details: product.details,
+      metricSavings: product.metricSavings,
     };
   }
 }

core/audits/third-party-summary.js

@@ -252,6 +252,9 @@ class ThirdPartySummary extends Audit {
         timeInMs: overallSummary.wastedMs,
       }),
       details,
+      metricSavings: {
+        TBT: overallSummary.wastedMs,
+      },
     };
   }
 }

core/test/fixtures/fraggle-rock/reports/sample-flow-result.json

@@ -1477,6 +1477,9 @@
                 "wastedMs": 0
               },
               "isEntityGrouped": true
+            },
+            "metricSavings": {
+              "TBT": 0
             }
           },
           "third-party-facades": {
@@ -8679,6 +8682,9 @@
                 "wastedMs": 0
               },
               "isEntityGrouped": true
+            },
+            "metricSavings": {
+              "TBT": 0
             }
           },
           "layout-shift-elements": {
@@ -17324,6 +17330,9 @@
                 }
               ],
               "isEntityGrouped": true
+            },
+            "metricSavings": {
+              "TBT": 0
             }
           },
           "third-party-facades": {

core/test/results/sample_v2.json

@@ -2236,6 +2236,9 @@
           "wastedMs": 0
         },
         "isEntityGrouped": true
+      },
+      "metricSavings": {
+        "TBT": 0
       }
     },
     "third-party-facades": {

types/audit.d.ts

@@ -18,6 +18,7 @@ declare module Audit {
   export type Result = AuditResult.Result;
   export type ScoreDisplayMode = AuditResult.ScoreDisplayMode;
   export type ScoreDisplayModes = AuditResult.ScoreDisplayModes;
+  export type MetricSavings = AuditResult.MetricSavings;
 
   type Context = Util.Immutable<{
     /** audit options */
@@ -81,6 +82,8 @@ declare module Audit {
     details?: AuditDetails;
     /** If an audit encounters unusual execution circumstances, strings can be put in this optional array to add top-level warnings to the LHR. */
     runWarnings?: Array<IcuMessage>;
+    /** Estimates of how much this audit affects various performance metrics. Values will be in the unit of the respective metrics. */
+    metricSavings?: MetricSavings;
   }
 
   /** The Audit.Product type for audits that do not return a `numericValue`. */

types/lhr/audit-result.d.ts

@@ -24,6 +24,14 @@ interface ScoreDisplayModes {
 
 type ScoreDisplayMode = ScoreDisplayModes[keyof ScoreDisplayModes];
 
+interface MetricSavings {
+  LCP?: number;
+  FCP?: number;
+  CLS?: number;
+  TBT?: number;
+  INP?: number;
+}
+
 /** Audit result returned in Lighthouse report. All audits offer a description and score of 0-1. */
 export interface Result {
   displayValue?: string;
@@ -50,6 +58,8 @@ export interface Result {
   id: string;
   /** A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit; markdown links supported. */
   description: string;
+  /** Estimates of how much this audit affects various performance metrics. Values will be in the unit of the respective metrics. */
+  metricSavings?: MetricSavings;
   /** A numeric value that has a meaning specific to the audit, e.g. the number of nodes in the DOM or the timestamp of a specific load event. More information can be found in the audit details, if present. */
   numericValue?: number;
   /** The unit of `numericValue`, used when the consumer wishes to convert numericValue to a display string. */