core(largest-contentful-paint): add new metric

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 requestOrUndefined(LargestContentfulPaint, metricComputationData); // 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 && largestContentfulPaint.timing,
+      largestContentfulPaintTs: largestContentfulPaint && 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,
@@ -115,7 +120,7 @@ class Metrics extends Audit {
     const details = {
       type: 'debugdata',
       // TODO: Consider not nesting metrics under `items`.
-      items: [metrics],
+      items: [metrics, {invalidLcp: traceOfTab.invalidLcp}],
     };
 
     return {
@@ -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

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'
     );

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');
+
+class LargestContentfulPaint extends ComputedMetric {
+  /**
+   * @param {LH.Artifacts.MetricComputationData} data
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Artifacts.LanternMetric>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  static computeSimulatedMetric(data, context) {
+    throw new Error('Unimplemented');
+  }
+
+  /**
+   * @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);

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},

lighthouse-core/lib/minify-trace.js

@@ -64,6 +64,8 @@ const traceEventsToKeepInProcess = new Set([
   'firstMeaningfulPaintCandidate',
   'loadEventEnd',
   'domContentLoadedEventEnd',
+  'largestContentfulPaint::Invalidate',
+  'largestContentfulPaint::Candidate',
 ]);
 
 /**

lighthouse-core/lib/tracehouse/trace-processor.js

@@ -524,6 +524,28 @@ 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 undefined.
+    let largestContentfulPaint;
+    let invalidLcp = false;
+    // Iterate the events backwards.
+    for (let i = frameEvents.length - 1; i >= 0; i--) {
+      const e = frameEvents[i];
+      // If the event's timestamp is before the navigation start, stop.
+      if (e.ts <= navigationStart.ts) break;
+      // If the first lcp event is 'Invalidate', there is inconclusive data to determine LCP.
+      if (e.name === 'largestContentfulPaint::Invalidate') {
+        invalidLcp = true;
+        break;
+      }
+      // If the first lcp event is not 'Candidate', keep iterating.
+      if (e.name !== 'largestContentfulPaint::Candidate') continue;
+      // Found the last LCP candidate in the trace, let's use it.
+      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 +573,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 +589,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),
@@ -581,9 +605,11 @@ class TraceProcessor {
       firstPaintEvt: firstPaint,
       firstContentfulPaintEvt: firstContentfulPaint,
       firstMeaningfulPaintEvt: firstMeaningfulPaint,
+      largestContentfulPaintEvt: largestContentfulPaint,
       loadEvt: load,
       domContentLoadedEvt: domContentLoaded,
       fmpFellBack,
+      invalidLcp,
     };
   }
 }

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

@@ -1,5 +1,47 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Performance: metrics evaluates valid input (with lcp) correctly 1`] = `
+Object {
+  "estimatedInputLatency": 1324,
+  "estimatedInputLatencyTs": undefined,
+  "firstCPUIdle": 14907,
+  "firstCPUIdleTs": 1671236823075,
+  "firstContentfulPaint": 4702,
+  "firstContentfulPaintTs": 1671226617803,
+  "firstMeaningfulPaint": 4702,
+  "firstMeaningfulPaintTs": 1671226617803,
+  "interactive": 14907,
+  "interactiveTs": 1671236823075,
+  "largestContentfulPaint": 15024,
+  "largestContentfulPaintTs": 1671236939268,
+  "observedDomContentLoaded": 14907,
+  "observedDomContentLoadedTs": 1671236823075,
+  "observedFirstContentfulPaint": 4702,
+  "observedFirstContentfulPaintTs": 1671226617803,
+  "observedFirstMeaningfulPaint": 4702,
+  "observedFirstMeaningfulPaintTs": 1671226617803,
+  "observedFirstPaint": 4702,
+  "observedFirstPaintTs": 1671226617803,
+  "observedFirstVisualChange": 4685,
+  "observedFirstVisualChangeTs": 1671226600754,
+  "observedLargestContentfulPaint": 15024,
+  "observedLargestContentfulPaintTs": 1671236939268,
+  "observedLastVisualChange": 4685,
+  "observedLastVisualChangeTs": 1671226600754,
+  "observedLoad": 40464,
+  "observedLoadTs": 1671262379989,
+  "observedNavigationStart": 0,
+  "observedNavigationStartTs": 1671221915754,
+  "observedSpeedIndex": 5715,
+  "observedSpeedIndexTs": 1671227631023,
+  "observedTraceEnd": 44549,
+  "observedTraceEndTs": 1671266464483,
+  "speedIndex": 5715,
+  "speedIndexTs": 1671227630754,
+  "totalBlockingTime": 1935,
+}
+`;
+
 exports[`Performance: metrics evaluates valid input correctly 1`] = `
 Object {
   "estimatedInputLatency": 78,
@@ -12,6 +54,8 @@ Object {
   "firstMeaningfulPaintTs": undefined,
   "interactive": 3427,
   "interactiveTs": undefined,
+  "largestContentfulPaint": undefined,
+  "largestContentfulPaintTs": undefined,
   "observedDomContentLoaded": 560,
   "observedDomContentLoadedTs": 225414732309,
   "observedFirstContentfulPaint": 499,
@@ -22,6 +66,8 @@ Object {
   "observedFirstPaintTs": 225414670868,
   "observedFirstVisualChange": 520,
   "observedFirstVisualChangeTs": 225414692015,
+  "observedLargestContentfulPaint": undefined,
+  "observedLargestContentfulPaintTs": undefined,
   "observedLastVisualChange": 818,
   "observedLastVisualChangeTs": 225414990015,
   "observedLoad": 2199,

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

@@ -11,6 +11,9 @@ const TTIComputed = require('../../computed/metrics/interactive.js');
 const pwaTrace = require('../fixtures/traces/progressive-app-m60.json');
 const pwaDevtoolsLog = require('../fixtures/traces/progressive-app-m60.devtools.log.json');
 
+const lcpTrace = require('../fixtures/traces/lcp-m79.json');
+const lcpDevtoolsLog = require('../fixtures/traces/lcp-m79.devtools.log.json');
+
 /* eslint-env jest */
 
 describe('Performance: metrics', () => {
@@ -45,4 +48,19 @@ describe('Performance: metrics', () => {
     const result = await MetricsAudit.audit(artifacts, context);
     expect(result.details.items[0].interactive).toEqual(undefined);
   });
+
+  it('evaluates valid input (with lcp) correctly', async () => {
+    const artifacts = {
+      traces: {
+        [MetricsAudit.DEFAULT_PASS]: lcpTrace,
+      },
+      devtoolsLogs: {
+        [MetricsAudit.DEFAULT_PASS]: lcpDevtoolsLog,
+      },
+    };
+
+    const context = {settings: {throttlingMethod: 'devtools'}, computedCache: new Map()};
+    const result = await MetricsAudit.audit(artifacts, context);
+    expect(result.details.items[0]).toMatchSnapshot();
+  });
 });

lighthouse-core/test/computed/metrics/largest-contentful-paint-test.js

@@ -0,0 +1,32 @@
+/**
+ * @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 assert = require('assert');
+
+const LargestContentfulPaint = require('../../../computed/metrics/largest-contentful-paint.js'); // eslint-disable-line max-len
+const trace = require('../../fixtures/traces/lcp-m79.json');
+const devtoolsLog = require('../../fixtures/traces/lcp-m79.devtools.log.json');
+
+/* eslint-env jest */
+
+describe('Metrics: FCP', () => {
+  it('should error when computing a simulated value', async () => {
+    const settings = {throttlingMethod: 'simulate'};
+    const context = {settings, computedCache: new Map()};
+    const resultPromise = LargestContentfulPaint.request({trace, devtoolsLog, settings}, context);
+    await expect(resultPromise).rejects.toThrow();
+  });
+
+  it('should compute an observed value', async () => {
+    const settings = {throttlingMethod: 'provided'};
+    const context = {settings, computedCache: new Map()};
+    const result = await LargestContentfulPaint.request({trace, devtoolsLog, settings}, context);
+
+    assert.equal(Math.round(result.timing), 15024);
+    assert.equal(result.timestamp, 1671236939268);
+  });
+});

lighthouse-core/test/computed/trace-of-tab-test.js

@@ -122,6 +122,7 @@ describe('TraceOfTabComputed', () => {
         navigationStart: 0,
         traceEnd: 12539.872,
       },
+      invalidLcp: false,
     });
   });
 

lighthouse-core/test/lib/tracehouse/trace-processor-test.js

@@ -9,6 +9,7 @@ const TraceProcessor = require('../../../lib/tracehouse/trace-processor.js');
 
 const assert = require('assert');
 const fs = require('fs');
+const createTestTrace = require('../../create-test-trace.js');
 const pwaTrace = require('../../fixtures/traces/progressive-app.json');
 const badNavStartTrace = require('../../fixtures/traces/bad-nav-start-ts.json');
 const lateTracingStartedTrace = require('../../fixtures/traces/tracingstarted-after-navstart.json');
@@ -18,6 +19,7 @@ const noFMPtrace = require('../../fixtures/traces/no_fmp_event.json');
 const noFCPtrace = require('../../fixtures/traces/airhorner_no_fcp.json');
 const noNavStartTrace = require('../../fixtures/traces/no_navstart_event.json');
 const backgroundTabTrace = require('../../fixtures/traces/backgrounded-tab-missing-paints.json');
+const lcpTrace = require('../../fixtures/traces/lcp-m79.json');
 
 /* eslint-env jest */
 
@@ -322,6 +324,31 @@ describe('TraceProcessor', () => {
       });
     });
 
+    describe('finds correct LCP', () => {
+      it('if there was a tracingStartedInPage after the frame\'s navStart', () => {
+        const trace = TraceProcessor.computeTraceOfTab(lcpTrace);
+        assert.equal(trace.mainFrameIds.frameId, '906A10385298DD996B521026AF4DA204');
+        assert.equal(trace.navigationStartEvt.ts, 1671221915754);
+        assert.equal(trace.firstContentfulPaintEvt.ts, 1671226617803);
+        assert.equal(trace.largestContentfulPaintEvt.ts, 1671236939268);
+        assert.ok(!trace.invalidLcp);
+      });
+
+      it('invalidates if last event is ::Invalidate', () => {
+        const invalidLcpTrace = createTestTrace({navigationStart: 0, traceEnd: 2000});
+        const frame = invalidLcpTrace.traceEvents[0].args.frame;
+        const args = {frame};
+        const cat = 'loading,rail,devtools.timeline';
+        invalidLcpTrace.traceEvents.push(...[
+          {name: 'largestContentfulPaint::Candidate', cat, args, ts: 1000, duration: 10},
+          {name: 'largestContentfulPaint::Invalidate', cat, args, ts: 1100, duration: 10},
+        ]);
+        const trace = TraceProcessor.computeTraceOfTab(invalidLcpTrace);
+        assert.equal(trace.largestContentfulPaintEvt, undefined);
+        assert.ok(trace.invalidLcp);
+      });
+    });
+
     it('handles traces missing a paints (captured in background tab)', () => {
       const trace = TraceProcessor.computeTraceOfTab(backgroundTabTrace);
       assert.equal(trace.mainFrameIds.frameId, '0x53965941e30');