core: add new CLS (all frames) to hidden metrics audit

lighthouse-cli/test/smokehouse/test-definitions/perf/expectations.js

@@ -335,6 +335,7 @@ module.exports = [
                 layoutShiftMaxSessionGap1sLimit5s: '>0',
                 layoutShiftMaxSliding1s: '>0',
                 layoutShiftMaxSliding300ms: '>0',
+                layoutShiftMaxSessionGap1sLimit5sAllFrames: '0.197 +/- 0.001',
               },
               {
                 lcpInvalidated: false,

lighthouse-core/audits/metrics.js

@@ -19,6 +19,7 @@ const DECIMAL_METRIC_KEYS = new Set([
   'layoutShiftMaxSessionGap1sLimit5s',
   'layoutShiftMaxSliding1s',
   'layoutShiftMaxSliding300ms',
+  'layoutShiftMaxSessionGap1sLimit5sAllFrames',
 ]);
 
 class Metrics extends Audit {

lighthouse-core/computed/layout-shift-variants.js

@@ -71,6 +71,40 @@ class LayoutShiftVariants {
     return maxScore;
   }
 
+  /**
+   * Calculates cumulative layout shifts per cluster (session) of LayoutShift
+   * events -- where a new cluster is created when there's a gap of more than
+   * 1000ms since the last LayoutShift event or the cluster is greater than
+   * 5000ms long -- and returns the max LayoutShift score found.
+   * @param {Array<LayoutShiftEvent>} layoutShiftEvents
+   * @return {number}
+   */
+  static newCumulativeLayoutShift(layoutShiftEvents) {
+    const gapMicroseconds = 1_000_000;
+    const limitMicroseconds = 5_000_000;
+    let maxScore = 0;
+    let currentClusterScore = 0;
+    let firstTs = Number.NEGATIVE_INFINITY;
+    let prevTs = Number.NEGATIVE_INFINITY;
+
+    for (const event of layoutShiftEvents) {
+      if (event.weightedScoreDelta === undefined) {
+        // TODO(bckenny): replace with an LHError when moving to AF by default.
+        return -1;
+      }
+
+      if (event.ts - firstTs > limitMicroseconds || event.ts - prevTs > gapMicroseconds) {
+        firstTs = event.ts;
+        currentClusterScore = 0;
+      }
+      prevTs = event.ts;
+      currentClusterScore += event.weightedScoreDelta;
+      maxScore = Math.max(maxScore, currentClusterScore);
+    }
+
+    return maxScore;
+  }
+
   /**
    * Returns the maximum cumulative layout shift in any `windowMs` ms window
    * (inclusive of bounds) in the trace.
@@ -141,19 +175,24 @@ class LayoutShiftVariants {
   /**
    * @param {LH.Trace} trace
    * @param {LH.Artifacts.ComputedContext} context
-   * @return {Promise<{avgSessionGap5s: number, maxSessionGap1s: number, maxSessionGap1sLimit5s: number, maxSliding1s: number, maxSliding300ms: number}>}
+   * @return {Promise<{avgSessionGap5s: number, maxSessionGap1s: number, maxSessionGap1sLimit5s: number, maxSliding1s: number, maxSliding300ms: number, layoutShiftMaxSessionGap1sLimit5sAllFrames: number}>}
    */
   static async compute_(trace, context) {
     const traceOfTab = await TraceOfTab.request(trace, context);
     const layoutShiftEvents = LayoutShiftVariants.getLayoutShiftEvents(traceOfTab.mainThreadEvents)
       .filter(e => e.isMainFrame); // Only main frame for now.
 
+    const layoutShiftEventsAllFrames =
+      LayoutShiftVariants.getLayoutShiftEvents(traceOfTab.frameTreeEvents);
+
     return {
       avgSessionGap5s: LayoutShiftVariants.avgSessionGap5s(layoutShiftEvents),
       maxSessionGap1s: LayoutShiftVariants.maxSession(layoutShiftEvents, 1000),
       maxSessionGap1sLimit5s: LayoutShiftVariants.maxSession(layoutShiftEvents, 1000, 5000),
       maxSliding1s: LayoutShiftVariants.maxSliding(layoutShiftEvents, 1000),
       maxSliding300ms: LayoutShiftVariants.maxSliding(layoutShiftEvents, 300),
+      // eslint-disable-next-line max-len
+      layoutShiftMaxSessionGap1sLimit5sAllFrames: LayoutShiftVariants.newCumulativeLayoutShift(layoutShiftEventsAllFrames),
     };
   }
 }

lighthouse-core/computed/metrics/timing-summary.js

@@ -135,6 +135,10 @@ class TimingSummary {
       layoutShiftMaxSessionGap1sLimit5s: layoutShiftVariants.maxSessionGap1sLimit5s,
       layoutShiftMaxSliding1s: layoutShiftVariants.maxSliding1s,
       layoutShiftMaxSliding300ms: layoutShiftVariants.maxSliding300ms,
+
+      // And new CLS (layoutShiftMaxSessionGap1sLimit5s) across all frames.
+      // eslint-disable-next-line max-len
+      layoutShiftMaxSessionGap1sLimit5sAllFrames: layoutShiftVariants.layoutShiftMaxSessionGap1sLimit5sAllFrames,
     };
     /** @type {Record<string,boolean>} */
     const debugInfo = {lcpInvalidated: traceOfTab.lcpInvalidated};

lighthouse-core/test/audits/__snapshots__/metrics-test.js.snap

@@ -23,6 +23,7 @@ Object {
   "layoutShiftAvgSessionGap5s": 0.0011656245471340055,
   "layoutShiftMaxSessionGap1s": 0.0011656245471340055,
   "layoutShiftMaxSessionGap1sLimit5s": 0.0011656245471340055,
+  "layoutShiftMaxSessionGap1sLimit5sAllFrames": -1,
   "layoutShiftMaxSliding1s": 0.0011656245471340055,
   "layoutShiftMaxSliding300ms": 0.0011656245471340055,
   "maxPotentialFID": 16,
@@ -85,6 +86,7 @@ Object {
   "layoutShiftAvgSessionGap5s": 0,
   "layoutShiftMaxSessionGap1s": 0,
   "layoutShiftMaxSessionGap1sLimit5s": 0,
+  "layoutShiftMaxSessionGap1sLimit5sAllFrames": 0,
   "layoutShiftMaxSliding1s": 0,
   "layoutShiftMaxSliding300ms": 0,
   "maxPotentialFID": 1336,
@@ -147,6 +149,7 @@ Object {
   "layoutShiftAvgSessionGap5s": 0,
   "layoutShiftMaxSessionGap1s": 0,
   "layoutShiftMaxSessionGap1sLimit5s": 0,
+  "layoutShiftMaxSessionGap1sLimit5sAllFrames": 0,
   "layoutShiftMaxSliding1s": 0,
   "layoutShiftMaxSliding300ms": 0,
   "maxPotentialFID": 198,
@@ -209,6 +212,7 @@ Object {
   "layoutShiftAvgSessionGap5s": 0,
   "layoutShiftMaxSessionGap1s": 0,
   "layoutShiftMaxSessionGap1sLimit5s": 0,
+  "layoutShiftMaxSessionGap1sLimit5sAllFrames": 0,
   "layoutShiftMaxSliding1s": 0,
   "layoutShiftMaxSliding300ms": 0,
   "maxPotentialFID": 396,

lighthouse-core/test/audits/metrics-test.js

@@ -160,6 +160,26 @@ describe('Performance: metrics', () => {
       layoutShiftMaxSessionGap1sLimit5s: expect.toBeApproximately(2.268816, 6),
       layoutShiftMaxSliding1s: expect.toBeApproximately(1.911799, 6),
       layoutShiftMaxSliding300ms: expect.toBeApproximately(1.436742, 6),
+      layoutShiftMaxSessionGap1sLimit5sAllFrames: expect.toBeApproximately(2.268816, 6),
+    });
+  });
+
+  it('evaluates new CLS correctly across all frames', async () => {
+    const artifacts = {
+      traces: {
+        [MetricsAudit.DEFAULT_PASS]: clsAllFramesTrace,
+      },
+      devtoolsLogs: {
+        [MetricsAudit.DEFAULT_PASS]: clsAllFramesDevtoolsLog,
+      },
+    };
+
+    const context = {settings: {throttlingMethod: 'provided'}, computedCache: new Map()};
+    const {details} = await MetricsAudit.audit(artifacts, context);
+    expect(details.items[0]).toMatchObject({
+      cumulativeLayoutShift: expect.toBeApproximately(0.001166, 6),
+      cumulativeLayoutShiftAllFrames: expect.toBeApproximately(0.027629, 6),
+      layoutShiftMaxSessionGap1sLimit5sAllFrames: expect.toBeApproximately(0.026463, 6),
     });
   });
 });