core(driver): create eval code using interface

lighthouse-core/gather/driver.js

@@ -438,16 +438,19 @@ 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.
+ * @template T
  * @param {string} expression
  * @param {{useIsolation?: boolean}=} options
  * @return {Promise<*>}
  */
  async evaluateAsync(expression, options = {}) {
- const contextId = options.useIsolation ? await this._getOrCreateIsolatedContextId() : undefined;
+ const contextId =
+ options.useIsolation ? await this._getOrCreateIsolatedContextId() : undefined;
 
  try {
  // `await` is not redundant here because we want to `catch` the async errors
@@ -464,6 +467,25 @@ class Driver {
  }
  }
 
+ /**
+ * Evaluate an expression (optionally defined in a structured manner, see `createEvalCode`
+ * in `page-functions.js`).
+ * See `evaluateAsync`.
+ * @template T, R
+ * @param {string | ((...args: T[]) => R)} expressionOrMainFn
+ * @param {{useIsolation?: boolean, args?: T[], deps?: Array<Function|string>}=} options
+ * @return {Promise<R>}
+ */
+ async evaluate(expressionOrMainFn, options = {}) {
+ if (typeof expressionOrMainFn !== 'string') {
+ expressionOrMainFn = pageFunctions.createEvalCode(expressionOrMainFn, {
+ mode: 'iife',
+ ...options,
+ });
+ }
+ return this.evaluateAsync(expressionOrMainFn, options);
+ }
+
  /**
  * Evaluate an expression in the given execution context; an undefined contextId implies the main
  * page without isolation.

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,13 @@ 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, {
+ 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,10 @@ 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, {
+ useIsolation: true,
+ deps: [pageFunctions.getElementsInDocument],
+ });
  }
 }
 

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

@@ -8,8 +8,7 @@
 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');
+const {getElementsInDocument, getNodeDetailsString} = require('../../lib/page-functions.js');
 
 /* global getNodeDetails */
 
@@ -19,7 +18,6 @@ const pageFunctions = require('../../lib/page-functions.js');
 /* istanbul ignore next */
 function collectAllScriptElements() {
  /** @type {HTMLScriptElement[]} */
- // @ts-expect-error - getElementsInDocument put into scope via stringification
  const scripts = getElementsInDocument('script'); // eslint-disable-line no-undef
 
  return scripts.map(script => {
@@ -72,12 +70,13 @@ 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, {
+ useIsolation: true,
+ deps: [
+ getNodeDetailsString,
+ 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,8 +6,39 @@
 // @ts-nocheck
 'use strict';
 
+/** @typedef {HTMLElementTagNameMap & {[id: string]: HTMLElement}} HTMLElementByTagName */
+
 /* global window document Node ShadowRoot */
 
+/**
+ * Creates valid JavaScript code given functions, strings of valid code, and arguments.
+ * @template T, R
+ * @param {(...args: T[]) => R} mainFn The main function to call. It's return value will be the return value
+ * of `createEvalCode`, wrapped in a Promise.
+ * @param {{mode?: 'iife'|'function', args?: T[], deps?: Array<Function|string>}} _ Set mode to `iife` to
+ * create a self-executing function expression, set to `function` to create just a function
+ * declaration statement. Args should match the args of `mainFn`, and can be any serializable
+ * value. `deps` are functions that must be defined for `mainFn` to work.
+ */
+function createEvalCode(mainFn, {mode, args, deps} = {}) {
+ const argsSerialized = args ? args.map(arg => JSON.stringify(arg)).join(',') : '';
+ const depsSerialized = deps ? deps.join('\n') : '';
+
+ if (!mode || mode === 'iife') {
+ return `(() => {
+ ${depsSerialized}
+ ${mainFn}
+ return ${mainFn.name}(${argsSerialized});
+ })()`;
+ } else {
+ return `function () {
+ ${depsSerialized}
+ ${mainFn}
+ return ${mainFn.name}.call(this, ${argsSerialized});
+ }`;
+ }
+}
+
 /**
  * Helper functions that are passed by `toString()` by Driver to be evaluated in target page.
  */
@@ -78,9 +109,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) {
@@ -463,9 +495,11 @@ const getNodeDetailsString = `function getNodeDetails(elem) {
 }`;
 
 module.exports = {
+ createEvalCode,
  wrapRuntimeEvalErrorInBrowserString: wrapRuntimeEvalErrorInBrowser.toString(),
  registerPerformanceObserverInPageString: registerPerformanceObserverInPage.toString(),
  checkTimeSinceLastLongTaskString: checkTimeSinceLastLongTask.toString(),
+ getElementsInDocument,
  getElementsInDocumentString: getElementsInDocument.toString(),
  getOuterHTMLSnippetString: getOuterHTMLSnippet.toString(),
  getOuterHTMLSnippet: getOuterHTMLSnippet,

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

@@ -35,7 +35,7 @@ describe('Link Elements gatherer', () => {
  function getPassData({linkElementsInDOM = [], headers = []}) {
  const url = 'https://example.com';
  const loadData = {networkRecords: [{url, responseHeaders: headers, resourceType: 'Document'}]};
- const driver = {evaluateAsync: () => Promise.resolve(linkElementsInDOM)};
+ const driver = {evaluate: () => Promise.resolve(linkElementsInDOM)};
  const passContext = {driver, url};
  return [passContext, loadData];
  }