new_audit: bf-cache

cli/test/smokehouse/test-definitions/dobetterweb.js

@@ -7,6 +7,11 @@
 /** @type {LH.Config.Json} */
 const config = {
   extends: 'lighthouse:default',
+  settings: {
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+  },
   audits: [
     // Test the `ignoredPatterns` audit option.
     {path: 'errors-in-console', options: {ignoredPatterns: ['An ignored error']}},

cli/test/smokehouse/test-definitions/perf-budgets.js

@@ -13,6 +13,10 @@ const config = {
     // webpages present here, hence the inclusion of 'best-practices'.
     onlyCategories: ['performance', 'best-practices'],
 
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+
     // A mixture of under, over, and meeting budget to exercise all paths.
     budgets: [{
       path: '/',

cli/test/smokehouse/test-definitions/perf-fonts.js

@@ -13,6 +13,10 @@ const config = {
     // webpages present here, hence the inclusion of 'best-practices'.
     onlyCategories: ['performance', 'best-practices'],
 
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+
     // A mixture of under, over, and meeting budget to exercise all paths.
     budgets: [{
       path: '/',

cli/test/smokehouse/test-definitions/perf-frame-metrics.js

@@ -13,6 +13,10 @@ const config = {
     // webpages present here, hence the inclusion of 'best-practices'.
     onlyCategories: ['performance', 'best-practices'],
 
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+
     // A mixture of under, over, and meeting budget to exercise all paths.
     budgets: [{
       path: '/',

cli/test/smokehouse/test-definitions/perf-preload.js

@@ -13,6 +13,10 @@ const config = {
     // webpages present here, hence the inclusion of 'best-practices'.
     onlyCategories: ['performance', 'best-practices'],
 
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+
     // A mixture of under, over, and meeting budget to exercise all paths.
     budgets: [{
       path: '/',

cli/test/smokehouse/test-definitions/perf-trace-elements.js

@@ -13,6 +13,10 @@ const config = {
     // webpages present here, hence the inclusion of 'best-practices'.
     onlyCategories: ['performance', 'best-practices'],
 
+    // BF cache will request the page again, initiating additional network requests.
+    // Disable the audit so we only detect requests from the normal page load.
+    skipAudits: ['bf-cache'],
+
     // A mixture of under, over, and meeting budget to exercise all paths.
     budgets: [{
       path: '/',

core/audits/bf-cache.js

@@ -0,0 +1,141 @@
+/**
+ * @license Copyright 2022 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.
+ */
+
+import {Audit} from './audit.js';
+import * as i18n from '../lib/i18n/i18n.js';
+import {NotRestoredReasonDescription} from '../lib/bfcache-strings.js';
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** TODO */
+  title: 'Back/forward cache is used',
+  /** TODO */
+  failureTitle: 'Back/forward cache is not used',
+  /** TODO */
+  description: 'The back/forward cache can speed up the page load after navigating away.',
+  /** TODO */
+  actionableColumn: 'Actionable failure',
+  /** TODO */
+  notActionableColumn: 'Not actionable failure',
+  /** TODO */
+  supportPendingColumn: 'Pending browser support',
+  /**
+   * @description [ICU Syntax] Label for an audit identifying the number of back/forward cache failure reasons found in the page.
+   */
+  displayValue: `{itemCount, plural,
+    =1 {1 actionable failure reason}
+    other {# actionable failure reasons}
+    }`,
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+class BFCache extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'bf-cache',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.failureTitle),
+      description: str_(UIStrings.description),
+      supportedModes: ['navigation', 'timespan'],
+      requiredArtifacts: ['BFCacheErrors'],
+    };
+  }
+
+  /**
+   * @param {LH.Crdp.Page.BackForwardCacheNotRestoredReason} reason
+   */
+  static getDescriptionForReason(reason) {
+    const matchingString = NotRestoredReasonDescription[reason];
+
+    if (matchingString === undefined) {
+      return reason;
+    }
+
+    return matchingString.name;
+  }
+
+  /**
+   * @param {LH.Artifacts.BFCacheErrorMap} errors
+   * @param {LH.IcuMessage | string} label
+   * @return {LH.Audit.Details.Table}
+   */
+  static makeTableForFailureType(errors, label) {
+    /** @type {LH.Audit.Details.TableItem[]} */
+    const results = [];
+
+    // https://github.com/Microsoft/TypeScript/issues/12870
+    const reasons = /** @type {LH.Crdp.Page.BackForwardCacheNotRestoredReason[]} */
+      (Object.keys(errors));
+
+    for (const reason of reasons) {
+      const frameUrls = errors[reason] || [];
+      results.push({
+        reason: this.getDescriptionForReason(reason),
+        subItems: {
+          type: 'subitems',
+          items: frameUrls.map(frameUrl => ({frameUrl})),
+        },
+      });
+    }
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      /* eslint-disable max-len */
+      {key: 'reason', valueType: 'text', subItemsHeading: {key: 'frameUrl', valueType: 'url'}, label},
+      /* eslint-enable max-len */
+    ];
+
+    return Audit.makeTableDetails(headings, results);
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts) {
+    const {PageSupportNeeded, SupportPending, Circumstantial} = artifacts.BFCacheErrors;
+
+    const actionableTable =
+      this.makeTableForFailureType(PageSupportNeeded, str_(UIStrings.actionableColumn));
+    const notActionableTable =
+      this.makeTableForFailureType(Circumstantial, str_(UIStrings.notActionableColumn));
+    const supportPendingTable =
+      this.makeTableForFailureType(SupportPending, str_(UIStrings.supportPendingColumn));
+
+    const items = [
+      actionableTable,
+      notActionableTable,
+      supportPendingTable,
+    ];
+
+    if (actionableTable.items.length === 0) {
+      return {
+        score: 1,
+        details: {
+          type: 'list',
+          items,
+        },
+      };
+    }
+
+    return {
+      score: 0,
+      displayValue: str_(UIStrings.displayValue, {itemCount: actionableTable.items.length}),
+      details: {
+        type: 'list',
+        items,
+      },
+    };
+  }
+}
+
+export default BFCache;
+export {UIStrings};

core/config/default-config.js

@@ -128,6 +128,7 @@ const artifacts = {
   Trace: '',
   Accessibility: '',
   AnchorElements: '',
+  BFCacheErrors: '',
   CacheContents: '',
   ConsoleMessages: '',
   CSSUsage: '',
@@ -216,8 +217,11 @@ const defaultConfig = {
     {id: artifacts.devtoolsLogs, gatherer: 'devtools-log-compat'},
     {id: artifacts.traces, gatherer: 'trace-compat'},
 
-    // FullPageScreenshot comes at the very end so all other node analysis is captured.
+    // FullPageScreenshot comes at the end so all other node analysis is captured.
     {id: artifacts.FullPageScreenshot, gatherer: 'full-page-screenshot'},
+
+    // BFCacheErrors comes at the very end because it can perform a page navigation.
+    {id: artifacts.BFCacheErrors, gatherer: 'bf-cache-errors'},
   ],
   audits: [
     'is-on-https',
@@ -373,6 +377,7 @@ const defaultConfig = {
     'seo/canonical',
     'seo/manual/structured-data',
     'work-during-interaction',
+    'bf-cache',
   ],
   groups: {
     'metrics': {
@@ -515,6 +520,7 @@ const defaultConfig = {
         {id: 'no-unload-listeners', weight: 0},
         {id: 'uses-responsive-images-snapshot', weight: 0},
         {id: 'work-during-interaction', weight: 0},
+        {id: 'bf-cache', weight: 0},
 
         // Budget audits.
         {id: 'performance-budget', weight: 0, group: 'budgets'},

core/gather/driver.js

@@ -84,7 +84,7 @@ class Driver {
   /** @return {Promise<void>} */
   async disconnect() {
     if (this.defaultSession === throwingSession) return;
-    this._targetManager?.disable();
+    await this._targetManager?.disable();
     await this.defaultSession.dispose();
   }
 }

core/gather/driver/target-manager.js

@@ -58,15 +58,22 @@ class TargetManager extends ProtocolEventEmitter {
   async _onFrameNavigated(frameNavigatedEvent) {
     // Child frames are handled in `_onSessionAttached`.
     if (frameNavigatedEvent.frame.parentId) return;
+    if (!this._enabled) return;
 
     // It's not entirely clear when this is necessary, but when the page switches processes on
     // navigating from about:blank to the `requestedUrl`, resetting `setAutoAttach` has been
     // necessary in the past.
-    await this._rootCdpSession.send('Target.setAutoAttach', {
-      autoAttach: true,
-      flatten: true,
-      waitForDebuggerOnStart: true,
-    });
+    try {
+      await this._rootCdpSession.send('Target.setAutoAttach', {
+        autoAttach: true,
+        flatten: true,
+        waitForDebuggerOnStart: true,
+      });
+    } catch (err) {
+      // The page can be closed at the end of the run before this CDP function returns.
+      // In these cases, just ignore the error since we won't need the page anyway.
+      if (this._enabled) throw err;
+    }
   }
 
   /**