GoogleChrome · devtools-bot · Feb 28, 2020 · Feb 25, 2019 · Mar 19, 2019 · May 23, 2019
diff --git a/lighthouse-cli/test/cli/__snapshots__/index-test.js.snap b/lighthouse-cli/test/cli/__snapshots__/index-test.js.snap
@@ -51,6 +51,9 @@ Object {
     Object {
       "path": "metrics/max-potential-fid",
     },
+    Object {
+      "path": "metrics/cumulative-layout-shift",
+    },
     Object {
       "path": "errors-in-console",
     },
@@ -785,6 +788,10 @@ Object {
           "id": "max-potential-fid",
           "weight": 0,
         },
+        Object {
+          "id": "cumulative-layout-shift",
+          "weight": 0,
+        },
         Object {
           "id": "estimated-input-latency",
           "weight": 0,

diff --git a/lighthouse-core/audits/metrics/cumulative-layout-shift.js b/lighthouse-core/audits/metrics/cumulative-layout-shift.js
@@ -0,0 +1,82 @@
+/**
+ * @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',
+  /** 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: 'Cumulative Layout Shift is the sum of all layout shifts that occurred during a ' +
+      'page\'s load. A layout shift is any movement an element makes once it is visible to the ' +
+      'user. All layout shift is recorded, scored, and then aggregated into a cumulative score ' +
+      'between 0 and 1; 0 being a perfectly stable page, and >=0.5 being a highly shifting page.',
+};
+
+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.05,
+      scoreMedian: 0.4,
+    };
+  }
+
+  /**
+   * @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,
+      numericUnit: 'unitless',
+      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
@@ -188,6 +188,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',
@@ -394,6 +395,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
@@ -860,6 +860,12 @@
   "lighthouse-core/audits/maskable-icon.js | title": {
     "message": "Manifest has a maskable icon"
   },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | description": {
+    "message": "Cumulative Layout Shift is the sum of all layout shifts that occurred during a page's load. A layout shift is any movement an element makes once it is visible to the user. All layout shift is recorded, scored, and then aggregated into a cumulative score between 0 and 1; 0 being a perfectly stable page, and >=0.5 being a highly shifting page."
+  },
+  "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
@@ -860,6 +860,12 @@
   "lighthouse-core/audits/maskable-icon.js | title": {
     "message": "M̂án̂íf̂éŝt́ ĥáŝ á m̂áŝḱâb́l̂é îćôń"
   },
+  "lighthouse-core/audits/metrics/cumulative-layout-shift.js | description": {
+    "message": "Ĉúm̂úl̂át̂ív̂é L̂áŷóût́ Ŝh́îf́t̂ íŝ t́ĥé ŝúm̂ óf̂ ál̂ĺ l̂áŷóût́ ŝh́îf́t̂ś t̂h́ât́ ôćĉúr̂ŕêd́ d̂úr̂ín̂ǵ â ṕâǵê'ś l̂óâd́. Â ĺâýôút̂ śĥíf̂t́ îś âńŷ ḿôv́êḿêńt̂ án̂ él̂ém̂én̂t́ m̂ák̂éŝ ón̂ćê ít̂ íŝ v́îśîb́l̂é t̂ó t̂h́ê úŝér̂. Ál̂ĺ l̂áŷóût́ ŝh́îf́t̂ íŝ ŕêćôŕd̂éd̂, śĉór̂éd̂, án̂d́ t̂h́êń âǵĝŕêǵât́êd́ îńt̂ó â ćûḿûĺât́îv́ê śĉór̂é b̂ét̂ẃêén̂ 0 án̂d́ 1; 0 b̂éîńĝ á p̂ér̂f́êćt̂ĺŷ śt̂áb̂ĺê ṕâǵê, án̂d́ >=0.5 b̂éîńĝ á ĥíĝh́l̂ý ŝh́îf́t̂ín̂ǵ p̂áĝé."
+  },
+  "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": 0,
   "estimatedInputLatency": 543,
   "estimatedInputLatencyTs": undefined,
   "firstCPUIdle": 3677,
@@ -15,6 +16,8 @@ Object {
   "largestContentfulPaint": 3419,
   "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": 0,
   "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": 0,
   "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},