core(timespan-runner): warn if a navigation is detected

core/gather/timespan-runner.js

@@ -12,6 +12,16 @@
 import {enableAsyncStacks, prepareTargetForTimespanMode} from './driver/prepare.js';
 import {initializeConfig} from '../config/config.js';
 import {getBaseArtifacts, finalizeArtifacts} from './base-artifacts.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** A warning that indicates page navigations should be audited using navigation mode, as opposed to timespan mode. "navigation mode" refers to a Lighthouse mode that analyzes a page navigation. "timespan mode" refers to a Lighthouse mode that analyzes user interactions over an arbitrary period of time. */
+  warningNavigationDetected: 'A page navigation was detected during the run. Using timespan mode to audit page navigations is not recommended. Use navigation mode to audit page navigations for better third-party attribution and main thread detection.',
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
 
 /**
  * @param {LH.Puppeteer.Page} page
@@ -45,6 +55,13 @@
 
   await prepareTargetForTimespanMode(driver, resolvedConfig.settings);
 
+  let pageNavigationDetected = false;
+  function onFrameNavigated() {
+    pageNavigationDetected = true;
+  }
+
+  driver.defaultSession.on('Page.frameNavigated', onFrameNavigated);
+
   const disableAsyncStacks = await enableAsyncStacks(driver.defaultSession);
 
   await collectPhaseArtifacts({phase: 'startInstrumentation', ...phaseOptions});
@@ -67,6 +84,11 @@
           // We should disable our `Page.frameNavigated` handlers before that.
           await disableAsyncStacks();
 
+          driver.defaultSession.off('Page.frameNavigated', onFrameNavigated);
+          if (pageNavigationDetected) {
+            baseArtifacts.LighthouseRunWarnings.push(str_(UIStrings.warningNavigationDetected));
+          }
+
           await collectPhaseArtifacts({phase: 'getArtifact', ...phaseOptions});
           await driver.disconnect();
 
@@ -82,4 +104,5 @@
 
 export {
   startTimespanGather,
+  UIStrings,
 };

core/test/gather/timespan-runner-test.js

@@ -14,6 +14,7 @@ import {
   mockDriverModule,
   mockRunnerModule,
 } from './mock-driver.js';
+import {flushAllTimersAndMicrotasks, timers} from '../test-utils.js';
 
 const mockSubmodules = await mockDriverSubmodules();
 const mockRunner = await mockRunnerModule();
@@ -40,6 +41,9 @@ describe('Timespan Runner', () => {
   /** @type {LH.Config} */
   let config;
 
+  before(() => timers.useFakeTimers());
+  after(() => timers.dispose());
+
   beforeEach(() => {
     mockSubmodules.reset();
     mockPage = createMockPage();
@@ -180,4 +184,17 @@ describe('Timespan Runner', () => {
       },
     });
   });
+
+  it('should warn if a navigation was detected', async () => {
+    mockDriver._session.on.mockEvent('Page.frameNavigated', {});
+
+    const timespan = await startTimespanGather(page, {config});
+    await flushAllTimersAndMicrotasks();
+    await timespan.endTimespanGather();
+
+    const artifacts = await mockRunner.gather.mock.calls[0][0]();
+    expect(artifacts.LighthouseRunWarnings).toHaveLength(1);
+    expect(artifacts.LighthouseRunWarnings[0])
+      .toBeDisplayString(/A page navigation was detected during the run. Using timespan mode/);
+  });
 });

core/test/scenarios/api-test-pptr.js

@@ -80,6 +80,10 @@ describe('Individual modes API', function() {
         finalDisplayedUrl: `${state.serverBaseUrl}/onclick.html#done`,
       });
 
+      expect(lhr.runWarnings).toHaveLength(1);
+      expect(lhr.runWarnings[0])
+        .toMatch(/A page navigation was detected during the run. Using timespan mode/);
+
       const bestPractices = lhr.categories['best-practices'];
       expect(bestPractices.score).toBeLessThan(1);
 

core/test/scenarios/pptr-test-utils.js

@@ -77,7 +77,6 @@ function createTestState() {
 
       beforeEach(async () => {
         trace = undefined;
-        console.log('########');
         this.page = await this.browser.newPage();
       });