GoogleChrome · patrickhulce · Aug 11, 2021 · Aug 10, 2021 · Aug 11, 2021 · Aug 11, 2021
diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
@@ -106,7 +106,7 @@ jobs:
 
     - run: sudo apt-get install xvfb
     - name: yarn smoke --fraggle-rock
-      run: xvfb-run --auto-servernum yarn smoke --debug --fraggle-rock -j=1 --retries=2 a11y lantern seo-passing seo-failing csp metrics
+      run: xvfb-run --auto-servernum yarn smoke --debug --fraggle-rock -j=1 --retries=2 a11y lantern seo-passing seo-failing csp metrics perf-debug
 
     # Fail if any changes were written to source files.
     - run: git diff --exit-code

diff --git a/lighthouse-cli/cli-flags.js b/lighthouse-cli/cli-flags.js
@@ -108,6 +108,10 @@ function getFlags(manualArgv, options = {}) {
           default: false,
           describe: 'Print the normalized config for the given config and options, then exit.',
         },
+        'debug-navigation': {
+          type: 'boolean',
+          describe: 'Pause after page load to wait for permission to continue the run, evaluate `continueLighthouseRun` in the console to continue.',
+        },
         'fraggle-rock': {
           type: 'boolean',
           default: false,

diff --git a/lighthouse-cli/test/fixtures/perf/debug.html b/lighthouse-cli/test/fixtures/perf/debug.html
@@ -0,0 +1,10 @@
+<html>
+  <head>
+  </head>
+  <body>
+    <h1>Debug test (should last at least 30s)</h1>
+    <script>
+      setTimeout(() => window.continueLighthouseRun(), 30_000);
+    </script>
+  </body>
+</html>
diff --git a/lighthouse-cli/test/smokehouse/test-definitions/core-tests.js b/lighthouse-cli/test/smokehouse/test-definitions/core-tests.js
@@ -161,6 +161,13 @@ const smokeTests = [{
   expectations: perf.frameMetrics,
   config: require('./perf/perf-config.js'),
   runSerially: true,
+}, {
+  id: 'perf-debug',
+  expectations: perf.debug,
+  config: {
+    extends: 'lighthouse:default',
+    settings: {debugNavigation: true, onlyAudits: ['metrics']},
+  },
 }, {
   id: 'perf-diagnostics-animations',
   expectations: diagnostics.animations,

diff --git a/lighthouse-cli/test/smokehouse/test-definitions/perf/expectations.js b/lighthouse-cli/test/smokehouse/test-definitions/perf/expectations.js
@@ -362,10 +362,19 @@ const frameMetrics = {
   },
 };
 
+const debug = {
+  lhr: {
+    requestedUrl: 'http://localhost:10200/perf/debug.html',
+    finalUrl: 'http://localhost:10200/perf/debug.html',
+    audits: {metrics: {details: {items: {0: {observedTraceEnd: '>30000'}}}}},
+  },
+};
+
 module.exports = {
   preload,
   budgets,
   fonts,
+  debug,
   traceElements,
   frameMetrics,
 };
diff --git a/lighthouse-core/config/constants.js b/lighthouse-core/config/constants.js
@@ -106,6 +106,7 @@ const defaultSettings = {
   auditMode: false,
   gatherMode: false,
   disableStorageReset: false,
+  debugNavigation: false,
   channel: 'node',
 
   // the following settings have no defaults but we still want ensure that `key in settings`

diff --git a/lighthouse-core/fraggle-rock/gather/navigation-runner.js b/lighthouse-core/fraggle-rock/gather/navigation-runner.js
@@ -88,6 +88,7 @@ async function _navigate(navigationContext) {
   try {
     const {finalUrl, warnings} = await gotoURL(driver, requestedUrl, {
       ...navigationContext.navigation,
+      debugNavigation: config.settings.debugNavigation,
       maxWaitForFcp: config.settings.maxWaitForFcp,
       maxWaitForLoad: config.settings.maxWaitForLoad,
       waitUntil: navigationContext.navigation.pauseAfterFcpMs ? ['fcp', 'load'] : ['load'],

diff --git a/lighthouse-core/gather/driver/navigation.js b/lighthouse-core/gather/driver/navigation.js
@@ -6,7 +6,7 @@
 'use strict';
 
 const NetworkMonitor = require('./network-monitor.js');
-const {waitForFullyLoaded, waitForFrameNavigated} = require('./wait-for-condition.js');
+const {waitForFullyLoaded, waitForFrameNavigated, waitForUserToContinue} = require('./wait-for-condition.js'); // eslint-disable-line max-len
 const constants = require('../../config/constants.js');
 const i18n = require('../../lib/i18n/i18n.js');
 const URL = require('../../lib/url-shim.js');
@@ -39,7 +39,7 @@ const DEFAULT_NETWORK_QUIET_THRESHOLD = 5000;
 // Controls how long to wait between longtasks before determining the CPU is idle, off by default
 const DEFAULT_CPU_QUIET_THRESHOLD = 0;
 
-/** @typedef {{waitUntil: Array<'fcp'|'load'|'navigated'>} & LH.Config.SharedPassNavigationJson & Partial<Pick<LH.Config.Settings, 'maxWaitForFcp'|'maxWaitForLoad'>>} NavigationOptions */
+/** @typedef {{waitUntil: Array<'fcp'|'load'|'navigated'>} & LH.Config.SharedPassNavigationJson & Partial<Pick<LH.Config.Settings, 'maxWaitForFcp'|'maxWaitForLoad'|'debugNavigation'>>} NavigationOptions */
 
 /** @param {NavigationOptions} options */
 function resolveWaitForFullyLoadedOptions(options) {
@@ -121,6 +121,10 @@ async function gotoURL(driver, url, options) {
   await waitforPageNavigateCmd;
   await networkMonitor.disable();
 
+  if (options.debugNavigation) {
+    await waitForUserToContinue(driver);
+  }
+
   return {
     finalUrl,
     warnings: getNavigationWarnings({timedOut, finalUrl, requestedUrl: url}),

diff --git a/lighthouse-core/gather/driver/wait-for-condition.js b/lighthouse-core/gather/driver/wait-for-condition.js
@@ -490,6 +490,32 @@ async function waitForFullyLoaded(session, networkMonitor, options) {
   return cleanupFn();
 }
 
+/**
+ * @param {LH.Gatherer.FRTransitionalDriver} driver
+ */
+function waitForUserToContinue(driver) {
+  /* c8 ignore start */
+  function createInPagePromise() {
+    let resolve = () => {};
+    /** @type {Promise<void>} */
+    const promise = new Promise(r => resolve = r);
+
+    // eslint-disable-next-line no-console
+    console.log([
+      `You have enabled Lighthouse navigation debug mode.`,
+      `When you have finished inspecting the page, evaluate "continueLighthouseRun()"`,
+      `in the console to continue with the Lighthouse run.`,
+    ].join(' '));
+
+    window.continueLighthouseRun = resolve;
+    return promise;
+  }
+  /* c8 ignore stop */
+
+  driver.defaultSession.setNextProtocolTimeout(2 ** 31 - 1);
+  return driver.executionContext.evaluate(createInPagePromise, {args: []});
+}
+
 module.exports = {
   waitForNothing,
   waitForFrameNavigated,
@@ -498,4 +524,5 @@ module.exports = {
   waitForNetworkIdle,
   waitForCPUIdle,
   waitForFullyLoaded,
+  waitForUserToContinue,
 };
diff --git a/lighthouse-core/gather/gather-runner.js b/lighthouse-core/gather/gather-runner.js
@@ -74,6 +74,7 @@ class GatherRunner {
       const {finalUrl, warnings} = await navigation.gotoURL(driver, requestedUrl, {
         waitUntil: passContext.passConfig.recordTrace ?
           ['load', 'fcp'] : ['load'],
+        debugNavigation: passContext.settings.debugNavigation,
         maxWaitForFcp: passContext.settings.maxWaitForFcp,
         maxWaitForLoad: passContext.settings.maxWaitForLoad,
         ...passContext.passConfig,

diff --git a/types/externs.d.ts b/types/externs.d.ts
@@ -52,6 +52,9 @@ declare global {
     __lighthouseNodesDontTouchOrAllVarianceGoesAway: Map<Element, string>;
     __lighthouseExecutionContextId?: number;
 
+    /** Injected by the page when the `--debug` flag is used. */
+    continueLighthouseRun(): void;
+
     // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
     requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
   }
@@ -206,6 +209,8 @@ export interface SharedFlagsSettings {
   gatherMode?: boolean | string;
   /** Flag indicating that the browser storage should not be reset for the audit. */
   disableStorageReset?: boolean;
+  /** Flag indicating that Lighthouse should pause after page load to wait for the user's permission to continue the audit. */
+  debugNavigation?: boolean;
 
   /** How Lighthouse should interpret this run in regards to scoring performance metrics and skipping mobile-only tests in desktop. Must be set even if throttling/emulation is being applied outside of Lighthouse. */
   formFactor?: 'mobile'|'desktop';