core: replace most usages of evaluateAsync with structured evaluate

docs/recipes/custom-gatherer-puppeteer/custom-gatherer.js

@@ -33,7 +33,7 @@ class CustomGatherer extends Gatherer {
       el.type = 'number';
       document.body.append(el);
     }
-    await driver.evaluateAsync(`(${makeInput})()`);
+    await driver.evaluate(makeInput, {args: []});
     await new Promise(resolve => setTimeout(resolve, 100));
 
     // Prove that `driver` (Lighthouse) and `page` (Puppeteer) are talking to the same page.

lighthouse-core/fraggle-rock/gather/driver.js

@@ -55,6 +55,17 @@ class Driver {
     if (!this._executionContext) throw new Error('Driver not connected to page');
     return this._executionContext.evaluateAsync(expression, options);
   }
+
+  /**
+   * @template {any[]} T, R
+   * @param {((...args: T) => R)} mainFn
+   * @param {{args: T, useIsolation?: boolean, deps?: Array<Function|string>}} options
+   * @return {FlattenedPromise<R>}
+   */
+  async evaluate(mainFn, options) {
+    if (!this._executionContext) throw new Error('Driver not connected to page');
+    return this._executionContext.evaluate(mainFn, options);
+  }
 }
 
 module.exports = Driver;

lighthouse-core/gather/driver.js

@@ -466,6 +466,11 @@ class Driver {
   }
 
   /**
+   * Note: Prefer `evaluate` instead.
+   * Evaluate an expression in the context of the current page. If useIsolation is true, the expression
+   * will be evaluated in a content script that has access to the page's DOM but whose JavaScript state
+   * is completely separate.
+   * Returns a promise that resolves on the expression's value.
    * @param {string} expression
    * @param {{useIsolation?: boolean}=} options
    * @return {Promise<*>}
@@ -484,7 +489,7 @@ class Driver {
    * @param {{args: T, useIsolation?: boolean, 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<R>}
+   * @return {FlattenedPromise<R>}
    */
   async evaluate(mainFn, options) {
     return this._executionContext.evaluate(mainFn, options);

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

@@ -160,7 +160,7 @@ class ExecutionContext {
    * @param {{args: T, useIsolation?: boolean, 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<R>}
+   * @return {FlattenedPromise<R>}
    */
   evaluate(mainFn, options) {
     const argsSerialized = options.args.map(arg => JSON.stringify(arg)).join(',');

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

@@ -210,15 +210,15 @@ function waitForCPUIdle(session, waitForCPUQuiet) {
   let lastTimeout;
   let canceled = false;
 
-  const checkForQuietExpression = `(${pageFunctions.checkTimeSinceLastLongTaskString})()`;
   /**
    * @param {ExecutionContext} executionContext
    * @param {() => void} resolve
    * @return {Promise<void>}
    */
   async function checkForQuiet(executionContext, resolve) {
     if (canceled) return;
-    const timeSinceLongTask = await executionContext.evaluateAsync(checkForQuietExpression);
+    const timeSinceLongTask =
+      await executionContext.evaluate(pageFunctions.checkTimeSinceLastLongTask, {args: []});
     if (canceled) return;
 
     if (typeof timeSinceLongTask === 'number') {

lighthouse-core/gather/gatherers/accessibility.js

@@ -99,13 +99,15 @@ class Accessibility extends Gatherer {
    */
   afterPass(passContext) {
     const driver = passContext.driver;
-    const expression = `(function () {
-      ${pageFunctions.getNodeDetailsString};
-      ${axeLibSource};
-      return (${runA11yChecks.toString()}());
-    })()`;
 
-    return driver.evaluateAsync(expression, {useIsolation: true}).then(returnedValue => {
+    return driver.evaluate(runA11yChecks, {
+      args: [],
+      useIsolation: true,
+      deps: [
+        axeLibSource,
+        pageFunctions.getNodeDetailsString,
+      ],
+    }).then(returnedValue => {
       if (!returnedValue) {
         throw new Error('No axe-core results returned');
       }

lighthouse-core/gather/gatherers/anchor-elements.js

@@ -95,15 +95,15 @@ class AnchorElements extends Gatherer {
    */
   async afterPass(passContext) {
     const driver = passContext.driver;
-    const expression = `(() => {
-      ${pageFunctions.getElementsInDocumentString};
-      ${pageFunctions.getNodeDetailsString};
 
-      return (${collectAnchorElements})();
-    })()`;
-
-    /** @type {LH.Artifacts['AnchorElements']} */
-    const anchors = await driver.evaluateAsync(expression, {useIsolation: true});
+    const anchors = await driver.evaluate(collectAnchorElements, {
+      args: [],
+      useIsolation: true,
+      deps: [
+        pageFunctions.getElementsInDocumentString,
+        pageFunctions.getNodeDetailsString,
+      ],
+    });
     await driver.sendCommand('DOM.enable');
 
     // DOM.getDocument is necessary for pushNodesByBackendIdsToFrontend to properly retrieve nodeIds if the `DOM` domain was enabled before this gatherer, invoke it to be safe.

lighthouse-core/gather/gatherers/cache-contents.js

@@ -46,12 +46,7 @@ class CacheContents extends Gatherer {
   async afterPass(passContext) {
     const driver = passContext.driver;
 
-    /** @type {Array<string>|void} */
-    const cacheUrls = await driver.evaluateAsync(`(${getCacheContents.toString()}())`);
-    if (!cacheUrls || !Array.isArray(cacheUrls)) {
-      throw new Error('Unable to retrieve cache contents');
-    }
-
+    const cacheUrls = await driver.evaluate(getCacheContents, {args: []});
     return cacheUrls;
   }
 }

lighthouse-core/gather/gatherers/dobetterweb/doctype.js

@@ -29,7 +29,7 @@ class Doctype extends Gatherer {
    */
   afterPass(passContext) {
     const driver = passContext.driver;
-    return driver.evaluateAsync(`(${getDoctype.toString()}())`);
+    return driver.evaluate(getDoctype, {args: []});
   }
 }
 

lighthouse-core/gather/gatherers/dobetterweb/domstats.js

@@ -3,36 +3,35 @@
  * 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.
  */
-// @ts-nocheck
+
 /**
  * @fileoverview Gathers stats about the max height and width of the DOM tree
  * and total number of elements used on the page.
  */
 
-/* global getNodeDetails */
+/* global getNodeDetails document */
 
 'use strict';
 
 const Gatherer = require('../gatherer.js');
 const pageFunctions = require('../../../lib/page-functions.js');
 
-
 /**
  * Calculates the maximum tree depth of the DOM.
  * @param {HTMLElement} element Root of the tree to look in.
  * @param {boolean=} deep True to include shadow roots. Defaults to true.
  * @return {LH.Artifacts.DOMStats}
  */
 /* istanbul ignore next */
-function getDOMStats(element, deep = true) {
+function getDOMStats(element = document.body, deep = true) {
   let deepestElement = null;
   let maxDepth = -1;
   let maxWidth = -1;
   let numElements = 0;
   let parentWithMostChildren = null;
 
   /**
-   * @param {Element} element
+   * @param {Element|ShadowRoot} element
    * @param {number} depth
    */
   const _calcDOMWidthAndHeight = function(element, depth = 1) {
@@ -64,10 +63,12 @@ function getDOMStats(element, deep = true) {
   return {
     depth: {
       max: result.maxDepth,
+      // @ts-expect-error - getNodeDetails put into scope via stringification
       ...getNodeDetails(deepestElement),
     },
     width: {
       max: result.maxWidth,
+      // @ts-expect-error - getNodeDetails put into scope via stringification
       ...getNodeDetails(parentWithMostChildren),
     },
     totalBodyElements: result.numElements,
@@ -82,12 +83,12 @@ class DOMStats extends Gatherer {
   async afterPass(passContext) {
     const driver = passContext.driver;
 
-    const expression = `(function() {
-      ${pageFunctions.getNodeDetailsString};
-      return (${getDOMStats.toString()}(document.body));
-    })()`;
     await driver.sendCommand('DOM.enable');
-    const results = await driver.evaluateAsync(expression, {useIsolation: true});
+    const results = await driver.evaluate(getDOMStats, {
+      args: [],
+      useIsolation: true,
+      deps: [pageFunctions.getNodeDetailsString],
+    });
     await driver.sendCommand('DOM.disable');
     return results;
   }

lighthouse-core/gather/gatherers/dobetterweb/password-inputs-with-prevented-paste.js

@@ -34,12 +34,10 @@ class PasswordInputsWithPreventedPaste extends Gatherer {
    * @return {Promise<LH.Artifacts['PasswordInputsWithPreventedPaste']>}
    */
   afterPass(passContext) {
-    const expression = `(() => {
-      ${pageFunctions.getNodeDetailsString};
-      return (${findPasswordInputsWithPreventedPaste.toString()}());
-    })()`;
-
-    return passContext.driver.evaluateAsync(expression);
+    return passContext.driver.evaluate(findPasswordInputsWithPreventedPaste, {
+      args: [],
+      deps: [pageFunctions.getNodeDetailsString],
+    });
   }
 }
 

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

@@ -42,7 +42,7 @@ function installMediaListener() {
 }
 
 /**
- * @return {Promise<{tagName: string, url: string, src: string, href: string, rel: string, media: string, disabled: boolean, mediaChanges: {href: string, media: string, msSinceHTMLEnd: number, matches: boolean}}>}
+ * @return {Promise<Array<{tagName: string, url: string, src: string, href: string, rel: string, media: string, disabled: boolean, mediaChanges: {href: string, media: string, msSinceHTMLEnd: number, matches: boolean}}>>}
  */
 /* istanbul ignore next */
 function collectTagsThatBlockFirstPaint() {
@@ -132,12 +132,11 @@ class TagsBlockingFirstPaint extends Gatherer {
    * @param {Array<LH.Artifacts.NetworkRequest>} networkRecords
    */
   static findBlockingTags(driver, networkRecords) {
-    const scriptSrc = `(${collectTagsThatBlockFirstPaint.toString()}())`;
     const firstRequestEndTime = networkRecords.reduce(
       (min, record) => Math.min(min, record.endTime),
       Infinity
     );
-    return driver.evaluateAsync(scriptSrc).then(tags => {
+    return driver.evaluate(collectTagsThatBlockFirstPaint, {args: []}).then(tags => {
       const requests = TagsBlockingFirstPaint._filteredAndIndexedByUrl(networkRecords);
 
       return tags.reduce((prev, tag) => {

lighthouse-core/gather/gatherers/form-elements.js

@@ -90,14 +90,14 @@ class FormElements extends Gatherer {
   async afterPass(passContext) {
     const driver = passContext.driver;
 
-    const expression = `(() => {
-      ${pageFunctions.getElementsInDocumentString};
-      ${pageFunctions.getNodeDetailsString};
-      return (${collectFormElements})();
-    })()`;
-
-    /** @type {LH.Artifacts['FormElements']} */
-    const formElements = await driver.evaluateAsync(expression, {useIsolation: true});
+    const formElements = await driver.evaluate(collectFormElements, {
+      args: [],
+      useIsolation: true,
+      deps: [
+        pageFunctions.getElementsInDocumentString,
+        pageFunctions.getNodeDetailsString,
+      ],
+    });
     return formElements;
   }
 }

lighthouse-core/gather/gatherers/full-page-screenshot.js

@@ -5,7 +5,7 @@
  */
 'use strict';
 
-/* globals window getBoundingClientRect */
+/* globals window document getBoundingClientRect */
 
 const Gatherer = require('./gatherer.js');
 const pageFunctions = require('../../lib/page-functions.js');
@@ -92,18 +92,23 @@ class FullPageScreenshot extends Gatherer {
 
       return nodes;
     }
-    const expression = `(function () {
-      ${pageFunctions.getBoundingClientRectString};
-      return (${resolveNodes.toString()}());
-    })()`;
+
+    /**
+     * @param {boolean} useIsolation
+     */
+    function evaluateInPage(useIsolation) {
+      return passContext.driver.evaluate(resolveNodes, {
+        args: [],
+        useIsolation,
+        deps: [pageFunctions.getBoundingClientRectString],
+      });
+    }
 
     // Collect nodes with the page context (`useIsolation: false`) and with our own, reused
-    // context (useIsolation: false). Gatherers use both modes when collecting node details,
+    // context (`useIsolation: false`). Gatherers use both modes when collecting node details,
     // so we must do the same here too.
-    const pageContextResult =
-      await passContext.driver.evaluateAsync(expression, {useIsolation: false});
-    const isolatedContextResult =
-      await passContext.driver.evaluateAsync(expression, {useIsolation: true});
+    const pageContextResult = await evaluateInPage(false);
+    const isolatedContextResult = await evaluateInPage(true);
     return {...pageContextResult, ...isolatedContextResult};
   }
 
@@ -136,20 +141,25 @@ class FullPageScreenshot extends Gatherer {
         // in the LH runner api, which for ex. puppeteer consumers would setup puppeteer emulation,
         // and then just call that to reset?
         // https://github.com/GoogleChrome/lighthouse/issues/11122
-        const observedDeviceMetrics = await driver.evaluateAsync(`(function() {
+
+        const observedDeviceMetrics = await driver.evaluate(function getObservedDeviceMetrics() {
+          // Convert the Web API's snake case (landscape-primary) to camel case (landscapePrimary).
+          const screenOrientationType = /** @type {LH.Crdp.Emulation.ScreenOrientationType} */ (
+            snakeCaseToCamelCase(window.screen.orientation.type));
           return {
             width: document.documentElement.clientWidth,
             height: document.documentElement.clientHeight,
             screenOrientation: {
-              type: window.screen.orientation.type,
+              type: screenOrientationType,
               angle: window.screen.orientation.angle,
             },
             deviceScaleFactor: window.devicePixelRatio,
           };
-        })()`, {useIsolation: true});
-        // Convert the Web API's snake case (landscape-primary) to camel case (landscapePrimary).
-        observedDeviceMetrics.screenOrientation.type =
-          snakeCaseToCamelCase(observedDeviceMetrics.screenOrientation.type);
+        }, {
+          args: [],
+          useIsolation: true,
+          deps: [snakeCaseToCamelCase],
+        });
         await driver.sendCommand('Emulation.setDeviceMetricsOverride', {
           mobile: passContext.baseArtifacts.TestedAsMobileDevice, // could easily be wrong
           ...observedDeviceMetrics,

lighthouse-core/gather/gatherers/html-without-javascript.js

@@ -40,8 +40,7 @@ class HTMLWithoutJavaScript extends Gatherer {
     // Reset the JS disable.
     passContext.disableJavaScript = false;
 
-    const expression = `(${getBodyText.toString()}())`;
-    const {bodyText, hasNoScript} = await passContext.driver.evaluateAsync(expression);
+    const {bodyText, hasNoScript} = await passContext.driver.evaluate(getBodyText, {args: []});
     if (typeof bodyText !== 'string') {
       throw new Error('document body innerText returned by protocol was not a string');
     }

lighthouse-core/gather/gatherers/iframe-elements.js

@@ -43,15 +43,14 @@ class IFrameElements extends Gatherer {
   async afterPass(passContext) {
     const driver = passContext.driver;
 
-    const expression = `(() => {
-      ${pageFunctions.getElementsInDocumentString};
-      ${pageFunctions.isPositionFixedString};
-      ${pageFunctions.getNodeDetailsString};
-      return (${collectIFrameElements})();
-    })()`;
-
-    /** @type {LH.Artifacts['IFrameElements']} */
-    const iframeElements = await driver.evaluateAsync(expression, {useIsolation: true});
+    const iframeElements = await driver.evaluate(collectIFrameElements, {
+      args: [],
+      deps: [
+        pageFunctions.getElementsInDocumentString,
+        pageFunctions.isPositionFixedString,
+        pageFunctions.getNodeDetailsString,
+      ],
+    });
     return iframeElements;
   }
 }