GoogleChrome · brendankenny · Oct 2, 2019 · Sep 20, 2019 · Sep 20, 2019 · Sep 20, 2019
diff --git a/lighthouse-core/audits/metrics.js b/lighthouse-core/audits/metrics.js
@@ -10,6 +10,7 @@ const TraceOfTab = require('../computed/trace-of-tab.js');
 const Speedline = require('../computed/speedline.js');
 const FirstContentfulPaint = require('../computed/metrics/first-contentful-paint.js');
 const FirstMeaningfulPaint = require('../computed/metrics/first-meaningful-paint.js');
+const LargestContentfulPaint = require('../computed/metrics/largest-contentful-paint.js');
 const FirstCPUIdle = require('../computed/metrics/first-cpu-idle.js');
 const Interactive = require('../computed/metrics/interactive.js');
 const SpeedIndex = require('../computed/metrics/speed-index.js');
@@ -40,7 +41,6 @@ class Metrics extends Audit {
     const devtoolsLog = artifacts.devtoolsLogs[Audit.DEFAULT_PASS];
     const metricComputationData = {trace, devtoolsLog, settings: context.settings};
 
-
     /**
      * @template TArtifacts
      * @template TReturn
@@ -56,6 +56,7 @@ class Metrics extends Audit {
     const speedline = await Speedline.request(trace, context);
     const firstContentfulPaint = await FirstContentfulPaint.request(metricComputationData, context);
     const firstMeaningfulPaint = await FirstMeaningfulPaint.request(metricComputationData, context);
+    const largestContentfulPaint = await LargestContentfulPaint.request(metricComputationData, context); // eslint-disable-line max-len
     const firstCPUIdle = await requestOrUndefined(FirstCPUIdle, metricComputationData);
     const interactive = await requestOrUndefined(Interactive, metricComputationData);
     const speedIndex = await requestOrUndefined(SpeedIndex, metricComputationData);
@@ -69,6 +70,8 @@ class Metrics extends Audit {
       firstContentfulPaintTs: firstContentfulPaint.timestamp,
       firstMeaningfulPaint: firstMeaningfulPaint.timing,
       firstMeaningfulPaintTs: firstMeaningfulPaint.timestamp,
+      largestContentfulPaint: largestContentfulPaint.timing,
+      largestContentfulPaintTs: largestContentfulPaint.timestamp,
       firstCPUIdle: firstCPUIdle && firstCPUIdle.timing,
       firstCPUIdleTs: firstCPUIdle && firstCPUIdle.timestamp,
       interactive: interactive && interactive.timing,
@@ -88,6 +91,8 @@ class Metrics extends Audit {
       observedFirstContentfulPaintTs: traceOfTab.timestamps.firstContentfulPaint,
       observedFirstMeaningfulPaint: traceOfTab.timings.firstMeaningfulPaint,
       observedFirstMeaningfulPaintTs: traceOfTab.timestamps.firstMeaningfulPaint,
+      observedLargestContentfulPaint: traceOfTab.timings.largestContentfulPaint,
+      observedLargestContentfulPaintTs: traceOfTab.timestamps.largestContentfulPaint,
       observedTraceEnd: traceOfTab.timings.traceEnd,
       observedTraceEndTs: traceOfTab.timestamps.traceEnd,
       observedLoad: traceOfTab.timings.load,
@@ -132,6 +137,8 @@ class Metrics extends Audit {
  * @property {number=} firstContentfulPaintTs
  * @property {number} firstMeaningfulPaint
  * @property {number=} firstMeaningfulPaintTs
+ * @property {number} largestContentfulPaint
+ * @property {number=} largestContentfulPaintTs
  * @property {number=} firstCPUIdle
  * @property {number=} firstCPUIdleTs
  * @property {number=} interactive
@@ -149,6 +156,8 @@ class Metrics extends Audit {
  * @property {number} observedFirstContentfulPaintTs
  * @property {number=} observedFirstMeaningfulPaint
  * @property {number=} observedFirstMeaningfulPaintTs
+ * @property {number=} observedLargestContentfulPaint
+ * @property {number=} observedLargestContentfulPaintTs
  * @property {number=} observedTraceEnd
  * @property {number=} observedTraceEndTs
  * @property {number=} observedLoad

diff --git a/lighthouse-core/audits/metrics/largest-contentful-paint.js b/lighthouse-core/audits/metrics/largest-contentful-paint.js
@@ -0,0 +1,73 @@
+/**
+ * @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 i18n = require('../../lib/i18n/i18n.js');
+const ComputedLcp = require('../../computed/metrics/largest-contentful-paint.js');
+
+const UIStrings = {
+  /** The name of the metric that marks the time at which the largest text or image is painted by the browser. Shown to users as the label for the numeric metric value. Ideally fits within a ~40 character limit. */
+  title: 'Largest Contentful Paint',
+  /** Description of the Largest Contentful Paint (LCP) metric, which marks the time at which the largest text or image is painted by the browser. This 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: 'Largest Contentful Paint marks the time at which the first text or image is ' +
+      `painted. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/largest-contentful-paint).`,
+};
+
+const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+class LargestContentfulPaint extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'largest-contentful-paint',
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      scoreDisplayMode: Audit.SCORING_MODES.NUMERIC,
+      requiredArtifacts: ['traces', 'devtoolsLogs'],
+    };
+  }
+
+  /**
+   * @return {LH.Audit.ScoreOptions}
+   */
+  static get defaultOptions() {
+    return {
+      // 75th and 95th percentiles HTTPArchive -> median and PODR
+      // https://bigquery.cloud.google.com/table/httparchive:lighthouse.2018_04_01_mobile?pli=1
+      // see https://www.desmos.com/calculator/2t1ugwykrl
+      scorePODR: 2000,
+      scoreMedian: 4000,
+    };
+  }
+
+  /**
+   * @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 devtoolsLog = artifacts.devtoolsLogs[Audit.DEFAULT_PASS];
+    const metricComputationData = {trace, devtoolsLog, settings: context.settings};
+    const metricResult = await ComputedLcp.request(metricComputationData, context);
+
+    return {
+      score: Audit.computeLogNormalScore(
+        metricResult.timing,
+        context.options.scorePODR,
+        context.options.scoreMedian
+      ),
+      numericValue: metricResult.timing,
+      displayValue: str_(i18n.UIStrings.seconds, {timeInMs: metricResult.timing}),
+    };
+  }
+}
+
+module.exports = LargestContentfulPaint;
+module.exports.UIStrings = UIStrings;
diff --git a/lighthouse-core/computed/metrics/lantern-first-meaningful-paint.js b/lighthouse-core/computed/metrics/lantern-first-meaningful-paint.js
@@ -38,7 +38,7 @@ class LanternFirstMeaningfulPaint extends LanternMetric {
     return LanternFirstContentfulPaint.getFirstPaintBasedGraph(
       dependencyGraph,
       fmp,
-      // See LanterFirstContentfulPaint's getOptimisticGraph implementation for a longer description
+      // See LanternFirstContentfulPaint's getOptimisticGraph implementation for a longer description
       // of why we exclude script initiated resources here.
       node => node.hasRenderBlockingPriority() && node.initiatorType !== 'script'
     );

diff --git a/lighthouse-core/computed/metrics/lantern-largest-contentful-paint.js b/lighthouse-core/computed/metrics/lantern-largest-contentful-paint.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 makeComputedArtifact = require('../computed-artifact.js');
+const LanternMetric = require('./lantern-metric.js');
+const LHError = require('../../lib/lh-error.js');
+const LanternFirstContentfulPaint = require('./lantern-first-contentful-paint.js');
+
+/** @typedef {import('../../lib/dependency-graph/base-node.js').Node} Node */
+
+class LanternLargestContentfulPaint extends LanternMetric {
+  /**
+   * @return {LH.Gatherer.Simulation.MetricCoefficients}
+   */
+  static get COEFFICIENTS() {
+    return {
+      intercept: 0,
+      optimistic: 0.5,
+      pessimistic: 0.5,
+    };
+  }
+
+  /**
+   * TODO: Validate.
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.TraceOfTab} traceOfTab
+   * @return {Node}
+   */
+  static getOptimisticGraph(dependencyGraph, traceOfTab) {
+    const lcp = traceOfTab.timestamps.largestContentfulPaint;
+    if (!lcp) {
+      throw new LHError(LHError.errors.NO_LCP);
+    }
+
+    return LanternFirstContentfulPaint.getFirstPaintBasedGraph(
+      dependencyGraph,
+      lcp,
+      // See LanternFirstContentfulPaint's getOptimisticGraph implementation for a longer description
+      // of why we exclude script initiated resources here.
+      node => node.hasRenderBlockingPriority() && node.initiatorType !== 'script'
+    );
+  }
+
+  /**
+   * TODO: Validate.
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.TraceOfTab} traceOfTab
+   * @return {Node}
+   */
+  static getPessimisticGraph(dependencyGraph, traceOfTab) {
+    const lcp = traceOfTab.timestamps.largestContentfulPaint;
+    if (!lcp) {
+      throw new LHError(LHError.errors.NO_LCP);
+    }
+
+    return LanternFirstContentfulPaint.getFirstPaintBasedGraph(
+      dependencyGraph,
+      lcp,
+      node => node.hasRenderBlockingPriority(),
+      // For pessimistic LCP we'll include *all* layout nodes
+      node => node.didPerformLayout()
+    );
+  }
+
+  /**
+   * @param {LH.Artifacts.MetricComputationDataInput} data
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Artifacts.LanternMetric>}
+   */
+  static async compute_(data, context) {
+    const fcpResult = await LanternFirstContentfulPaint.request(data, context);
+    const metricResult = await this.computeMetricWithGraphs(data, context);
+    metricResult.timing = Math.max(metricResult.timing, fcpResult.timing);
+    return metricResult;
+  }
+}
+
+module.exports = makeComputedArtifact(LanternLargestContentfulPaint);
diff --git a/lighthouse-core/computed/metrics/largest-contentful-paint.js b/lighthouse-core/computed/metrics/largest-contentful-paint.js
@@ -0,0 +1,41 @@
+/**
+ * @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 ComputedMetric = require('./metric.js');
+const LHError = require('../../lib/lh-error.js');
+const LanternLargestContentfulPaint = require('./lantern-largest-contentful-paint.js');
+
+class LargestContentfulPaint extends ComputedMetric {
+  /**
+   * @param {LH.Artifacts.MetricComputationData} data
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Artifacts.LanternMetric>}
+   */
+  static computeSimulatedMetric(data, context) {
+    return LanternLargestContentfulPaint.request(data, context);
+  }
+
+  /**
+   * @param {LH.Artifacts.MetricComputationData} data
+   * @return {Promise<LH.Artifacts.Metric>}
+   */
+  static async computeObservedMetric(data) {
+    const {traceOfTab} = data;
+    if (!traceOfTab.timestamps.largestContentfulPaint) {
+      throw new LHError(LHError.errors.NO_LCP);
+    }
+
+    return {
+      // LCP established as existing, so cast
+      timing: /** @type {number} */ (traceOfTab.timings.largestContentfulPaint),
+      timestamp: traceOfTab.timestamps.largestContentfulPaint,
+    };
+  }
+}
+
+module.exports = makeComputedArtifact(LargestContentfulPaint);
diff --git a/lighthouse-core/lib/i18n/locales/en-US.json b/lighthouse-core/lib/i18n/locales/en-US.json
@@ -806,6 +806,12 @@
   "lighthouse-core/audits/metrics/interactive.js | title": {
     "message": "Time to Interactive"
   },
+  "lighthouse-core/audits/metrics/largest-contentful-paint.js | description": {
+    "message": "Largest Contentful Paint marks the time at which the first text or image is painted. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/largest-contentful-paint)."
+  },
+  "lighthouse-core/audits/metrics/largest-contentful-paint.js | title": {
+    "message": "Largest Contentful Paint"
+  },
   "lighthouse-core/audits/metrics/max-potential-fid.js | description": {
     "message": "The maximum potential First Input Delay that your users could experience is the duration, in milliseconds, of the longest task. [Learn more](https://developers.google.com/web/updates/2018/05/first-input-delay)."
   },

diff --git a/lighthouse-core/lib/i18n/locales/en-XL.json b/lighthouse-core/lib/i18n/locales/en-XL.json
@@ -806,6 +806,12 @@
   "lighthouse-core/audits/metrics/interactive.js | title": {
     "message": "T̂ím̂é t̂ó Îńt̂ér̂áĉt́îv́ê"
   },
+  "lighthouse-core/audits/metrics/largest-contentful-paint.js | description": {
+    "message": "L̂ár̂ǵêśt̂ Ćôńt̂én̂t́f̂úl̂ Ṕâín̂t́ m̂ár̂ḱŝ t́ĥé t̂ím̂é ât́ ŵh́îćĥ t́ĥé f̂ír̂śt̂ t́êx́t̂ ór̂ ím̂áĝé îś p̂áîńt̂éd̂. [Ĺêár̂ń m̂ór̂é](https://developers.google.com/web/tools/lighthouse/audits/largest-contentful-paint)."
+  },
+  "lighthouse-core/audits/metrics/largest-contentful-paint.js | title": {
+    "message": "L̂ár̂ǵêśt̂ Ćôńt̂én̂t́f̂úl̂ Ṕâín̂t́"
+  },
   "lighthouse-core/audits/metrics/max-potential-fid.js | description": {
     "message": "T̂h́ê ḿâx́îḿûḿ p̂ót̂én̂t́îál̂ F́îŕŝt́ Îńp̂út̂ D́êĺâý t̂h́ât́ ŷóûŕ ûśêŕŝ ćôúl̂d́ êx́p̂ér̂íêńĉé îś t̂h́ê d́ûŕât́îón̂, ín̂ ḿîĺl̂íŝéĉón̂d́ŝ, óf̂ t́ĥé l̂ón̂ǵêśt̂ t́âśk̂. [Ĺêár̂ń m̂ór̂é](https://developers.google.com/web/updates/2018/05/first-input-delay)."
   },

diff --git a/lighthouse-core/lib/lh-error.js b/lighthouse-core/lib/lh-error.js
@@ -253,6 +253,10 @@ const ERRORS = {
     code: 'NO_FMP',
     message: UIStrings.badTraceRecording,
   },
+  NO_LCP: {
+    code: 'NO_LCP',
+    message: UIStrings.badTraceRecording,
+  },
 
   // TTI calculation failures
   FMP_TOO_LATE_FOR_FCPUI: {code: 'FMP_TOO_LATE_FOR_FCPUI', message: UIStrings.pageLoadTookTooLong},

diff --git a/lighthouse-core/lib/tracehouse/trace-processor.js b/lighthouse-core/lib/tracehouse/trace-processor.js
@@ -524,6 +524,19 @@ class TraceProcessor {
       firstMeaningfulPaint = lastCandidate;
     }
 
+    // LCP comes from the latest `largestContentfulPaint::Candidate`, but it can be invalidated
+    // by a `largestContentfulPaint::Invalidate` event. In the case that the last candidate is
+    // invalidated, the value will be null.
+    let largestContentfulPaint;
+    for (let i = frameEvents.length - 1; i >= 0; i--) {
+      const e = frameEvents[i];
+      if (e.ts <= navigationStart.ts) break;
+      if (e.name === 'largestContentfulPaint::Invalidate') break;
+      if (e.name !== 'largestContentfulPaint::Candidate') continue;
+      largestContentfulPaint = e;
+      break;
+    }
+
     const load = frameEvents.find(e => e.name === 'loadEventEnd' && e.ts > navigationStart.ts);
     const domContentLoaded = frameEvents.find(
       e => e.name === 'domContentLoadedEventEnd' && e.ts > navigationStart.ts
@@ -551,6 +564,7 @@ class TraceProcessor {
       firstPaint: getTimestamp(firstPaint),
       firstContentfulPaint: getTimestamp(firstContentfulPaint),
       firstMeaningfulPaint: getTimestamp(firstMeaningfulPaint),
+      largestContentfulPaint: getTimestamp(largestContentfulPaint),
       traceEnd: fakeEndOfTraceEvt.ts,
       load: getTimestamp(load),
       domContentLoaded: getTimestamp(domContentLoaded),
@@ -566,6 +580,7 @@ class TraceProcessor {
       firstPaint: maybeGetTiming(timestamps.firstPaint),
       firstContentfulPaint: maybeGetTiming(timestamps.firstContentfulPaint),
       firstMeaningfulPaint: maybeGetTiming(timestamps.firstMeaningfulPaint),
+      largestContentfulPaint: maybeGetTiming(timestamps.largestContentfulPaint),
       traceEnd: getTiming(timestamps.traceEnd),
       load: maybeGetTiming(timestamps.load),
       domContentLoaded: maybeGetTiming(timestamps.domContentLoaded),