lighthouse 9.5.0-dev.20230110 → 9.5.0-dev.20230112

package/cli/bin.js

@@ -63,20 +63,20 @@ async function begin() {
 
   const urlUnderTest = cliFlags._[0];
 
-  /** @type {LH.Config.Json|undefined} */
-  let configJson;
+  /** @type {LH.Config|undefined} */
+  let config;
   if (cliFlags.configPath) {
     // Resolve the config file path relative to where cli was called.
     cliFlags.configPath = path.resolve(process.cwd(), cliFlags.configPath);
 
     if (cliFlags.configPath.endsWith('.json')) {
-      configJson = JSON.parse(fs.readFileSync(cliFlags.configPath, 'utf-8'));
+      config = JSON.parse(fs.readFileSync(cliFlags.configPath, 'utf-8'));
     } else {
       const configModuleUrl = url.pathToFileURL(cliFlags.configPath).href;
-      configJson = (await import(configModuleUrl)).default;
+      config = (await import(configModuleUrl)).default;
     }
   } else if (cliFlags.preset) {
-    configJson = (await import(`../core/config/${cliFlags.preset}-config.js`)).default;
+    config = (await import(`../core/config/${cliFlags.preset}-config.js`)).default;
   }
 
   if (cliFlags.budgetPath) {
@@ -132,7 +132,7 @@ async function begin() {
     });
   }
 
-  return runLighthouse(urlUnderTest, cliFlags, configJson);
+  return runLighthouse(urlUnderTest, cliFlags, config);
 }
 
 export {

package/cli/run.js

@@ -209,7 +209,7 @@ async function potentiallyKillChrome(launchedChrome) {
 /**
  * @param {string} url
  * @param {LH.CliFlags} flags
- * @param {LH.Config.Json|undefined} config
+ * @param {LH.Config|undefined} config
  * @return {Promise<LH.RunnerResult|undefined>}
  */
 async function runLighthouse(url, flags, config) {

package/cli/test/smokehouse/config/exclusions.js

@@ -28,4 +28,9 @@ const exclusions = {
   ],
 };
 
+// https://github.com/GoogleChrome/lighthouse/issues/14271
+for (const array of Object.values(exclusions)) {
+  array.push('lantern-idle-callback-short');
+}
+
 export default exclusions;

package/cli/test/smokehouse/core-tests.js

@@ -14,6 +14,8 @@ import errorsExpiredSsl from './test-definitions/errors-expired-ssl.js';
 import errorsIframeExpiredSsl from './test-definitions/errors-iframe-expired-ssl.js';
 import errorsInfiniteLoop from './test-definitions/errors-infinite-loop.js';
 import formsAutoComplete from './test-definitions/forms-autocomplete.js';
+import fpsMax from './test-definitions/fps-max.js';
+import fpsScaled from './test-definitions/fps-scaled.js';
 import issuesMixedContent from './test-definitions/issues-mixed-content.js';
 import lanternFetch from './test-definitions/lantern-fetch.js';
 import lanternIdleCallbackLong from './test-definitions/lantern-idle-callback-long.js';
@@ -51,10 +53,10 @@ import pwaSvgomg from './test-definitions/pwa-svgomg.js';
 import redirectsClientPaintServer from './test-definitions/redirects-client-paint-server.js';
 import redirectsHistoryPushState from './test-definitions/redirects-history-push-state.js';
 import redirectsMultipleServer from './test-definitions/redirects-multiple-server.js';
-import redirectScripts from './test-definitions/redirects-scripts.js';
+import redirectsScripts from './test-definitions/redirects-scripts.js';
+import redirectsSelf from './test-definitions/redirects-self.js';
 import redirectsSingleClient from './test-definitions/redirects-single-client.js';
 import redirectsSingleServer from './test-definitions/redirects-single-server.js';
-import redirectsSelf from './test-definitions/redirects-self.js';
 import screenshot from './test-definitions/screenshot.js';
 import seoFailing from './test-definitions/seo-failing.js';
 import seoPassing from './test-definitions/seo-passing.js';
@@ -62,8 +64,6 @@ import seoStatus403 from './test-definitions/seo-status-403.js';
 import seoTapTargets from './test-definitions/seo-tap-targets.js';
 import sourceMaps from './test-definitions/source-maps.js';
 import timing from './test-definitions/timing.js';
-import fpsScaled from './test-definitions/fps-scaled.js';
-import fpsMax from './test-definitions/fps-max.js';
 
 /** @type {ReadonlyArray<Smokehouse.TestDfn>} */
 const smokeTests = [
@@ -77,19 +77,21 @@ const smokeTests = [
   errorsIframeExpiredSsl,
   errorsInfiniteLoop,
   formsAutoComplete,
+  fpsMax,
+  fpsScaled,
   issuesMixedContent,
+  lanternFetch,
+  lanternIdleCallbackLong,
+  lanternIdleCallbackShort,
   lanternOnline,
   lanternSetTimeout,
-  lanternFetch,
   lanternXhr,
-  lanternIdleCallbackShort,
-  lanternIdleCallbackLong,
   legacyJavascript,
   metricsDebugger,
   metricsDelayedFcp,
   metricsDelayedLcp,
-  metricsTrickyTtiLateFcp,
   metricsTrickyTti,
+  metricsTrickyTtiLateFcp,
   offlineOnlineOnly,
   offlineReady,
   offlineSwBroken,
@@ -107,17 +109,17 @@ const smokeTests = [
   perfTraceElements,
   pubads,
   pwaAirhorner,
-  pwaChromestatus,
-  pwaSvgomg,
   pwaCaltrain,
+  pwaChromestatus,
   pwaRocks,
+  pwaSvgomg,
   redirectsClientPaintServer,
   redirectsHistoryPushState,
   redirectsMultipleServer,
-  redirectScripts,
+  redirectsScripts,
+  redirectsSelf,
   redirectsSingleClient,
   redirectsSingleServer,
-  redirectsSelf,
   screenshot,
   seoFailing,
   seoPassing,
@@ -125,8 +127,6 @@ const smokeTests = [
   seoTapTargets,
   sourceMaps,
   timing,
-  fpsScaled,
-  fpsMax,
 ];
 
 export default smokeTests;

package/cli/test/smokehouse/lighthouse-runners/bundle.js

@@ -26,9 +26,9 @@ import {loadArtifacts, saveArtifacts} from '../../../../core/lib/asset-saver.js'
 // This runs only in the worker. The rest runs on the main thread.
 if (!isMainThread && parentPort) {
   (async () => {
-    const {url, configJson, testRunnerOptions} = workerData;
+    const {url, config, testRunnerOptions} = workerData;
     try {
-      const result = await runBundledLighthouse(url, configJson, testRunnerOptions);
+      const result = await runBundledLighthouse(url, config, testRunnerOptions);
       // Save to assets directory because LighthouseError won't survive postMessage.
       const assetsDir = fs.mkdtempSync(os.tmpdir() + '/smoke-bundle-assets-');
       await saveArtifacts(result.artifacts, assetsDir);
@@ -46,11 +46,11 @@ if (!isMainThread && parentPort) {
 
 /**
  * @param {string} url
- * @param {LH.Config.Json|undefined} configJson
+ * @param {LH.Config|undefined} config
  * @param {{isDebug?: boolean, useLegacyNavigation?: boolean}} testRunnerOptions
  * @return {Promise<{lhr: LH.Result, artifacts: LH.Artifacts}>}
  */
-async function runBundledLighthouse(url, configJson, testRunnerOptions) {
+async function runBundledLighthouse(url, config, testRunnerOptions) {
   if (isMainThread || !parentPort) {
     throw new Error('must be called in worker');
   }
@@ -87,12 +87,12 @@ async function runBundledLighthouse(url, configJson, testRunnerOptions) {
     if (testRunnerOptions.useLegacyNavigation) {
       const connection = new CriConnection(port);
       runnerResult =
-        await legacyNavigation(url, {port, logLevel}, configJson, connection);
+        await legacyNavigation(url, {port, logLevel}, config, connection);
     } else {
       // Puppeteer is not included in the bundle, we must create the page here.
       const browser = await puppeteer.connect({browserURL: `http://localhost:${port}`});
       const page = await browser.newPage();
-      runnerResult = await lighthouse(url, {port, logLevel}, configJson, page);
+      runnerResult = await lighthouse(url, {port, logLevel}, config, page);
     }
     if (!runnerResult) throw new Error('No runnerResult');
 
@@ -109,17 +109,17 @@ async function runBundledLighthouse(url, configJson, testRunnerOptions) {
 /**
  * Launch Chrome and do a full Lighthouse run via the Lighthouse DevTools bundle.
  * @param {string} url
- * @param {LH.Config.Json=} configJson
+ * @param {LH.Config=} config
  * @param {{isDebug?: boolean, useLegacyNavigation?: boolean}=} testRunnerOptions
  * @return {Promise<{lhr: LH.Result, artifacts: LH.Artifacts, log: string}>}
  */
-async function runLighthouse(url, configJson, testRunnerOptions = {}) {
+async function runLighthouse(url, config, testRunnerOptions = {}) {
   /** @type {string[]} */
   const logs = [];
   const worker = new Worker(new URL(import.meta.url), {
     stdout: true,
     stderr: true,
-    workerData: {url, configJson, testRunnerOptions},
+    workerData: {url, config, testRunnerOptions},
   });
   worker.stdout.setEncoding('utf8');
   worker.stderr.setEncoding('utf8');

package/cli/test/smokehouse/lighthouse-runners/cli.js

@@ -27,16 +27,16 @@ const execFileAsync = promisify(execFile);
 /**
  * Launch Chrome and do a full Lighthouse run via the Lighthouse CLI.
  * @param {string} url
- * @param {LH.Config.Json=} configJson
+ * @param {LH.Config=} config
  * @param {{isDebug?: boolean, useFraggleRock?: boolean}=} testRunnerOptions
  * @return {Promise<{lhr: LH.Result, artifacts: LH.Artifacts, log: string}>}
  */
-async function runLighthouse(url, configJson, testRunnerOptions = {}) {
+async function runLighthouse(url, config, testRunnerOptions = {}) {
   const {isDebug} = testRunnerOptions;
   const tmpDir = `${LH_ROOT}/.tmp/smokehouse`;
   await fs.mkdir(tmpDir, {recursive: true});
   const tmpPath = await fs.mkdtemp(`${tmpDir}/smokehouse-`);
-  return internalRun(url, tmpPath, configJson, testRunnerOptions)
+  return internalRun(url, tmpPath, config, testRunnerOptions)
     // Wait for internalRun() before removing scratch directory.
     .finally(() => !isDebug && fs.rm(tmpPath, {recursive: true, force: true}));
 }
@@ -45,11 +45,11 @@ async function runLighthouse(url, configJson, testRunnerOptions = {}) {
  * Internal runner.
  * @param {string} url
  * @param {string} tmpPath
- * @param {LH.Config.Json=} configJson
+ * @param {LH.Config=} config
  * @param {{isDebug?: boolean, useLegacyNavigation?: boolean}=} options
  * @return {Promise<{lhr: LH.Result, artifacts: LH.Artifacts, log: string}>}
  */
-async function internalRun(url, tmpPath, configJson, options) {
+async function internalRun(url, tmpPath, config, options) {
   const {isDebug = false, useLegacyNavigation = false} = options || {};
   const localConsole = new LocalConsole();
 
@@ -72,9 +72,9 @@ async function internalRun(url, tmpPath, configJson, options) {
   }
 
   // Config can be optionally provided.
-  if (configJson) {
+  if (config) {
     const configPath = `${tmpPath}/config.json`;
-    await fs.writeFile(configPath, JSON.stringify(configJson));
+    await fs.writeFile(configPath, JSON.stringify(config));
     args.push(`--config-path=${configPath}`);
   }
 

package/cli/test/smokehouse/lighthouse-runners/devtools.js

@@ -41,16 +41,16 @@ async function setup() {
  * unless DEVTOOLS_PATH is set.
  * CHROME_PATH determines which Chrome is used–otherwise the default is puppeteer's chrome binary.
  * @param {string} url
- * @param {LH.Config.Json=} configJson
+ * @param {LH.Config=} config
  * @param {{isDebug?: boolean, useLegacyNavigation?: boolean}=} testRunnerOptions
  * @return {Promise<{lhr: LH.Result, artifacts: LH.Artifacts, log: string}>}
  */
-async function runLighthouse(url, configJson, testRunnerOptions = {}) {
+async function runLighthouse(url, config, testRunnerOptions = {}) {
   const chromeFlags = [
     `--custom-devtools-frontend=file://${devtoolsDir}/out/LighthouseIntegration/gen/front_end`,
   ];
   const {lhr, artifacts, logs} = await testUrlFromDevtools(url, {
-    config: configJson,
+    config,
     chromeFlags,
     useLegacyNavigation: testRunnerOptions.useLegacyNavigation,
   });

package/cli/test/smokehouse/readme.md

@@ -14,7 +14,7 @@ See [`SmokehouseOptions`](https://github.com/GoogleChrome/lighthouse/blob/main/c
 | -------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `id`           | `string`                           | The string identifier of the test.                                                                                               |
 | `expectations` | `{lhr: Object, artifacts: Object}` | See below.                                                                                                                       |
-| `config`       | `LH.Config.Json` (optional)        | An optional Lighthouse config. If not specified, the default config is used.                                                     |
+| `config`       | `LH.Config` (optional)        | An optional Lighthouse config. If not specified, the default config is used.                                                     |
 | `runSerially`  | `boolean` (optional)               | An optional flag. If set to true, the test won't be run in parallel to other tests. Useful if the test is performance sensitive. |
 
 ### Expectations

package/cli/test/smokehouse/smokehouse.js

@@ -134,21 +134,21 @@ function purpleify(str) {
 }
 
 /**
- * @param {LH.Config.Json=} configJson
- * @return {LH.Config.Json|undefined}
+ * @param {LH.Config=} config
+ * @return {LH.Config|undefined}
  */
-function convertToLegacyConfig(configJson) {
-  if (!configJson) return configJson;
+function convertToLegacyConfig(config) {
+  if (!config) return config;
 
   return {
-    ...configJson,
+    ...config,
     passes: [{
       passName: 'defaultPass',
-      pauseAfterFcpMs: configJson.settings?.pauseAfterFcpMs,
-      pauseAfterLoadMs: configJson.settings?.pauseAfterLoadMs,
-      networkQuietThresholdMs: configJson.settings?.networkQuietThresholdMs,
-      cpuQuietThresholdMs: configJson.settings?.cpuQuietThresholdMs,
-      blankPage: configJson.settings?.blankPage,
+      pauseAfterFcpMs: config.settings?.pauseAfterFcpMs,
+      pauseAfterLoadMs: config.settings?.pauseAfterLoadMs,
+      networkQuietThresholdMs: config.settings?.networkQuietThresholdMs,
+      cpuQuietThresholdMs: config.settings?.cpuQuietThresholdMs,
+      blankPage: config.settings?.blankPage,
     }],
   };
 }
@@ -184,15 +184,15 @@ async function runSmokeTest(smokeTestDefn, testOptions) {
       bufferedConsole.log(`  Retrying run (${i} out of ${retries} retries)…`);
     }
 
-    let configJson = smokeTestDefn.config;
+    let config = smokeTestDefn.config;
     if (useLegacyNavigation) {
-      configJson = convertToLegacyConfig(configJson);
+      config = convertToLegacyConfig(config);
     }
 
     // Run Lighthouse.
     try {
       result = {
-        ...await lighthouseRunner(requestedUrl, configJson, {isDebug, useLegacyNavigation}),
+        ...await lighthouseRunner(requestedUrl, config, {isDebug, useLegacyNavigation}),
         networkRequests: takeNetworkRequestUrls ? takeNetworkRequestUrls() : undefined,
       };
 

package/core/audits/bf-cache.js

@@ -0,0 +1,120 @@
+/**
+ * @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/bf-cache-strings.js';
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** Title of a diagnostic Lighthouse audit that identifies when the back/forward cache is being used. "back/forward" refers to the back and forward buttons found in modern browsers. This title is shown to users if the back/forward cache was used, or if the there was no attempt to restore the page from the back/forward cache. */
+  title: `Page didn't prevent back/forward cache restoration`,
+  /** Title of a diagnostic Lighthouse audit that identifies when the back/forward cache is being used. "back/forward" refers to the back and forward buttons found in modern browsers. This title is shown to users if the page attempted to restore from the back/forward cache but the back/forward cache was not used. */
+  failureTitle: 'Page prevented back/forward cache restoration',
+  /** Description of a diagnostic Lighthouse audit that identifies when the back/forward cache is being used. "back/forward" refers to the back and forward buttons found in modern browsers. */
+  description: 'Many navigations are performed by going back to a previous page, or forwards again. The back/forward cache (bfcache) can speed up these return navigations. [Learn more about the bfcache](https://web.dev/bfcache/)',
+  /** Failure type for an error that the user should be able to address themselves. Shown in a table column with other failure types. */
+  actionableFailureType: 'Actionable',
+  /** Failure type for an error that the user cannot address in the page's code. Shown in a table column with other failure types. */
+  notActionableFailureType: 'Not actionable',
+  /** Failure type for an error caused by missing browser support. Shown in a table column with other failure types. */
+  supportPendingFailureType: 'Pending browser support',
+  /** Label for a column in a data table; entries in the column will be a string explaining why a failure occurred. */
+  failureReasonColumn: 'Failure reason',
+  /** Label for a column in a data table; entries in the column will be a string representing the type of failure preventing the back/forward cache from being used. */
+  failureTypeColumn: 'Failure type',
+  /**
+   * @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 failure reason}
+    other {# failure reasons}
+    }`,
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+/** @type {LH.Crdp.Page.BackForwardCacheNotRestoredReasonType[]} */
+const ORDERED_FAILURE_TYPES = ['PageSupportNeeded', 'SupportPending', 'Circumstantial'];
+
+/** @type {Record<LH.Crdp.Page.BackForwardCacheNotRestoredReasonType, string | LH.IcuMessage>} */
+const FAILURE_TYPE_TO_STRING = {
+  PageSupportNeeded: str_(UIStrings.actionableFailureType),
+  Circumstantial: str_(UIStrings.notActionableFailureType),
+  SupportPending: str_(UIStrings.supportPendingFailureType),
+};
+
+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: ['BFCacheFailures'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts) {
+    const failures = artifacts.BFCacheFailures;
+    if (!failures.length) return {score: 1};
+
+    // TODO: Analyze more than one bf cache failure.
+    const {notRestoredReasonsTree} = failures[0];
+
+    /** @type {LH.Audit.Details.TableItem[]} */
+    const results = [];
+
+    for (const failureType of ORDERED_FAILURE_TYPES) {
+      const reasonsMap = notRestoredReasonsTree[failureType];
+
+      for (const [reason, frameUrls] of Object.entries(reasonsMap)) {
+        results.push({
+          reason: NotRestoredReasonDescription[reason]?.name ?? reason,
+          failureType: FAILURE_TYPE_TO_STRING[failureType],
+          subItems: {
+            type: 'subitems',
+            items: frameUrls.map(frameUrl => ({frameUrl})),
+          },
+          // Include hidden protocol reason code for debugging.
+          protocolReason: reason,
+        });
+      }
+    }
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      /* eslint-disable max-len */
+      {key: 'reason', valueType: 'text', subItemsHeading: {key: 'frameUrl', valueType: 'url'}, label: str_(UIStrings.failureReasonColumn)},
+      {key: 'failureType', valueType: 'text', label: str_(UIStrings.failureTypeColumn)},
+      /* eslint-enable max-len */
+    ];
+
+    const details = Audit.makeTableDetails(headings, results);
+
+    const displayValue = results.length ?
+      str_(UIStrings.displayValue, {itemCount: results.length}) :
+      undefined;
+
+    return {
+      score: results.length ? 0 : 1,
+      displayValue,
+      details,
+    };
+  }
+}
+
+export default BFCache;
+export {UIStrings};

package/core/audits/installable-manifest.js

@@ -16,7 +16,7 @@ const UIStrings = {
   'failureTitle': 'Web app manifest or service worker do not meet the installability requirements',
   /** Description of a Lighthouse audit that tells the user why installability is important for webapps. This is displayed after a user expands the section to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
   'description': `Service worker is the technology that enables your app to use many Progressive Web App features, such as offline, add to homescreen, and push notifications. With proper service worker and manifest implementations, browsers can proactively prompt users to add your app to their homescreen, which can lead to higher engagement. [Learn more about manifest installability requirements](https://developer.chrome.com/docs/lighthouse/pwa/installable-manifest/).`,
-  /** Description Table column header for the observed value of the Installability failure reason statistic. */
+  /** Label for a column in a data table; entries in the column will be a string explaining why a failure occurred. */
   'columnValue': 'Failure reason',
   /**
    * @description [ICU Syntax] Label for an audit identifying the number of installability errors found in the page.