core(driver): create eval code using interface

lighthouse-core/gather/driver.js

@@ -457,6 +457,22 @@ class Driver {
     return this._executionContext.evaluateAsync(expression, options);
   }
 
+  /**
+   * Evaluate a function in the context of the current page.
+   * If `useIsolation` is true, the function 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 a value of `mainFn`'s return type.
+   * @template {any[]} T, R
+   * @param {((...args: T) => R)} mainFn The main function to call.
+   * @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>}
+   */
+  async evaluate(mainFn, options) {
+    return this._executionContext.evaluate(mainFn, options);
+  }
+
   /**
    * @return {Promise<{url: string, data: string}|null>}
    */

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

@@ -83,9 +83,9 @@ 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 = window.__nativePromise || Promise;
-        const URL = window.__nativeURL || window.URL;
-        window.__lighthouseExecutionContextId = ${contextId};
+        const __nativePromise = globalThis.__nativePromise || Promise;
+        const URL = globalThis.__nativeURL || globalThis.URL;
+        globalThis.__lighthouseExecutionContextId = ${contextId};
         return new __nativePromise(function (resolve) {
           return __nativePromise.resolve()
             .then(_ => ${expression})
@@ -149,6 +149,29 @@ class ExecutionContext {
       throw err;
     }
   }
+
+  /**
+   * Evaluate a function in the context of the current page.
+   * If `useIsolation` is true, the function 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 a value of `mainFn`'s return type.
+   * @template {any[]} T, R
+   * @param {((...args: T) => R)} mainFn The main function to call.
+   * @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>}
+   */
+  evaluate(mainFn, options) {
+    const argsSerialized = options.args.map(arg => JSON.stringify(arg)).join(',');
+    const depsSerialized = options.deps ? options.deps.join('\n') : '';
+    const expression = `(() => {
+      ${depsSerialized}
+      ${mainFn}
+      return ${mainFn.name}(${argsSerialized});
+    })()`;
+    return this.evaluateAsync(expression, options);
+  }
 }
 
 module.exports = ExecutionContext;

lighthouse-core/gather/fetcher.js

@@ -175,7 +175,8 @@ class Fetcher {
       requestInterceptionPromise,
     ]).finally(() => clearTimeout(timeoutHandle));
 
-    const injectionPromise = this.driver.evaluateAsync(`${injectIframe}(${JSON.stringify(url)})`, {
+    const injectionPromise = this.driver.evaluate(injectIframe, {
+      args: [url],
       useIsolation: true,
     });
 

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

@@ -9,7 +9,7 @@ const LinkHeader = require('http-link-header');
 const Gatherer = require('./gatherer.js');
 const {URL} = require('../../lib/url-shim.js');
 const NetworkAnalyzer = require('../../lib/dependency-graph/simulator/network-analyzer.js');
-const {getElementsInDocumentString, getNodeDetailsString} = require('../../lib/page-functions.js');
+const pageFunctions = require('../../lib/page-functions.js');
 
 /* globals HTMLLinkElement getNodeDetails */
 
@@ -86,13 +86,14 @@ class LinkElements extends Gatherer {
   static getLinkElementsInDOM(passContext) {
     // We'll use evaluateAsync because the `node.getAttribute` method doesn't actually normalize
     // the values like access from JavaScript does.
-    return passContext.driver.evaluateAsync(`(() => {
-      ${getElementsInDocumentString};
-      ${getLinkElementsInDOM};
-      ${getNodeDetailsString};
-
-      return getLinkElementsInDOM();
-    })()`, {useIsolation: true});
+    return passContext.driver.evaluate(getLinkElementsInDOM, {
+      args: [],
+      useIsolation: true,
+      deps: [
+        pageFunctions.getNodeDetailsString,
+        pageFunctions.getElementsInDocument,
+      ],
+    });
   }
 
   /**

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

@@ -6,7 +6,30 @@
 'use strict';
 
 const Gatherer = require('./gatherer.js');
-const getElementsInDocumentString = require('../../lib/page-functions.js').getElementsInDocumentString; // eslint-disable-line max-len
+const pageFunctions = require('../../lib/page-functions.js');
+
+/* globals getElementsInDocument */
+
+/* istanbul ignore next */
+function collectMetaElements() {
+  // @ts-expect-error - getElementsInDocument put into scope via stringification
+  const metas = /** @type {HTMLMetaElement[]} */ (getElementsInDocument('head meta'));
+  return metas.map(meta => {
+    /** @param {string} name */
+    const getAttribute = name => {
+      const attr = meta.attributes.getNamedItem(name);
+      if (!attr) return;
+      return attr.value;
+    };
+    return {
+      name: meta.name.toLowerCase(),
+      content: meta.content,
+      property: getAttribute('property'),
+      httpEquiv: meta.httpEquiv ? meta.httpEquiv.toLowerCase() : undefined,
+      charset: getAttribute('charset'),
+    };
+  });
+}
 
 class MetaElements extends Gatherer {
   /**
@@ -18,19 +41,11 @@ class MetaElements extends Gatherer {
 
     // We'll use evaluateAsync because the `node.getAttribute` method doesn't actually normalize
     // the values like access from JavaScript does.
-    return driver.evaluateAsync(`(() => {
-      ${getElementsInDocumentString};
-
-      return getElementsInDocument('head meta').map(meta => {
-        return {
-          name: meta.name.toLowerCase(),
-          content: meta.content,
-          property: meta.attributes.property ? meta.attributes.property.value : undefined,
-          httpEquiv: meta.httpEquiv ? meta.httpEquiv.toLowerCase() : undefined,
-          charset: meta.attributes.charset ? meta.attributes.charset.value : undefined,
-        };
-      });
-    })()`, {useIsolation: true});
+    return driver.evaluate(collectMetaElements, {
+      args: [],
+      useIsolation: true,
+      deps: [pageFunctions.getElementsInDocument],
+    });
   }
 }
 

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

@@ -8,7 +8,6 @@
 const Gatherer = require('./gatherer.js');
 const NetworkAnalyzer = require('../../lib/dependency-graph/simulator/network-analyzer.js');
 const NetworkRequest = require('../../lib/network-request.js');
-const getElementsInDocumentString = require('../../lib/page-functions.js').getElementsInDocumentString; // eslint-disable-line max-len
 const pageFunctions = require('../../lib/page-functions.js');
 
 /* global getNodeDetails */
@@ -72,12 +71,14 @@ class ScriptElements extends Gatherer {
     const driver = passContext.driver;
     const mainResource = NetworkAnalyzer.findMainDocument(loadData.networkRecords, passContext.url);
 
-    /** @type {LH.Artifacts['ScriptElements']} */
-    const scripts = await driver.evaluateAsync(`(() => {
-      ${getElementsInDocumentString}
-      ${pageFunctions.getNodeDetailsString};
-      return (${collectAllScriptElements.toString()})();
-    })()`, {useIsolation: true});
+    const scripts = await driver.evaluate(collectAllScriptElements, {
+      args: [],
+      useIsolation: true,
+      deps: [
+        pageFunctions.getNodeDetailsString,
+        pageFunctions.getElementsInDocument,
+      ],
+    });
 
     for (const script of scripts) {
       if (script.content) script.requestId = mainResource.requestId;

lighthouse-core/gather/gatherers/seo/tap-targets.js

@@ -33,7 +33,7 @@ const tapTargetsSelector = TARGET_SELECTORS.join(',');
 
 /**
  * @param {HTMLElement} element
- * @returns {boolean}
+ * @return {boolean}
  */
 /* istanbul ignore next */
 function elementIsVisible(element) {
@@ -42,7 +42,7 @@ function elementIsVisible(element) {
 
 /**
  * @param {Element} element
- * @returns {LH.Artifacts.Rect[]}
+ * @return {LH.Artifacts.Rect[]}
  */
 /* istanbul ignore next */
 function getClientRects(element) {
@@ -65,7 +65,7 @@ function getClientRects(element) {
 /**
  * @param {Element} element
  * @param {string} tapTargetsSelector
- * @returns {boolean}
+ * @return {boolean}
  */
 /* istanbul ignore next */
 function elementHasAncestorTapTarget(element, tapTargetsSelector) {
@@ -119,7 +119,7 @@ function hasTextNodeSiblingsFormingTextBlock(element) {
  * Makes a reasonable guess, but for example gets it wrong if the element is surrounded by other
  * HTML elements instead of direct text nodes.
  * @param {Element} element
- * @returns {boolean}
+ * @return {boolean}
  */
 /* istanbul ignore next */
 function elementIsInTextBlock(element) {
@@ -160,7 +160,7 @@ function elementCenterIsAtZAxisTop(el, elCenterPoint) {
 /**
  * Finds all position sticky/absolute elements on the page and adds a class
  * that disables pointer events on them.
- * @returns {() => void} - undo function to re-enable pointer events
+ * @return {() => void} - undo function to re-enable pointer events
  */
 /* istanbul ignore next */
 function disableFixedAndStickyElementPointerEvents() {
@@ -186,7 +186,7 @@ function disableFixedAndStickyElementPointerEvents() {
 
 /**
  * @param {string} tapTargetsSelector
- * @returns {LH.Artifacts.TapTarget[]}
+ * @return {LH.Artifacts.TapTarget[]}
  */
 /* istanbul ignore next */
 function gatherTapTargets(tapTargetsSelector) {
@@ -285,23 +285,25 @@ class TapTargets extends Gatherer {
    * @return {Promise<LH.Artifacts.TapTarget[]>} All visible tap targets with their positions and sizes
    */
   afterPass(passContext) {
-    const expression = `(function() {
-      ${pageFunctions.getElementsInDocumentString};
-      ${disableFixedAndStickyElementPointerEvents.toString()};
-      ${elementIsVisible.toString()};
-      ${elementHasAncestorTapTarget.toString()};
-      ${elementCenterIsAtZAxisTop.toString()}
-      ${getClientRects.toString()};
-      ${hasTextNodeSiblingsFormingTextBlock.toString()};
-      ${elementIsInTextBlock.toString()};
-      ${RectHelpers.getRectCenterPoint.toString()};
-      ${pageFunctions.getNodeDetailsString};
-      ${gatherTapTargets.toString()};
-
-      return gatherTapTargets("${tapTargetsSelector}");
-    })()`;
-
-    return passContext.driver.evaluateAsync(expression, {useIsolation: true});
+    return passContext.driver.evaluate(gatherTapTargets, {
+      args: [tapTargetsSelector],
+      useIsolation: true,
+      deps: [
+        pageFunctions.getNodeDetailsString,
+        pageFunctions.getElementsInDocument,
+        disableFixedAndStickyElementPointerEvents,
+        elementIsVisible,
+        elementHasAncestorTapTarget,
+        elementCenterIsAtZAxisTop,
+        getClientRects,
+        hasTextNodeSiblingsFormingTextBlock,
+        elementIsInTextBlock,
+        RectHelpers.getRectCenterPoint,
+        pageFunctions.getNodePath,
+        pageFunctions.getNodeSelector,
+        pageFunctions.getNodeLabel,
+      ],
+    });
   }
 }
 

lighthouse-core/lib/page-functions.js

@@ -6,12 +6,21 @@
 // @ts-nocheck
 'use strict';
 
-/* global window document Node ShadowRoot */
-
 /**
+ * @fileoverview
  * Helper functions that are passed by `toString()` by Driver to be evaluated in target page.
+ *
+ * Important: this module should only be imported like this:
+ *     const pageFunctions = require('...');
+ * Never like this:
+ *     const {justWhatINeed} = require('...');
+ * Otherwise, minification will mangle the variable names and break usage.
  */
 
+/** @typedef {HTMLElementTagNameMap & {[id: string]: HTMLElement}} HTMLElementByTagName */
+
+/* global window document Node ShadowRoot */
+
 /**
  * The `exceptionDetails` provided by the debugger protocol does not contain the useful
  * information such as name, message, and stack trace of the error when it's wrapped in a
@@ -78,9 +87,10 @@ function checkTimeSinceLastLongTask() {
 }
 
 /**
- * @param {string=} selector Optional simple CSS selector to filter nodes on.
+ * @template {string} T
+ * @param {T} selector Optional simple CSS selector to filter nodes on.
  *     Combinators are not supported.
- * @return {Array<HTMLElement>}
+ * @return {Array<HTMLElementByTagName[T]>}
  */
 /* istanbul ignore next */
 function getElementsInDocument(selector) {
@@ -501,6 +511,7 @@ module.exports = {
   wrapRuntimeEvalErrorInBrowserString: wrapRuntimeEvalErrorInBrowser.toString(),
   registerPerformanceObserverInPageString: registerPerformanceObserverInPage.toString(),
   checkTimeSinceLastLongTaskString: checkTimeSinceLastLongTask.toString(),
+  getElementsInDocument,
   getElementsInDocumentString: getElementsInDocument.toString(),
   getOuterHTMLSnippetString: getOuterHTMLSnippet.toString(),
   getOuterHTMLSnippet: getOuterHTMLSnippet,