core: surface LCP element in a diagnostic audit

lighthouse-cli/test/cli/__snapshots__/index-test.js.snap

@@ -150,6 +150,9 @@ Object {
     Object {
       "path": "third-party-summary",
     },
+    Object {
+      "path": "largest-contentful-paint-element",
+    },
     Object {
       "path": "manual/pwa-cross-browser",
     },
@@ -935,6 +938,11 @@ Object {
           "id": "third-party-summary",
           "weight": 0,
         },
+        Object {
+          "group": "diagnostics",
+          "id": "largest-contentful-paint-element",
+          "weight": 0,
+        },
         Object {
           "group": "diagnostics",
           "id": "uses-http2",
@@ -1311,6 +1319,9 @@ Object {
         Object {
           "path": "accessibility",
         },
+        Object {
+          "path": "trace-elements",
+        },
       ],
       "loadFailureMode": "fatal",
       "networkQuietThresholdMs": 1000,

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

@@ -136,6 +136,21 @@ module.exports = [
             ],
           },
         },
+        'largest-contentful-paint-element': {
+          score: null,
+          displayValue: '1 element found',
+          details: {
+            items: [
+              {
+                node: {
+                  type: 'node',
+                  nodeLabel: 'img',
+                  path: '2,HTML,1,BODY,0,IMG',
+                },
+              },
+            ],
+          },
+        },
       },
     },
   },

lighthouse-core/audits/dobetterweb/dom-size.js

@@ -27,8 +27,6 @@ const UIStrings = {
     'and produce costly [layout reflows](https://developers.google.com/speed/articles/reflow). [Learn more](https://web.dev/dom-size).',
   /** Table column header for the type of statistic. These statistics describe how big the DOM is (count of DOM elements, children, depth). */
   columnStatistic: 'Statistic',
-  /** Table column header for the DOM element. Each DOM element is described with its HTML representation. */
-  columnElement: 'Element',
   /** Table column header for the observed value of the DOM statistic. */
   columnValue: 'Value',
   /** [ICU Syntax] Label for an audit identifying the number of DOM elements found in the page. */
@@ -92,7 +90,7 @@ class DOMSize extends Audit {
     /** @type {LH.Audit.Details.Table['headings']} */
     const headings = [
       {key: 'statistic', itemType: 'text', text: str_(UIStrings.columnStatistic)},
-      {key: 'element', itemType: 'code', text: str_(UIStrings.columnElement)},
+      {key: 'element', itemType: 'code', text: str_(i18n_.UIStrings.columnElement)},
       {key: 'value', itemType: 'numeric', text: str_(UIStrings.columnValue)},
     ];
 

lighthouse-core/audits/largest-contentful-paint-element.js

@@ -0,0 +1,78 @@
+/**
+ * @license Copyright 2020 The Lighthouse Authors. 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 UIStrings = {
+  /** Descriptive title of a diagnostic audit that provides the element that was determined to be the Largest Contentful Paint. */
+  title: 'Largest Contentful Paint element',
+  /** Description of a Lighthouse audit that tells the user that the element shown was determined to be the Largest Contentful Paint. */
+  description: 'This is the element that was identified as the Largest Contentful Paint. ' +
+    '[Learn More](https://web.dev/lighthouse-largest-contentful-paint)',
+  /** [ICU Syntax] Label for the audit identifying if an element was found. */
+  displayValue: `{itemCount, plural,
+    =1 {1 element found}
+    other {# elements found}
+    }`,
+};
+
+const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings);
+
+class LargestContentfulPaintElement extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'largest-contentful-paint-element',
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      scoreDisplayMode: Audit.SCORING_MODES.INFORMATIVE,
+      requiredArtifacts: ['TraceElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @return {LH.Audit.Product}
+   */
+  static audit(artifacts) {
+    const lcpElement =
+      artifacts.TraceElements.find(node => node.metricName === 'largest-contentful-paint');
+    const lcpElementDetails = [];
+    if (lcpElement) {
+      lcpElementDetails.push({
+        node: /** @type {LH.Audit.Details.NodeValue} */ ({
+          type: 'node',
+          path: lcpElement.devtoolsNodePath,
+          selector: lcpElement.selector,
+          nodeLabel: lcpElement.nodeLabel,
+          snippet: lcpElement.snippet,
+        }),
+      });
+    }
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      {key: 'node', itemType: 'node', text: str_(i18n.UIStrings.columnElement)},
+    ];
+
+    const details = Audit.makeTableDetails(headings, lcpElementDetails);
+
+    const displayValue = str_(UIStrings.displayValue, {itemCount: lcpElementDetails.length});
+
+    return {
+      score: 1,
+      displayValue,
+      details,
+    };
+  }
+}
+
+module.exports = LargestContentfulPaintElement;
+module.exports.UIStrings = UIStrings;

lighthouse-core/config/default-config.js

@@ -159,6 +159,7 @@ const defaultConfig = {
       'seo/robots-txt',
       'seo/tap-targets',
       'accessibility',
+      'trace-elements',
     ],
   },
   {
@@ -230,6 +231,7 @@ const defaultConfig = {
     'timing-budget',
     'resource-summary',
     'third-party-summary',
+    'largest-contentful-paint-element',
     'manual/pwa-cross-browser',
     'manual/pwa-page-transitions',
     'manual/pwa-each-page-has-url',
@@ -448,6 +450,7 @@ const defaultConfig = {
         {id: 'timing-budget', weight: 0, group: 'budgets'},
         {id: 'resource-summary', weight: 0, group: 'diagnostics'},
         {id: 'third-party-summary', weight: 0, group: 'diagnostics'},
+        {id: 'largest-contentful-paint-element', weight: 0, group: 'diagnostics'},
         {id: 'uses-http2', weight: 0, group: 'diagnostics'},
         {id: 'uses-passive-event-listeners', weight: 0, group: 'diagnostics'},
         {id: 'no-document-write', weight: 0, group: 'diagnostics'},

lighthouse-core/gather/gatherers/trace-elements.js

@@ -0,0 +1,105 @@
+/**
+ * @license Copyright 2020 The Lighthouse Authors. 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';
+
+/**
+ * @fileoverview
+ * This gatherer identifies the Largest Contentful Paint element from the trace. Since the trace only has the nodeId of the element,
+ * we temporarily add an attribute so that we can identify the element in the DOM.
+ */
+
+const Gatherer = require('./gatherer.js');
+const pageFunctions = require('../../lib/page-functions.js');
+const TraceProcessor = require('../../lib/tracehouse/trace-processor.js');
+
+const LH_ATTRIBUTE_MARKER = 'lhtemp';
+
+/**
+ * @param {string} attributeMarker
+ * @return {LH.Artifacts['TraceElements']}
+ */
+/* istanbul ignore next */
+function collectTraceElements(attributeMarker) {
+  /** @type {Array<HTMLElement>} */
+  // @ts-ignore - put into scope via stringification
+  const markedElements = getElementsInDocument('[' + attributeMarker + ']'); // eslint-disable-line no-undef
+  /** @type {LH.Artifacts['TraceElements']} */
+  const TraceElements = [];
+  for (const element of markedElements) {
+    const metricName = element.getAttribute(attributeMarker) || '';
+    element.removeAttribute(attributeMarker);
+    // @ts-ignore - put into scope via stringification
+    TraceElements.push({
+      metricName,
+      // @ts-ignore - put into scope via stringification
+      devtoolsNodePath: getNodePath(element), // eslint-disable-line no-undef
+      // @ts-ignore - put into scope via stringification
+      selector: getNodeSelector(element), // eslint-disable-line no-undef
+      // @ts-ignore - put into scope via stringification
+      nodeLabel: getNodeLabel(element), // eslint-disable-line no-undef
+      // @ts-ignore - put into scope via stringification
+      snippet: getOuterHTMLSnippet(element), // eslint-disable-line no-undef
+    });
+  }
+  return TraceElements;
+}
+
+class TraceElements extends Gatherer {
+  /**
+   * @param {LH.TraceEvent | undefined} lcpEvent
+   * @return {number | undefined}
+   */
+  static getNodeIDFromTraceEvent(lcpEvent) {
+    return lcpEvent && lcpEvent.args &&
+      lcpEvent.args.data && lcpEvent.args.data.nodeId;
+  }
+
+  /**
+   * @param {LH.Gatherer.PassContext} passContext
+   * @param {LH.Gatherer.LoadData} loadData
+   * @return {Promise<LH.Artifacts['TraceElements']>}
+   */
+  async afterPass(passContext, loadData) {
+    const driver = passContext.driver;
+    if (!loadData.trace) {
+      throw new Error('Trace is missing!');
+    }
+    const traceOfTab = TraceProcessor.computeTraceOfTab(loadData.trace);
+    const lcpEvent = traceOfTab.largestContentfulPaintEvt;
+    /** @type {Array<number>} */
+    const backendNodeIds = [];
+
+    const lcpNodeId = TraceElements.getNodeIDFromTraceEvent(lcpEvent);
+    if (lcpNodeId) {
+      backendNodeIds.push(lcpNodeId);
+    }
+    // DOM.getDocument is necessary for pushNodesByBackendIdsToFrontend to properly retrieve nodeIds.
+    await driver.sendCommand('DOM.getDocument', {depth: -1, pierce: true});
+    const translatedIds = await driver.sendCommand('DOM.pushNodesByBackendIdsToFrontend',
+      {backendNodeIds: backendNodeIds});
+
+    // Mark the LCP element so we can find it in the page.
+    await driver.sendCommand('DOM.setAttributeValue', {
+      nodeId: translatedIds.nodeIds[0],
+      name: LH_ATTRIBUTE_MARKER,
+      value: 'largest-contentful-paint',
+    });
+
+    const expression = `(() => {
+      ${pageFunctions.getElementsInDocumentString};
+      ${pageFunctions.getNodePathString};
+      ${pageFunctions.getNodeSelectorString};
+      ${pageFunctions.getNodeLabelString};
+      ${pageFunctions.getOuterHTMLSnippetString};
+
+      return (${collectTraceElements})('${LH_ATTRIBUTE_MARKER}');
+    })()`;
+
+    return driver.evaluateAsync(expression, {useIsolation: true});
+  }
+}
+
+module.exports = TraceElements;

lighthouse-core/lib/i18n/i18n.js

@@ -82,6 +82,8 @@ const UIStrings = {
   columnSource: 'Source',
   /** Label for a column in a data table; entries will be how much a predetermined budget has been exeeded by. Depending on the context, this number could represent an excess in quantity or size of network requests, or, an excess in the duration of time that it takes for the page to load.*/
   columnOverBudget: 'Over Budget',
+  /** Label for a column in a data table; entries will be a representation of a DOM element. */
+  columnElement: 'Element',
   /** Label for a row in a data table; entries will be the total number and byte size of all resources loaded by a web page. */
   totalResourceType: 'Total',
   /** Label for a row in a data table; entries will be the total number and byte size of all 'Document' resources loaded by a web page. */

lighthouse-core/lib/i18n/locales/ar-XB.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "‏‮Page‬‏ ‏‮has‬‏ ‏‮the‬‏ ‏‮HTML‬‏ ‏‮doctype‬‏"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "‏‮Element‬‏"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "‏‮Statistic‬‏"
   },

lighthouse-core/lib/i18n/locales/ar.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "الصفحة تحتوي على HTML DOCTYPE"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "العنصر"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "الإحصائية"
   },

lighthouse-core/lib/i18n/locales/bg.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Страницата съдържа doctype на HTML"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Елемент"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Статистически данни"
   },

lighthouse-core/lib/i18n/locales/ca.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "La pàgina té el tipus de document HTML"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Element"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Estadística"
   },

lighthouse-core/lib/i18n/locales/cs.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Stránka má deklaraci typu dokumentu (DOCTYPE) HTML"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Prvek"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Statistika"
   },

lighthouse-core/lib/i18n/locales/da.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Siden har dokumenttypen HTML"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Element"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Statistik"
   },

lighthouse-core/lib/i18n/locales/de.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Seite verfügt über den HTML-DOCTYPE"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Element"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Statistik"
   },

lighthouse-core/lib/i18n/locales/el.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Η σελίδα έχει τύπο εγγράφου (doctype) HTML"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Στοιχείο"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Στατιστικό στοιχείο"
   },

lighthouse-core/lib/i18n/locales/en-GB.json

@@ -566,9 +566,6 @@
   "lighthouse-core/audits/dobetterweb/doctype.js | title": {
     "message": "Page has the HTML doctype"
   },
-  "lighthouse-core/audits/dobetterweb/dom-size.js | columnElement": {
-    "message": "Element"
-  },
   "lighthouse-core/audits/dobetterweb/dom-size.js | columnStatistic": {
     "message": "Statistic"
   },