core(driver): move evaluateOnNewDocument to executionContext

lighthouse-core/gather/driver.js

@@ -398,17 +398,6 @@ class Driver {
     return !!this._domainEnabledCounts.get(domain);
   }
 
-  /**
-   * Add a script to run at load time of all future page loads.
-   * @param {string} scriptSource
-   * @return {Promise<LH.Crdp.Page.AddScriptToEvaluateOnLoadResponse>} Identifier of the added script.
-   */
-  evaluateScriptOnNewDocument(scriptSource) {
-    return this.sendCommand('Page.addScriptToEvaluateOnLoad', {
-      scriptSource,
-    });
-  }
-
   /**
    * @return {Promise<LH.Crdp.ServiceWorker.WorkerVersionUpdatedEvent>}
    */
@@ -885,20 +874,6 @@ class Driver {
     }
   }
 
-  /**
-   * Cache native functions/objects inside window
-   * so we are sure polyfills do not overwrite the native implementations
-   * @return {Promise<void>}
-   */
-  async cacheNatives() {
-    await this.evaluateScriptOnNewDocument(`
-        window.__nativePromise = Promise;
-        window.__nativeURL = URL;
-        window.__ElementMatches = Element.prototype.matches;
-        window.__perfNow = performance.now.bind(performance);
-    `);
-  }
-
   /**
    * Use a RequestIdleCallback shim for tests run with simulated throttling, so that the deadline can be used without
    * a penalty
@@ -907,9 +882,10 @@ class Driver {
    */
   async registerRequestIdleCallbackWrap(settings) {
     if (settings.throttlingMethod === 'simulate') {
-      const scriptStr = `(${pageFunctions.wrapRequestIdleCallbackString})
-        (${settings.throttling.cpuSlowdownMultiplier})`;
-      await this.evaluateScriptOnNewDocument(scriptStr);
+      await this.executionContext.evaluateOnNewDocument(
+        pageFunctions.wrapRequestIdleCallback,
+        {args: [settings.throttling.cpuSlowdownMultiplier]}
+      );
     }
   }
 

lighthouse-core/gather/driver/execution-context.js

@@ -5,6 +5,8 @@
  */
 'use strict';
 
+/* global window */
+
 const pageFunctions = require('../../lib/page-functions.js');
 
 class ExecutionContext {
@@ -83,11 +85,10 @@ class ExecutionContext {
       // 3. Ensure that errors captured in the Promise are converted into plain-old JS Objects
       //    so that they can be serialized properly b/c JSON.stringify(new Error('foo')) === '{}'
       expression: `(function wrapInNativePromise() {
-        const __nativePromise = globalThis.__nativePromise || Promise;
-        const URL = globalThis.__nativeURL || globalThis.URL;
+        ${ExecutionContext._cachedNativesPreamble};
         globalThis.__lighthouseExecutionContextId = ${contextId};
-        return new __nativePromise(function (resolve) {
-          return __nativePromise.resolve()
+        return new Promise(function (resolve) {
+          return Promise.resolve()
             .then(_ => ${expression})
             .catch(${pageFunctions.wrapRuntimeEvalErrorInBrowserString})
             .then(resolve);
@@ -164,14 +165,79 @@ class ExecutionContext {
    * @return {FlattenedPromise<R>}
    */
   evaluate(mainFn, options) {
-    const argsSerialized = options.args.map(arg => JSON.stringify(arg)).join(',');
+    const argsSerialized = ExecutionContext.serializeArguments(options.args);
     const depsSerialized = options.deps ? options.deps.join('\n') : '';
     const expression = `(() => {
       ${depsSerialized}
       return (${mainFn})(${argsSerialized});
     })()`;
     return this.evaluateAsync(expression, options);
   }
+
+  /**
+   * Evaluate a function on every new frame from now on.
+   * @template {any[]} T
+   * @param {((...args: T) => void)} mainFn The main function to call.
+   * @param {{args: T, deps?: Array<Function|string>}} options `args` should
+   *   match the args of `mainFn`, and can be any serializable value. `deps` are functions that must be
+   *   defined for `mainFn` to work.
+   * @return {Promise<void>}
+   */
+  async evaluateOnNewDocument(mainFn, options) {
+    const argsSerialized = ExecutionContext.serializeArguments(options.args);
+    const depsSerialized = options.deps ? options.deps.join('\n') : '';
+
+    const expression = `
+      ${ExecutionContext._cachedNativesPreamble};
+      ${depsSerialized};
+      (${mainFn})(${argsSerialized});
+    `;
+
+    await this._session.sendCommand('Page.addScriptToEvaluateOnNewDocument', {source: expression});
+  }
+
+  /**
+   * Cache native functions/objects inside window so we are sure polyfills do not overwrite the
+   * native implementations when the page loads.
+   * @return {Promise<void>}
+   */
+  async cacheNativesOnNewDocument() {
+    await this.evaluateOnNewDocument(() => {
+      window.__nativePromise = window.Promise;
+      window.__nativeURL = window.URL;
+      window.__nativePerformance = window.performance;
+      window.__ElementMatches = window.Element.prototype.matches;
+      // Ensure the native `performance.now` is not overwritable.
+      const performance = window.performance;
+      const performanceNow = window.performance.now;
+      Object.defineProperty(performance, 'now', {
+        value: () => performanceNow.call(performance),
+        writable: false,
+      });
+    }, {args: []});
+  }
+
+  /**
+   * Prefix every script evaluation with a shadowing of common globals that tend to be ponyfilled
+   * incorrectly by many sites. This allows functions to still refer to `Promise` instead of
+   * Lighthouse-specific backups like `__nativePromise`.
+   */
+  static get _cachedNativesPreamble() {
+    return [
+      'const Promise = globalThis.__nativePromise || globalThis.Promise',
+      'const URL = globalThis.__nativeURL || globalThis.URL',
+      'const performance = globalThis.__nativePerformance || globalThis.performance',
+    ].join(';\n');
+  }
+
+  /**
+   * Serializes an array of arguments for use in an `eval` string across the protocol.
+   * @param {any[]} args
+   * @return {string}
+   */
+  static serializeArguments(args) {
+    return args.map(arg => arg === undefined ? 'undefined' : JSON.stringify(arg)).join(',');
+  }
 }
 
 module.exports = ExecutionContext;

lighthouse-core/gather/driver/wait-for-condition.js

@@ -5,7 +5,7 @@
  */
 'use strict';
 
-/* global window */
+/* global window, performance */
 
 const log = require('lighthouse-logger');
 const LHError = require('../../lib/lh-error.js');
@@ -274,7 +274,7 @@ function registerPerformanceObserverInPage() {
   // Do not re-register if we've already run this script.
   if (window.____lastLongTask !== undefined) return;
 
-  window.____lastLongTask = window.__perfNow();
+  window.____lastLongTask = performance.now();
   const observer = new window.PerformanceObserver(entryList => {
     const entries = entryList.getEntries();
     for (const entry of entries) {
@@ -303,8 +303,8 @@ function checkTimeSinceLastLongTaskInPage() {
   // at some point farish (several hundred ms) into the future and the time at which it executes isn't
   // a reliable indicator of long task existence, instead we check if any information has changed.
   // See https://developer.chrome.com/blog/timer-throttling-in-chrome-88/
-  return new window.__nativePromise(resolve => {
-    const firstAttemptTs = window.__perfNow();
+  return new Promise(resolve => {
+    const firstAttemptTs = performance.now();
     const firstAttemptLastLongTaskTs = window.____lastLongTask || 0;
 
     setTimeout(() => {

lighthouse-core/gather/gather-runner.js

@@ -132,7 +132,7 @@ class GatherRunner {
     await driver.beginEmulation(options.settings);
     await driver.enableRuntimeEvents();
     await driver.enableAsyncStacks();
-    await driver.cacheNatives();
+    await driver.executionContext.cacheNativesOnNewDocument();
     await driver.dismissJavaScriptDialogs();
     await driver.registerRequestIdleCallbackWrap(options.settings);
     if (resetStorage) {

lighthouse-core/gather/gatherers/dobetterweb/tags-blocking-first-paint.js

@@ -20,7 +20,7 @@
 
 const Gatherer = require('../gatherer.js');
 
-/* global document, window, HTMLLinkElement, SVGScriptElement */
+/* global document, window, performance, HTMLLinkElement, SVGScriptElement */
 
 /** @typedef {{href: string, media: string, msSinceHTMLEnd: number, matches: boolean}} MediaChange */
 /** @typedef {{tagName: 'LINK', url: string, href: string, rel: string, media: string, disabled: boolean, mediaChanges: Array<MediaChange>}} LinkTag */
@@ -37,7 +37,7 @@ function installMediaListener() {
       const mediaChange = {
         href: this.href,
         media: val,
-        msSinceHTMLEnd: Date.now() - window.performance.timing.responseEnd,
+        msSinceHTMLEnd: Date.now() - performance.timing.responseEnd,
         matches: window.matchMedia(val).matches,
       };
       // @ts-expect-error - `___linkMediaChanges` created above.
@@ -203,8 +203,9 @@ class TagsBlockingFirstPaint extends Gatherer {
    * @param {LH.Gatherer.PassContext} passContext
    */
   async beforePass(passContext) {
-    // Don't return return value of `evaluateScriptOnNewDocument`.
-    await passContext.driver.evaluateScriptOnNewDocument(`(${installMediaListener.toString()})()`);
+    const {executionContext} = passContext.driver;
+    // Don't return return value of `evaluateOnNewDocument`.
+    await executionContext.evaluateOnNewDocument(installMediaListener, {args: []});
   }
 
   /**

lighthouse-core/lib/page-functions.js

@@ -542,6 +542,6 @@ module.exports = {
   getNodeLabel: getNodeLabel,
   getNodeLabelString: getNodeLabel.toString(),
   isPositionFixedString: isPositionFixed.toString(),
-  wrapRequestIdleCallbackString: wrapRequestIdleCallback.toString(),
+  wrapRequestIdleCallback,
   getBoundingClientRectString: getBoundingClientRect.toString(),
 };

lighthouse-core/test/gather/driver/execution-context-test.js

@@ -206,11 +206,12 @@ describe('.evaluate', () => {
     const {expression} = mockFn.findInvocation('Runtime.evaluate');
     const expected = `
 (function wrapInNativePromise() {
-        const __nativePromise = globalThis.__nativePromise || Promise;
-        const URL = globalThis.__nativeURL || globalThis.URL;
+        const Promise = globalThis.__nativePromise || globalThis.Promise;
+const URL = globalThis.__nativeURL || globalThis.URL;
+const performance = globalThis.__nativePerformance || globalThis.performance;
         globalThis.__lighthouseExecutionContextId = undefined;
-        return new __nativePromise(function (resolve) {
-          return __nativePromise.resolve()
+        return new Promise(function (resolve) {
+          return Promise.resolve()
             .then(_ => (() => {
 
       return (function main(value) {
@@ -329,3 +330,12 @@ function square(val) {
     expect(eval(code)).toEqual({a: 5, b: 100, passThru: 'hello'});
   });
 });
+
+describe('.serializeArguments', () => {
+  it('should serialize a list of differently typed arguments', () => {
+    const args = [undefined, 1, 'foo', null, {x: {y: {z: [2]}}}];
+    expect(ExecutionContext.serializeArguments(args)).toEqual(
+      `undefined,1,"foo",null,{"x":{"y":{"z":[2]}}}`
+    );
+  });
+});

lighthouse-core/test/gather/fake-driver.js

@@ -57,24 +57,21 @@ function makeFakeDriver({protocolGetVersionResponse}) {
     enableAsyncStacks() {
       return Promise.resolve();
     },
-    evaluateScriptOnLoad() {
-      return Promise.resolve();
-    },
     cleanBrowserCaches() {},
     clearDataForOrigin() {},
     getImportantStorageWarning() {
       return Promise.resolve(undefined);
     },
-    cacheNatives() {
-      return Promise.resolve();
-    },
     executionContext: {
       evaluateAsync() {
         return Promise.resolve({});
       },
       evaluate() {
         return Promise.resolve({});
       },
+      cacheNativesOnNewDocument() {
+        return Promise.resolve();
+      },
     },
     /** @param {{x: number, y: number}} position */
     scrollTo(position) {

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

@@ -88,9 +88,6 @@ class EmulationDriver extends Driver {
   assertNoSameOriginServiceWorkerClients() {
     return Promise.resolve();
   }
-  cacheNatives() {
-    return Promise.resolve();
-  }
   registerPerformanceObserver() {
     return Promise.resolve();
   }
@@ -125,6 +122,7 @@ function resetDefaultMockResponses() {
     .mockResponse('Network.setBlockedURLs')
     .mockResponse('Network.setExtraHTTPHeaders')
     .mockResponse('Network.setUserAgentOverride')
+    .mockResponse('Page.addScriptToEvaluateOnNewDocument')
     .mockResponse('Page.enable')
     .mockResponse('ServiceWorker.enable');
 }
@@ -339,7 +337,7 @@ describe('GatherRunner', function() {
       dismissJavaScriptDialogs: asyncFunc,
       enableRuntimeEvents: asyncFunc,
       enableAsyncStacks: asyncFunc,
-      cacheNatives: asyncFunc,
+      executionContext: {cacheNativesOnNewDocument: asyncFunc},
       gotoURL: asyncFunc,
       registerRequestIdleCallbackWrap: asyncFunc,
       cleanBrowserCaches: createCheck('calledCleanBrowserCaches'),
@@ -530,7 +528,7 @@ describe('GatherRunner', function() {
       dismissJavaScriptDialogs: asyncFunc,
       enableRuntimeEvents: asyncFunc,
       enableAsyncStacks: asyncFunc,
-      cacheNatives: asyncFunc,
+      executionContext: {cacheNativesOnNewDocument: asyncFunc},
       gotoURL: asyncFunc,
       registerPerformanceObserver: asyncFunc,
       registerRequestIdleCallbackWrap: asyncFunc,

types/externs.d.ts

@@ -393,11 +393,11 @@ declare global {
 
   interface Window {
     // Cached native functions/objects for use in case the page overwrites them.
-    // See: `driver.cacheNatives`.
+    // See: `executionContext.cacheNativesOnNewDocument`.
     __nativePromise: PromiseConstructor;
-    __nativeURL: URL;
+    __nativePerformance: Performance;
+    __nativeURL: typeof URL;
     __ElementMatches: Element['matches'];
-    __perfNow: Performance['now'];
 
     /** Used for monitoring long tasks in the test page. */
     ____lastLongTask?: number;