GoogleChrome · devtools-bot · Feb 28, 2020 · Feb 25, 2019 · Mar 19, 2019 · May 23, 2019
diff --git a/lighthouse-core/audits/metrics/cumulative-layout-shift.js b/lighthouse-core/audits/metrics/cumulative-layout-shift.js
@@ -0,0 +1,81 @@
+/**
+ * @license Copyright 2019 Google Inc. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const Audit = require('../audit.js');
+const ComputedCLS = require('../../computed/metrics/cumulative-layout-shift.js');
+const i18n = require('../../lib/i18n/i18n.js');
+
+const UIStrings = {
+  /** The name of the metric "Cumulative Layout Shift" that indicates how much the page changes its layout while it loads. If big segments of the page shift their location during load, the Cumulative Layout Shift will be higher. Shown to users as the label for the numeric metric value. Ideally fits within a ~40 character limit. */
+  title: 'Cumulative Layout Shift',
+  // TODO(paulirish): improve this description.
+  /** Description of the Cumulative Layout Shift metric that indicates how much the page changes its layout while it loads. If big segments of the page shift their location during load, the Cumulative Layout Shift will be higher. This description is displayed within a tooltip when the user hovers on the metric name to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */
+  description: 'The more the page\'s layout changes during its load, the higher the ' +
+      'Cumulative Layout Shift. ' +
+      'Perfectly solid == 0. Unpleasant experience >= 0.50.',
+};
+
+const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+/**
+ * @fileoverview This metric represents the amount of visual shifting of DOM elements during page load.
+ */
+class CumulativeLayoutShift extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'cumulative-layout-shift',
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      scoreDisplayMode: Audit.SCORING_MODES.NUMERIC,
+      requiredArtifacts: ['traces'],
+    };
+  }
+
+  /**
+   * @return {LH.Audit.ScoreOptions}
+   */
+  static get defaultOptions() {
+    return {
+      // TODO(paulirish): Calibrate these
+      scorePODR: 0.1,
+      scoreMedian: 0.5,
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    const trace = artifacts.traces[Audit.DEFAULT_PASS];
+    const metricResult = await ComputedCLS.request(trace, context);
+
+    /** @type {LH.Audit.Details.DebugData} */
+    const details = {
+      type: 'debugdata',
+      items: [metricResult.debugInfo],
+    };
+
+    return {
+      score: Audit.computeLogNormalScore(
+        metricResult.value,
+        context.options.scorePODR,
+        context.options.scoreMedian
+      ),
+      numericValue: metricResult.value,
+      displayValue: metricResult.value.toLocaleString(context.settings.locale),
+      details,
+    };
+  }
+}
+
+module.exports = CumulativeLayoutShift;
+module.exports.UIStrings = UIStrings;
diff --git a/lighthouse-core/computed/metrics/cumulative-layout-shift.js b/lighthouse-core/computed/metrics/cumulative-layout-shift.js
@@ -0,0 +1,61 @@
+/**
+ * @license Copyright 2019 Google Inc. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+const makeComputedArtifact = require('../computed-artifact.js');
+const TraceOfTab = require('../trace-of-tab.js');
+const LHError = require('../../lib/lh-error.js');
+
+class CumulativeLayoutShift {
+  /**
+   * @param {LH.Trace} trace
+   * @param {LH.Audit.Context} context
+   * @return {Promise<{value: number, debugInfo: Record<string,boolean> | null}>}
+   */
+  static async compute_(trace, context) {
+    const traceOfTab = await TraceOfTab.request(trace, context);
+
+    // Find the last LayoutShift event, if any.
+    let finalLayoutShift;
+    for (let i = traceOfTab.mainThreadEvents.length - 1; i >= 0; i--) {
+      const evt = traceOfTab.mainThreadEvents[i];
+      if (evt.name === 'LayoutShift' && evt.args && evt.args.data && evt.args.data.is_main_frame) {
+        finalLayoutShift = evt;
+        break;
+      }
+    }
+
+    const finalLayoutShiftTraceEventFound = !!finalLayoutShift;
+    // tdresser sez: In about 10% of cases, layout instability is 0, and there will be no trace events.
+    // TODO: Validate that. http://crbug.com/1003459
-    // TODO: Validate that. http://crbug.com/1003459
+    // TODO(http://crbug.com/1003459): Validate that.
-    // TODO: Validate that. http://crbug.com/1003459
+    // TODO(http://crbug.com/1003459): Validate that.
+    if (!finalLayoutShift) {
+      return {
+        value: 0,
+        debugInfo: {
+          finalLayoutShiftTraceEventFound,
+        },
+      };
+    }
+
+    const cumulativeLayoutShift =
+      finalLayoutShift.args &&
+      finalLayoutShift.args.data &&
+      finalLayoutShift.args.data.cumulative_score;
+
+    if (cumulativeLayoutShift === undefined) {
+      throw new LHError(LHError.errors.LAYOUT_SHIFT_MISSING_DATA);
+    }
+
+    return {
+      value: cumulativeLayoutShift,
+      debugInfo: {
+        finalLayoutShiftTraceEventFound,
+      },
+    };
+  }
+}
+
+module.exports = makeComputedArtifact(CumulativeLayoutShift);
diff --git a/lighthouse-core/computed/metrics/timing-summary.js b/lighthouse-core/computed/metrics/timing-summary.js
@@ -12,6 +12,7 @@ const FirstMeaningfulPaint = require('./first-meaningful-paint.js');
 const LargestContentfulPaint = require('./largest-contentful-paint.js');
 const FirstCPUIdle = require('./first-cpu-idle.js');
 const Interactive = require('./interactive.js');
+const CumulativeLayoutShift = require('./cumulative-layout-shift.js');
 const SpeedIndex = require('./speed-index.js');
 const EstimatedInputLatency = require('./estimated-input-latency.js');
 const MaxPotentialFID = require('./max-potential-fid.js');
@@ -45,6 +46,7 @@ class TimingSummary {
     const largestContentfulPaint = await requestOrUndefined(LargestContentfulPaint, metricComputationData); // eslint-disable-line max-len
     const firstCPUIdle = await requestOrUndefined(FirstCPUIdle, metricComputationData);
     const interactive = await requestOrUndefined(Interactive, metricComputationData);
+    const cumulativeLayoutShift = await requestOrUndefined(CumulativeLayoutShift, trace);
     const maxPotentialFID = await requestOrUndefined(MaxPotentialFID, metricComputationData);
     const speedIndex = await requestOrUndefined(SpeedIndex, metricComputationData);
     const estimatedInputLatency = await EstimatedInputLatency.request(metricComputationData, context); // eslint-disable-line max-len
@@ -69,6 +71,8 @@ class TimingSummary {
       estimatedInputLatencyTs: estimatedInputLatency.timestamp,
       totalBlockingTime: totalBlockingTime.timing,
       maxPotentialFID: maxPotentialFID && maxPotentialFID.timing,
+      cumulativeLayoutShift: cumulativeLayoutShift && cumulativeLayoutShift.value !== null ?
+        cumulativeLayoutShift.value : undefined,
 
       // Include all timestamps of interest from trace of tab
       observedNavigationStart: traceOfTab.timings.navigationStart,
@@ -87,6 +91,8 @@ class TimingSummary {
       observedLoadTs: traceOfTab.timestamps.load,
       observedDomContentLoaded: traceOfTab.timings.domContentLoaded,
       observedDomContentLoadedTs: traceOfTab.timestamps.domContentLoaded,
+      observedCumulativeLayoutShift: traceOfTab.timings.cumulativeLayoutShift,
+      observedCumulativeLayoutShiftTs: traceOfTab.timestamps.cumulativeLayoutShift,
 
       // Include some visual metrics from speedline
       observedFirstVisualChange: speedline.first,

diff --git a/lighthouse-core/config/default-config.js b/lighthouse-core/config/default-config.js
@@ -186,6 +186,7 @@ const defaultConfig = {
     'metrics/estimated-input-latency',
     'metrics/total-blocking-time',
     'metrics/max-potential-fid',
+    'metrics/cumulative-layout-shift',
     'errors-in-console',
     'time-to-first-byte',
     'metrics/first-cpu-idle',
@@ -389,6 +390,7 @@ const defaultConfig = {
         {id: 'interactive', weight: 5, group: 'metrics'},
         {id: 'first-cpu-idle', weight: 2, group: 'metrics'},
         {id: 'max-potential-fid', weight: 0, group: 'metrics'},
+        {id: 'cumulative-layout-shift', weight: 0}, // intentionally left out of metrics so it won't be displayed
         {id: 'estimated-input-latency', weight: 0}, // intentionally left out of metrics so it won't be displayed
         {id: 'total-blocking-time', weight: 0}, // intentionally left out of metrics so it won't be displayed
         {id: 'render-blocking-resources', weight: 0, group: 'load-opportunities'},

diff --git a/lighthouse-core/gather/driver.js b/lighthouse-core/gather/driver.js
@@ -100,6 +100,9 @@ class Driver {
       // Used instead of 'toplevel' in Chrome 71+
       'disabled-by-default-lighthouse',
 
+      // Used for Cumulative Layout Shift metric
+      'loading',
+
       // All compile/execute events are captured by parent events in devtools.timeline..
       // But the v8 category provides some nice context for only <0.5% of the trace size
       'v8',

diff --git a/lighthouse-core/lib/i18n/locales/en-US.json b/lighthouse-core/lib/i18n/locales/en-US.json
@@ -839,6 +839,12 @@
   "lighthouse-core/audits/manual/pwa-page-transitions.js | title": {
     "message": "Page transitions don't feel like they block on the network"
   },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | description": {
+    "message": "The more the page's layout changes during its load, the higher the Cumulative Layout Shift. Perfectly solid == 0. Unpleasant experience >= 0.50."
+  },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | title": {
+    "message": "Cumulative Layout Shift"
+  },
   "lighthouse-core/audits/metrics/estimated-input-latency.js | description": {
     "message": "Estimated Input Latency is an estimate of how long your app takes to respond to user input, in milliseconds, during the busiest 5s window of page load. If your latency is higher than 50 ms, users may perceive your app as laggy. [Learn more](https://web.dev/estimated-input-latency)."
   },

diff --git a/lighthouse-core/lib/i18n/locales/en-XL.json b/lighthouse-core/lib/i18n/locales/en-XL.json
@@ -839,6 +839,12 @@
   "lighthouse-core/audits/manual/pwa-page-transitions.js | title": {
     "message": "P̂áĝé t̂ŕâńŝít̂íôńŝ d́ôń't̂ f́êél̂ ĺîḱê t́ĥéŷ b́l̂óĉḱ ôń t̂h́ê ńêt́ŵór̂ḱ"
   },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | description": {
+    "message": "T̂h́ê ḿôŕê t́ĥé p̂áĝé'ŝ ĺâýôút̂ ćĥán̂ǵêś d̂úr̂ín̂ǵ ît́ŝ ĺôád̂, t́ĥé ĥíĝh́êŕ t̂h́ê Ćûḿûĺât́îv́ê Ĺâýôút̂ Śĥíf̂t́. P̂ér̂f́êćt̂ĺŷ śôĺîd́ == 0. Ûńp̂ĺêáŝán̂t́ êx́p̂ér̂íêńĉé >= 0.50."
+  },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | title": {
+    "message": "Ĉúm̂úl̂át̂ív̂é L̂áŷóût́ Ŝh́îf́t̂"
+  },
   "lighthouse-core/audits/metrics/estimated-input-latency.js | description": {
     "message": "Êśt̂ím̂át̂éd̂ Ín̂ṕût́ L̂át̂én̂ćŷ íŝ án̂ éŝt́îḿât́ê óf̂ h́ôẃ l̂ón̂ǵ ŷóûŕ âṕp̂ t́âḱêś t̂ó r̂éŝṕôńd̂ t́ô úŝér̂ ín̂ṕût́, îń m̂íl̂ĺîśêćôńd̂ś, d̂úr̂ín̂ǵ t̂h́ê b́ûśîéŝt́ 5ŝ ẃîńd̂óŵ óf̂ ṕâǵê ĺôád̂. Íf̂ ýôúr̂ ĺât́êńĉý îś ĥíĝh́êŕ t̂h́âń 50 m̂ś, ûśêŕŝ ḿâý p̂ér̂ćêív̂é ŷóûŕ âṕp̂ áŝ ĺâǵĝý. [L̂éâŕn̂ ḿôŕê](https://web.dev/estimated-input-latency)."
   },

diff --git a/lighthouse-core/lib/lh-error.js b/lighthouse-core/lib/lh-error.js
@@ -254,6 +254,11 @@ const ERRORS = {
     code: 'NO_LCP',
     message: UIStrings.badTraceRecording,
   },
+  /** Layout Shift trace events are found but without data */
+  LAYOUT_SHIFT_MISSING_DATA: {
+    code: 'LAYOUT_SHIFT_MISSING_DATA',
+    message: UIStrings.badTraceRecording,
+  },
 
   // TTI calculation failures
   FMP_TOO_LATE_FOR_FCPUI: {code: 'FMP_TOO_LATE_FOR_FCPUI', message: UIStrings.pageLoadTookTooLong},
@@ -376,6 +381,7 @@ const ERRORS = {
   },
 
   // Hey! When adding a new error type, update lighthouse-result.proto too.
+  // Only necessary for runtime errors, which come from artifacts or pageLoadErrors.
 };
 
 /** @type {Record<keyof typeof ERRORS, LighthouseErrorDefinition>} */

diff --git a/lighthouse-core/test/audits/__snapshots__/metrics-test.js.snap b/lighthouse-core/test/audits/__snapshots__/metrics-test.js.snap
@@ -2,6 +2,7 @@
 
 exports[`Performance: metrics evaluates valid input (with lcp) correctly 1`] = `
 Object {
+  "cumulativeLayoutShift": undefined,
   "estimatedInputLatency": 543,
   "estimatedInputLatencyTs": undefined,
   "firstCPUIdle": 3677,
@@ -15,6 +16,8 @@ Object {
   "largestContentfulPaint": 3343,
   "largestContentfulPaintTs": undefined,
   "maxPotentialFID": 1336,
+  "observedCumulativeLayoutShift": undefined,
+  "observedCumulativeLayoutShiftTs": undefined,
   "observedDomContentLoaded": 1513,
   "observedDomContentLoadedTs": 713038536140,
   "observedFirstContentfulPaint": 1122,
@@ -45,6 +48,7 @@ Object {
 
 exports[`Performance: metrics evaluates valid input correctly 1`] = `
 Object {
+  "cumulativeLayoutShift": undefined,
   "estimatedInputLatency": 78,
   "estimatedInputLatencyTs": undefined,
   "firstCPUIdle": 3351,
@@ -58,6 +62,8 @@ Object {
   "largestContentfulPaint": undefined,
   "largestContentfulPaintTs": undefined,
   "maxPotentialFID": 396,
+  "observedCumulativeLayoutShift": undefined,
+  "observedCumulativeLayoutShiftTs": undefined,
   "observedDomContentLoaded": 560,
   "observedDomContentLoadedTs": 225414732309,
   "observedFirstContentfulPaint": 499,

diff --git a/lighthouse-core/test/computed/metrics/timing-summary-test.js b/lighthouse-core/test/computed/metrics/timing-summary-test.js
@@ -18,6 +18,7 @@ describe('Timing summary', () => {
 
     expect(result.metrics).toMatchInlineSnapshot(`
 Object {
+  "cumulativeLayoutShift": undefined,
   "estimatedInputLatency": 77.79999999999995,
   "estimatedInputLatencyTs": undefined,
   "firstCPUIdle": 3351.3320000492968,
@@ -31,6 +32,8 @@ Object {
   "largestContentfulPaint": undefined,
   "largestContentfulPaintTs": undefined,
   "maxPotentialFID": 396.0000000000001,
+  "observedCumulativeLayoutShift": undefined,
+  "observedCumulativeLayoutShiftTs": undefined,
   "observedDomContentLoaded": 560.294,
   "observedDomContentLoadedTs": 225414732309,
   "observedFirstContentfulPaint": 498.87,

diff --git a/lighthouse-core/test/results/artifacts/defaultPass.trace.json b/lighthouse-core/test/results/artifacts/defaultPass.trace.json
@@ -14507,6 +14507,7 @@
   {"pid":75994,"tid":17667,"ts":185608247189,"ph":"X","cat":"toplevel","name":"MessageLoop::RunTask","args":{"src_file":"../../ipc/ipc_mojo_bootstrap.cc","src_func":"SendMessage"},"dur":30,"tdur":29,"tts":78797},
 
   {"_comment": "Manually added event to make sample lhr not error", "name":"largestContentfulPaint::Candidate", "pid":75994,"tid":17667,"ts":185608247190,"ph":"R","cat":"loading,rail,devtools.timeline", "args": {"frame": "0x44d2861df8"}},
+  {"_comment": "Manually added event to make test CLS", "name":"LayoutShift", "pid":75994,"tid":775,"ts":185608247190,"ph":"R","cat":"loading,rail,devtools.timeline", "args": {"frame": "0x44d2861df8", "data": {"is_main_frame": true, "cumulative_score": 0.42}}},
 
   {"pid":75994,"tid":17667,"ts":185608250604,"ph":"X","cat":"toplevel","name":"MessagePumpLibevent::OnLibeventNotification","args":{"src_file":"../../mojo/edk/system/channel_posix.cc","src_func":"StartOnIOThread"},"dur":29,"tdur":30,"tts":78849},
   {"pid":75994,"tid":17667,"ts":185608250671,"ph":"X","cat":"toplevel","name":"MessagePumpLibevent::OnLibeventNotification","args":{"src_file":"../../mojo/edk/system/channel_posix.cc","src_func":"StartOnIOThread"},"dur":25,"tdur":25,"tts":78903},

diff --git a/lighthouse-core/test/results/sample_v2.json b/lighthouse-core/test/results/sample_v2.json
@@ -218,6 +218,23 @@
       "numericValue": 122.537,
       "displayValue": "120 ms"
     },
+    "cumulative-layout-shift": {
+      "id": "cumulative-layout-shift",
+      "title": "Cumulative Layout Shift",
+      "description": "The more the page's layout changes during its load, the higher the Cumulative Layout Shift. Perfectly solid == 0. Unpleasant experience >= 0.50.",
+      "score": 0.59,
+      "scoreDisplayMode": "numeric",
+      "numericValue": 0.42,
+      "displayValue": "0.42",
+      "details": {
+        "type": "debugdata",
+        "items": [
+          {
+            "finalLayoutShiftTraceEventFound": true
+          }
+        ]
+      }
+    },
     "errors-in-console": {
       "id": "errors-in-console",
       "title": "Browser errors were logged to the console",
@@ -1271,6 +1288,7 @@
             "estimatedInputLatency": 16,
             "totalBlockingTime": 117,
             "maxPotentialFID": 123,
+            "cumulativeLayoutShift": 0,
             "observedNavigationStart": 0,
             "observedNavigationStartTs": 185603319912,
             "observedFirstPaint": 3969,
@@ -3528,6 +3546,10 @@
           "weight": 0,
           "group": "metrics"
         },
+        {
+          "id": "cumulative-layout-shift",
+          "weight": 0
+        },
         {
           "id": "estimated-input-latency",
           "weight": 0
@@ -4475,6 +4497,18 @@
         "duration": 100,
         "entryType": "measure"
       },
+      {
+        "startTime": 0,
+        "name": "lh:audit:cumulative-layout-shift",
+        "duration": 100,
+        "entryType": "measure"
+      },
+      {
+        "startTime": 0,
+        "name": "lh:computed:CumulativeLayoutShift",
+        "duration": 100,
+        "entryType": "measure"
+      },
       {
         "startTime": 0,
         "name": "lh:audit:errors-in-console",
@@ -5506,6 +5540,12 @@
       "lighthouse-core/audits/metrics/max-potential-fid.js | description": [
         "audits[max-potential-fid].description"
       ],
+      "lighthouse-core/audits/metrics/cumulative-layout-shift.js | title": [
+        "audits[cumulative-layout-shift].title"
+      ],
+      "lighthouse-core/audits/metrics/cumulative-layout-shift.js | description": [
+        "audits[cumulative-layout-shift].description"
+      ],
       "lighthouse-core/audits/errors-in-console.js | failureTitle": [
         "audits[errors-in-console].title"
       ],