lighthouse 9.6.7 → 10.0.0

package/core/gather/base-gatherer.js

@@ -0,0 +1,108 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * 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.
+ */
+
+import * as LH from '../../types/lh.js';
+
+/* eslint-disable no-unused-vars */
+
+/**
+ * Base class for all gatherers supporting both Fraggle Rock and the legacy flow.
+ * Most extending classes should implement the Fraggle Rock API and let this class handle translation.
+ * See core/gather/gatherers/gatherer.js for legacy method explanations.
+ *
+ * @implements {LH.Gatherer.GathererInstance}
+ * @implements {LH.Gatherer.FRGathererInstance}
+ */
+class FRGatherer {
+  /** @type {LH.Gatherer.GathererMeta} */
+  meta = {supportedModes: []};
+
+  /**
+   * Method to start observing a page for an arbitrary period of time.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<void>|void}
+   */
+  startInstrumentation(passContext) { }
+
+  /**
+   * Method to start observing a page when the measurements are very sensitive and
+   * should observe as little Lighthouse-induced work as possible.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<void>|void}
+   */
+  startSensitiveInstrumentation(passContext) { }
+
+  /**
+   * Method to stop observing a page when the measurements are very sensitive and
+   * should observe as little Lighthouse-induced work as possible.
+   *
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<void>|void}
+   */
+  stopSensitiveInstrumentation(passContext) { }
+
+  /**
+   * Method to end observing a page after an arbitrary period of time.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<void>|void}
+   */
+  stopInstrumentation(passContext) { }
+
+  /**
+   * Method to gather results about a page.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {LH.Gatherer.PhaseResult}
+   */
+  getArtifact(passContext) { }
+
+  /**
+   * Legacy property used to define the artifact ID. In Fraggle Rock, the artifact ID lives on the config.
+   * @return {keyof LH.GathererArtifacts}
+   */
+  get name() {
+    let name = this.constructor.name;
+    // Rollup will mangle class names in an known way–just trim until `$`.
+    if (name.includes('$')) {
+      name = name.substr(0, name.indexOf('$'));
+    }
+    // @ts-expect-error - assume that class name has been added to LH.GathererArtifacts.
+    return name;
+  }
+
+  /**
+   * Legacy method. Called before navigation to target url, roughly corresponds to `startInstrumentation`.
+   * @param {LH.Gatherer.PassContext} passContext
+   * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
+   */
+  async beforePass(passContext) {
+    await this.startInstrumentation({...passContext, dependencies: {}});
+    await this.startSensitiveInstrumentation({...passContext, dependencies: {}});
+  }
+
+  /**
+   * Legacy method. Should never be used by a Fraggle Rock gatherer, here for compat only.
+   * @param {LH.Gatherer.PassContext} passContext
+   * @return {LH.Gatherer.PhaseResult}
+   */
+  pass(passContext) { }
+
+  /**
+   * Legacy method. Roughly corresponds to `stopInstrumentation` or `getArtifact` depending on type of gatherer.
+   * @param {LH.Gatherer.PassContext} passContext
+   * @param {LH.Gatherer.LoadData} loadData
+   * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
+   */
+  async afterPass(passContext, loadData) {
+    if ('dependencies' in this.meta) {
+      throw Error('Gatherer with dependencies should override afterPass');
+    }
+    await this.stopSensitiveInstrumentation({...passContext, dependencies: {}});
+    await this.stopInstrumentation({...passContext, dependencies: {}});
+    return this.getArtifact({...passContext, dependencies: {}});
+  }
+}
+
+export default FRGatherer;

package/core/gather/driver/dom.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves a backend node ID (from a trace event, protocol, etc) to the object ID for use with
+ * `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {number} backendNodeId
+ * @return {Promise<string|undefined>}
+ */
+export function resolveNodeIdToObjectId(session: LH.Gatherer.FRProtocolSession, backendNodeId: number): Promise<string | undefined>;
+/**
+ * Resolves a proprietary devtools node path (created from page-function.js) to the object ID for use
+ * with `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ * Requires `DOM.getDocument` to have been called since the object's creation or it will always be `undefined`.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {string} path
+ * @return {Promise<string|undefined>}
+ */
+export function resolveDevtoolsNodePathToObjectId(session: LH.Gatherer.FRProtocolSession, path: string): Promise<string | undefined>;
+//# sourceMappingURL=dom.d.ts.map

package/core/gather/driver/dom.js

@@ -0,0 +1,57 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * 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.
+ */
+
+/**
+ * @param {Error} err
+ * @return {undefined}
+ */
+function handlePotentialMissingNodeError(err) {
+  if (
+    /No node.*found/.test(err.message) ||
+    /Node.*does not belong to the document/.test(err.message)
+  ) {
+    return undefined;
+  }
+  throw err;
+}
+
+/**
+ * Resolves a backend node ID (from a trace event, protocol, etc) to the object ID for use with
+ * `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {number} backendNodeId
+ * @return {Promise<string|undefined>}
+ */
+async function resolveNodeIdToObjectId(session, backendNodeId) {
+  try {
+    const resolveNodeResponse = await session.sendCommand('DOM.resolveNode', {backendNodeId});
+    return resolveNodeResponse.object.objectId;
+  } catch (err) {
+    return handlePotentialMissingNodeError(err);
+  }
+}
+
+/**
+ * Resolves a proprietary devtools node path (created from page-function.js) to the object ID for use
+ * with `Runtime.callFunctionOn`. `undefined` means the node could not be found.
+ * Requires `DOM.getDocument` to have been called since the object's creation or it will always be `undefined`.
+ *
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @param {string} path
+ * @return {Promise<string|undefined>}
+ */
+async function resolveDevtoolsNodePathToObjectId(session, path) {
+  try {
+    const {nodeId} = await session.sendCommand('DOM.pushNodeByPathToFrontend', {path});
+    const {object: {objectId}} = await session.sendCommand('DOM.resolveNode', {nodeId});
+    return objectId;
+  } catch (err) {
+    return handlePotentialMissingNodeError(err);
+  }
+}
+
+export {resolveNodeIdToObjectId, resolveDevtoolsNodePathToObjectId};

package/core/gather/driver/environment.d.ts

@@ -0,0 +1,35 @@
+export namespace UIStrings {
+    const warningSlowHostCpu: string;
+}
+/**
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @return {Promise<LH.Crdp.Browser.GetVersionResponse & {milestone: number}>}
+ */
+export function getBrowserVersion(session: LH.Gatherer.FRProtocolSession): Promise<import("devtools-protocol").Protocol.Browser.GetVersionResponse & {
+    milestone: number;
+}>;
+/**
+ * Computes the benchmark index to get a rough estimate of device class.
+ * @param {LH.Gatherer.FRTransitionalDriver['executionContext']} executionContext
+ * @return {Promise<number>}
+ */
+export function getBenchmarkIndex(executionContext: LH.Gatherer.FRTransitionalDriver['executionContext']): Promise<number>;
+/**
+ * Returns a warning if the host device appeared to be underpowered according to BenchmarkIndex.
+ *
+ * @param {{settings: LH.Config.Settings; baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>}} context
+ * @return {LH.IcuMessage | undefined}
+ */
+export function getSlowHostCpuWarning(context: {
+    settings: LH.Config.Settings;
+    baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>;
+}): LH.IcuMessage | undefined;
+/**
+ * @param {{settings: LH.Config.Settings, baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>}} context
+ * @return {Array<LH.IcuMessage>}
+ */
+export function getEnvironmentWarnings(context: {
+    settings: LH.Config.Settings;
+    baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>;
+}): Array<LH.IcuMessage>;
+//# sourceMappingURL=environment.d.ts.map

package/core/gather/driver/environment.js

@@ -0,0 +1,105 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * 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.
+ */
+
+import log from 'lighthouse-logger';
+
+import * as constants from '../../config/constants.js';
+import {pageFunctions} from '../../lib/page-functions.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+
+const UIStrings = {
+  /**
+   * @description Warning that the host device where Lighthouse is running appears to have a slower
+   * CPU than the expected Lighthouse baseline.
+   */
+  warningSlowHostCpu: 'The tested device appears to have a slower CPU than  ' +
+  'Lighthouse expects. This can negatively affect your performance score. Learn more about ' +
+  '[calibrating an appropriate CPU slowdown multiplier](https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md#cpu-throttling).',
+};
+
+/**
+ * We want to warn when the CPU seemed to be at least ~2x weaker than our regular target device.
+ * We're starting with a more conservative value that will increase over time to our true target threshold.
+ * @see https://github.com/GoogleChrome/lighthouse/blob/ccbc8002fd058770d14e372a8301cc4f7d256414/docs/throttling.md#calibrating-multipliers
+ */
+const SLOW_CPU_BENCHMARK_INDEX_THRESHOLD = 1000;
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+/**
+ * @param {LH.Gatherer.FRProtocolSession} session
+ * @return {Promise<LH.Crdp.Browser.GetVersionResponse & {milestone: number}>}
+ */
+async function getBrowserVersion(session) {
+  const status = {msg: 'Getting browser version', id: 'lh:gather:getVersion'};
+  log.time(status, 'verbose');
+  const version = await session.sendCommand('Browser.getVersion');
+  const match = version.product.match(/\/(\d+)/); // eg 'Chrome/71.0.3577.0'
+  const milestone = match ? parseInt(match[1]) : 0;
+  log.timeEnd(status);
+  return Object.assign(version, {milestone});
+}
+
+/**
+ * Computes the benchmark index to get a rough estimate of device class.
+ * @param {LH.Gatherer.FRTransitionalDriver['executionContext']} executionContext
+ * @return {Promise<number>}
+ */
+async function getBenchmarkIndex(executionContext) {
+  const status = {msg: 'Benchmarking machine', id: 'lh:gather:getBenchmarkIndex'};
+  log.time(status);
+  const indexVal = await executionContext.evaluate(pageFunctions.computeBenchmarkIndex, {
+    args: [],
+  });
+  log.timeEnd(status);
+  return indexVal;
+}
+
+/**
+ * Returns a warning if the host device appeared to be underpowered according to BenchmarkIndex.
+ *
+ * @param {{settings: LH.Config.Settings; baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>}} context
+ * @return {LH.IcuMessage | undefined}
+ */
+function getSlowHostCpuWarning(context) {
+  const {settings, baseArtifacts} = context;
+  const {throttling, throttlingMethod} = settings;
+  const defaultThrottling = constants.defaultSettings.throttling;
+
+  // We only want to warn when the user can take an action to fix it.
+  // Eventually, this should expand to cover DevTools.
+  if (settings.channel !== 'cli') return;
+
+  // Only warn if they are using the default throttling settings.
+  const isThrottledMethod = throttlingMethod === 'simulate' || throttlingMethod === 'devtools';
+  const isDefaultMultiplier =
+    throttling.cpuSlowdownMultiplier === defaultThrottling.cpuSlowdownMultiplier;
+  if (!isThrottledMethod || !isDefaultMultiplier) return;
+
+  // Only warn if the device didn't meet the threshold.
+  // See https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md#cpu-throttling
+  if (baseArtifacts.BenchmarkIndex > SLOW_CPU_BENCHMARK_INDEX_THRESHOLD) return;
+
+  return str_(UIStrings.warningSlowHostCpu);
+}
+
+/**
+ * @param {{settings: LH.Config.Settings, baseArtifacts: Pick<LH.Artifacts, 'BenchmarkIndex'>}} context
+ * @return {Array<LH.IcuMessage>}
+ */
+function getEnvironmentWarnings(context) {
+  return [
+    getSlowHostCpuWarning(context),
+  ].filter(/** @return {s is LH.IcuMessage} */ s => !!s);
+}
+
+export {
+  UIStrings,
+  getBrowserVersion,
+  getBenchmarkIndex,
+  getSlowHostCpuWarning,
+  getEnvironmentWarnings,
+};

package/core/gather/driver/execution-context.d.ts

@@ -0,0 +1,101 @@
+export class ExecutionContext {
+    /**
+     * 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` (injected by `cacheNativesOnNewDocument` above).
+     */
+    static _cachedNativesPreamble: string;
+    /**
+     * Serializes an array of arguments for use in an `eval` string across the protocol.
+     * @param {unknown[]} args
+     * @return {string}
+     */
+    static serializeArguments(args: unknown[]): string;
+    /** @param {LH.Gatherer.FRProtocolSession} session */
+    constructor(session: LH.Gatherer.FRProtocolSession);
+    _session: LH.Gatherer.FRProtocolSession;
+    /** @type {number|undefined} */
+    _executionContextId: number | undefined;
+    /**
+     * Marks how many execution context ids have been created, for purposes of having a unique
+     * value (that doesn't expose the actual execution context id) to
+     * use for __lighthouseExecutionContextUniqueIdentifier.
+     * @type {number}
+     */
+    _executionContextIdentifiersCreated: number;
+    /**
+     * Returns the isolated context ID currently in use.
+     */
+    getContextId(): number | undefined;
+    /**
+     * Clears the remembered context ID. Use this method when we have knowledge that the runtime context
+     * we were using has been destroyed by the browser and is no longer available.
+     */
+    clearContextId(): void;
+    /**
+     * Returns the cached isolated execution context ID or creates a new execution context for the main
+     * frame. The cached execution context is cleared on every gotoURL invocation, so a new one will
+     * always be created on the first call on a new page.
+     * @return {Promise<number>}
+     */
+    _getOrCreateIsolatedContextId(): Promise<number>;
+    /**
+     * Evaluate an expression in the given execution context; an undefined contextId implies the main
+     * page without isolation.
+     * @param {string} expression
+     * @param {number|undefined} contextId
+     * @return {Promise<*>}
+     */
+    _evaluateInContext(expression: string, contextId: number | undefined): Promise<any>;
+    /**
+     * 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<*>}
+     */
+    evaluateAsync(expression: string, options?: {
+        useIsolation?: boolean;
+    } | undefined): Promise<any>;
+    /**
+     * 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 {unknown[]} 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<Awaited<R>>}
+     */
+    evaluate<T extends unknown[], R>(mainFn: (...args: T) => R, options: {
+        args: T;
+        useIsolation?: boolean | undefined;
+        deps?: (string | Function)[] | undefined;
+    }): Promise<Awaited<R>>;
+    /**
+     * Evaluate a function on every new frame from now on.
+     * @template {unknown[]} 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>}
+     */
+    evaluateOnNewDocument<T_1 extends unknown[]>(mainFn: (...args: T_1) => void, options: {
+        args: T_1;
+        deps?: (string | Function)[] | undefined;
+    }): Promise<void>;
+    /**
+     * Cache native functions/objects inside window so we are sure polyfills do not overwrite the
+     * native implementations when the page loads.
+     * @return {Promise<void>}
+     */
+    cacheNativesOnNewDocument(): Promise<void>;
+}
+import * as LH from "../../../types/lh.js";
+//# sourceMappingURL=execution-context.d.ts.map