lighthouse 9.6.8 → 10.0.0

package/core/gather/gatherers/trace.js

@@ -0,0 +1,130 @@
+/**
+ * @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.
+ */
+
+/**
+ * @fileoverview
+ * This gatherer collects all network and page devtools protocol traffic during the timespan/navigation.
+ * This protocol log can be used to recreate the network records using lib/network-recorder.js.
+ */
+
+import FRGatherer from '../base-gatherer.js';
+import {TraceProcessor} from '../../lib/tracehouse/trace-processor.js';
+
+class Trace extends FRGatherer {
+  /** @type {LH.Trace} */
+  _trace = {traceEvents: []};
+
+  static getDefaultTraceCategories() {
+    return [
+      // Exclude default categories. We'll be selective to minimize trace size
+      '-*',
+
+      // Used instead of 'toplevel' in Chrome 71+
+      'disabled-by-default-lighthouse',
+
+      // Used for Cumulative Layout Shift metric
+      'loading',
+
+      // All compile/execute events are captured by parent events in devtools.timeline..
+      // But the v8 category provides some nice context for only <0.5% of the trace size
+      'v8',
+      // Same situation here. This category is there for RunMicrotasks only, but with other teams
+      // accidentally excluding microtasks, we don't want to assume a parent event will always exist
+      'v8.execute',
+
+      // For extracting UserTiming marks/measures
+      'blink.user_timing',
+
+      // Not mandatory but not used much
+      'blink.console',
+
+      // Most of the events we need are from these two categories
+      'devtools.timeline',
+      'disabled-by-default-devtools.timeline',
+
+      // Up to 450 (https://goo.gl/rBfhn4) JPGs added to the trace
+      'disabled-by-default-devtools.screenshot',
+
+      // This doesn't add its own events, but adds a `stackTrace` property to devtools.timeline events
+      'disabled-by-default-devtools.timeline.stack',
+
+      // Additional categories used by devtools. Not used by Lighthouse, but included to facilitate
+      // loading traces from Lighthouse into the Performance panel.
+      'disabled-by-default-devtools.timeline.frame',
+      'latencyInfo',
+
+      // A bug introduced in M92 causes these categories to crash targets on Linux.
+      // See https://github.com/GoogleChrome/lighthouse/issues/12835 for full investigation.
+      // 'disabled-by-default-v8.cpu_profiler',
+    ];
+  }
+
+  /**
+   * @param {LH.Gatherer.FRProtocolSession} session
+   * @return {Promise<LH.Trace>}
+   */
+  static async endTraceAndCollectEvents(session) {
+    /** @type {Array<LH.TraceEvent>} */
+    const traceEvents = [];
+
+    /**
+     * Listener for when dataCollected events fire for each trace chunk
+     * @param {LH.Crdp.Tracing.DataCollectedEvent} data
+     */
+    const dataListener = function(data) {
+      traceEvents.push(...data.value);
+    };
+    session.on('Tracing.dataCollected', dataListener);
+
+    return new Promise((resolve, reject) => {
+      session.once('Tracing.tracingComplete', _ => {
+        session.off('Tracing.dataCollected', dataListener);
+        resolve({traceEvents});
+      });
+
+      session.sendCommand('Tracing.end').catch(reject);
+    });
+  }
+
+  static symbol = Symbol('Trace');
+
+  /** @type {LH.Gatherer.GathererMeta} */
+  meta = {
+    symbol: Trace.symbol,
+    supportedModes: ['timespan', 'navigation'],
+  };
+
+  /**
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   */
+  async startSensitiveInstrumentation({driver, gatherMode, settings}) {
+    const traceCategories = Trace.getDefaultTraceCategories()
+      .concat(settings.additionalTraceCategories || []);
+    await driver.defaultSession.sendCommand('Page.enable');
+    await driver.defaultSession.sendCommand('Tracing.start', {
+      categories: traceCategories.join(','),
+      options: 'sampling-frequency=10000', // 1000 is default and too slow.
+    });
+
+    if (gatherMode === 'timespan') {
+      await driver.defaultSession.sendCommand('Tracing.recordClockSyncMarker',
+        {syncId: TraceProcessor.TIMESPAN_MARKER_ID});
+    }
+  }
+
+  /**
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   */
+  async stopSensitiveInstrumentation({driver}) {
+    this._trace = await Trace.endTraceAndCollectEvents(driver.defaultSession);
+  }
+
+  getArtifact() {
+    return this._trace;
+  }
+}
+
+export default Trace;

package/core/gather/gatherers/viewport-dimensions.d.ts

@@ -0,0 +1,10 @@
+export default ViewportDimensions;
+declare class ViewportDimensions extends FRGatherer {
+    /**
+     * @param {LH.Gatherer.FRTransitionalContext} passContext
+     * @return {Promise<LH.Artifacts.ViewportDimensions>}
+     */
+    getArtifact(passContext: LH.Gatherer.FRTransitionalContext): Promise<LH.Artifacts.ViewportDimensions>;
+}
+import FRGatherer from "../base-gatherer.js";
+//# sourceMappingURL=viewport-dimensions.d.ts.map

package/core/gather/gatherers/viewport-dimensions.js

@@ -0,0 +1,57 @@
+/**
+ * @license Copyright 2016 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 FRGatherer from '../base-gatherer.js';
+
+/* global window */
+
+/**
+ * @return {LH.Artifacts.ViewportDimensions}
+ */
+/* c8 ignore start */
+function getViewportDimensions() {
+  // window.innerWidth to get the scrollable size of the window (irrespective of zoom)
+  // window.outerWidth to get the size of the visible area
+  // window.devicePixelRatio to get ratio of logical pixels to physical pixels
+  return {
+    innerWidth: window.innerWidth,
+    innerHeight: window.innerHeight,
+    outerWidth: window.outerWidth,
+    outerHeight: window.outerHeight,
+    devicePixelRatio: window.devicePixelRatio,
+  };
+}
+/* c8 ignore stop */
+
+class ViewportDimensions extends FRGatherer {
+  /** @type {LH.Gatherer.GathererMeta} */
+  meta = {
+    supportedModes: ['snapshot', 'timespan', 'navigation'],
+  };
+
+  /**
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<LH.Artifacts.ViewportDimensions>}
+   */
+  async getArtifact(passContext) {
+    const driver = passContext.driver;
+
+    const dimensions = await driver.executionContext.evaluate(getViewportDimensions, {
+      args: [],
+      useIsolation: true,
+    });
+
+    const allNumeric = Object.values(dimensions).every(Number.isFinite);
+    if (!allNumeric) {
+      const results = JSON.stringify(dimensions);
+      throw new Error(`ViewportDimensions results were not numeric: ${results}`);
+    }
+
+    return dimensions;
+  }
+}
+
+export default ViewportDimensions;

package/core/gather/gatherers/web-app-manifest.d.ts

@@ -0,0 +1,32 @@
+export default WebAppManifest;
+declare class WebAppManifest extends FRGatherer {
+    /**
+     * @param {LH.Gatherer.FRProtocolSession} session
+     * @return {Promise<{url: string, data: string}|null>}
+     */
+    static fetchAppManifest(session: LH.Gatherer.FRProtocolSession): Promise<{
+        url: string;
+        data: string;
+    } | null>;
+    /**
+     * Uses the debugger protocol to fetch the manifest from within the context of
+     * the target page, reusing any credentials, emulation, etc, already established
+     * there.
+     *
+     * Returns the parsed manifest or null if the page had no manifest. If the manifest
+     * was unparseable as JSON, manifest.value will be undefined and manifest.warning
+     * will have the reason. See manifest-parser.js for more information.
+     *
+     * @param {LH.Gatherer.FRProtocolSession} session
+     * @param {string} pageUrl
+     * @return {Promise<LH.Artifacts.Manifest|null>}
+     */
+    static getWebAppManifest(session: LH.Gatherer.FRProtocolSession, pageUrl: string): Promise<LH.Artifacts.Manifest | null>;
+    /**
+     * @param {LH.Gatherer.FRTransitionalContext} context
+     * @return {Promise<LH.Artifacts['WebAppManifest']>}
+     */
+    getArtifact(context: LH.Gatherer.FRTransitionalContext): Promise<LH.Artifacts['WebAppManifest']>;
+}
+import FRGatherer from "../base-gatherer.js";
+//# sourceMappingURL=web-app-manifest.d.ts.map

package/core/gather/gatherers/web-app-manifest.js

@@ -0,0 +1,106 @@
+/**
+ * @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 {parseManifest} from '../../lib/manifest-parser.js';
+import FRGatherer from '../base-gatherer.js';
+
+class WebAppManifest extends FRGatherer {
+  /** @type {LH.Gatherer.GathererMeta} */
+  meta = {
+    supportedModes: ['snapshot', 'navigation'],
+  };
+
+  /**
+   * @param {LH.Gatherer.FRProtocolSession} session
+   * @return {Promise<{url: string, data: string}|null>}
+   */
+  static async fetchAppManifest(session) {
+    // In all environments but LR, Page.getAppManifest finishes very quickly.
+    // In LR, there is a bug that causes this command to hang until outgoing
+    // requests finish. This has been seen in long polling (where it will never
+    // return) and when other requests take a long time to finish. We allow 10 seconds
+    // for outgoing requests to finish. Anything more, and we continue the run without
+    // a manifest.
+    // Googlers, see: http://b/124008171
+    session.setNextProtocolTimeout(10000);
+    let response;
+    try {
+      response = await session.sendCommand('Page.getAppManifest');
+    } catch (err) {
+      if (err.code === 'PROTOCOL_TIMEOUT') {
+        // LR will timeout fetching the app manifest in some cases, move on without one.
+        // https://github.com/GoogleChrome/lighthouse/issues/7147#issuecomment-461210921
+        log.error('WebAppManifest', 'Failed fetching manifest', err);
+        return null;
+      }
+
+      throw err;
+    }
+
+    let data = response.data;
+
+    // We're not reading `response.errors` however it may contain critical and noncritical
+    // errors from Blink's manifest parser:
+    //   https://chromedevtools.github.io/debugger-protocol-viewer/tot/Page/#type-AppManifestError
+    if (!data) {
+      // If the data is empty, the page had no manifest.
+      return null;
+    }
+
+    const BOM_LENGTH = 3;
+    const BOM_FIRSTCHAR = 65279;
+    const isBomEncoded = data.charCodeAt(0) === BOM_FIRSTCHAR;
+
+    if (isBomEncoded) {
+      data = Buffer.from(data)
+        .slice(BOM_LENGTH)
+        .toString();
+    }
+
+    return {...response, data};
+  }
+
+  /**
+   * Uses the debugger protocol to fetch the manifest from within the context of
+   * the target page, reusing any credentials, emulation, etc, already established
+   * there.
+   *
+   * Returns the parsed manifest or null if the page had no manifest. If the manifest
+   * was unparseable as JSON, manifest.value will be undefined and manifest.warning
+   * will have the reason. See manifest-parser.js for more information.
+   *
+   * @param {LH.Gatherer.FRProtocolSession} session
+   * @param {string} pageUrl
+   * @return {Promise<LH.Artifacts.Manifest|null>}
+   */
+  static async getWebAppManifest(session, pageUrl) {
+    const status = {msg: 'Get webapp manifest', id: 'lh:gather:getWebAppManifest'};
+    log.time(status);
+    const response = await WebAppManifest.fetchAppManifest(session);
+    if (!response) return null;
+    const manifest = parseManifest(response.data, response.url, pageUrl);
+    log.timeEnd(status);
+    return manifest;
+  }
+
+  /**
+   * @param {LH.Gatherer.FRTransitionalContext} context
+   * @return {Promise<LH.Artifacts['WebAppManifest']>}
+   */
+  async getArtifact(context) {
+    const driver = context.driver;
+    const {finalDisplayedUrl} = context.baseArtifacts.URL;
+    try {
+      return await WebAppManifest.getWebAppManifest(driver.defaultSession, finalDisplayedUrl);
+    } catch {
+      return null;
+    }
+  }
+}
+
+export default WebAppManifest;

package/core/gather/navigation-runner.d.ts

@@ -0,0 +1,94 @@
+export type NavigationContext = {
+    driver: Driver;
+    page: LH.Puppeteer.Page;
+    resolvedConfig: LH.Config.ResolvedConfig;
+    navigation: LH.Config.NavigationDefn;
+    requestor: LH.NavigationRequestor;
+    baseArtifacts: LH.FRBaseArtifacts;
+    computedCache: Map<string, LH.ArbitraryEqualityMap>;
+};
+export type PhaseState = Omit<Parameters<typeof collectPhaseArtifacts>[0], 'phase'>;
+/**
+ * @param {LH.Puppeteer.Page|undefined} page
+ * @param {LH.NavigationRequestor|undefined} requestor
+ * @param {{config?: LH.Config, flags?: LH.Flags}} [options]
+ * @return {Promise<LH.Gatherer.FRGatherResult>}
+ */
+export function navigationGather(page: LH.Puppeteer.Page | undefined, requestor: LH.NavigationRequestor | undefined, options?: {
+    config?: import("../../types/config.js").default | undefined;
+    flags?: import("../index.js").Flags | undefined;
+} | undefined): Promise<LH.Gatherer.FRGatherResult>;
+/**
+ * @param {{driver: Driver, resolvedConfig: LH.Config.ResolvedConfig, requestor: LH.NavigationRequestor}} args
+ * @return {Promise<{baseArtifacts: LH.FRBaseArtifacts}>}
+ */
+export function _setup({ driver, resolvedConfig, requestor }: {
+    driver: Driver;
+    resolvedConfig: LH.Config.ResolvedConfig;
+    requestor: LH.NavigationRequestor;
+}): Promise<{
+    baseArtifacts: LH.FRBaseArtifacts;
+}>;
+/**
+ * @param {NavigationContext} navigationContext
+ * @return {Promise<{warnings: Array<LH.IcuMessage>}>}
+ */
+export function _setupNavigation({ requestor, driver, navigation, resolvedConfig }: NavigationContext): Promise<{
+    warnings: Array<LH.IcuMessage>;
+}>;
+/**
+ * @param {NavigationContext} navigationContext
+ * @return {Promise<{requestedUrl: string, mainDocumentUrl: string, navigationError: LH.LighthouseError | undefined, warnings: Array<LH.IcuMessage>}>}
+ */
+export function _navigate(navigationContext: NavigationContext): Promise<{
+    requestedUrl: string;
+    mainDocumentUrl: string;
+    navigationError: LH.LighthouseError | undefined;
+    warnings: Array<LH.IcuMessage>;
+}>;
+/**
+ * @param {NavigationContext} navigationContext
+ * @return {ReturnType<typeof _computeNavigationResult>}
+ */
+export function _navigation(navigationContext: NavigationContext): ReturnType<typeof _computeNavigationResult>;
+/**
+ * @param {{driver: Driver, page: LH.Puppeteer.Page, resolvedConfig: LH.Config.ResolvedConfig, requestor: LH.NavigationRequestor; baseArtifacts: LH.FRBaseArtifacts, computedCache: NavigationContext['computedCache']}} args
+ * @return {Promise<{artifacts: Partial<LH.FRArtifacts & LH.FRBaseArtifacts>}>}
+ */
+export function _navigations(args: {
+    driver: Driver;
+    page: LH.Puppeteer.Page;
+    resolvedConfig: LH.Config.ResolvedConfig;
+    requestor: LH.NavigationRequestor;
+    baseArtifacts: LH.FRBaseArtifacts;
+    computedCache: NavigationContext['computedCache'];
+}): Promise<{
+    artifacts: Partial<LH.FRArtifacts & LH.FRBaseArtifacts>;
+}>;
+/**
+ * @param {{requestedUrl?: string, driver: Driver, resolvedConfig: LH.Config.ResolvedConfig, lhBrowser?: LH.Puppeteer.Browser, lhPage?: LH.Puppeteer.Page}} args
+ */
+export function _cleanup({ requestedUrl, driver, resolvedConfig, lhBrowser, lhPage }: {
+    requestedUrl?: string;
+    driver: Driver;
+    resolvedConfig: LH.Config.ResolvedConfig;
+    lhBrowser?: LH.Puppeteer.Browser;
+    lhPage?: LH.Puppeteer.Page;
+}): Promise<void>;
+import { Driver } from "./driver.js";
+import { collectPhaseArtifacts } from "./runner-helpers.js";
+import { LighthouseError } from "../lib/lh-error.js";
+/**
+ * @param {NavigationContext} navigationContext
+ * @param {PhaseState} phaseState
+ * @param {Awaited<ReturnType<typeof _setupNavigation>>} setupResult
+ * @param {Awaited<ReturnType<typeof _navigate>>} navigateResult
+ * @return {Promise<{artifacts: Partial<LH.GathererArtifacts>, warnings: Array<LH.IcuMessage>, pageLoadError: LH.LighthouseError | undefined}>}
+ */
+declare function _computeNavigationResult(navigationContext: NavigationContext, phaseState: PhaseState, setupResult: Awaited<ReturnType<typeof _setupNavigation>>, navigateResult: Awaited<ReturnType<typeof _navigate>>): Promise<{
+    artifacts: Partial<LH.GathererArtifacts>;
+    warnings: Array<LH.IcuMessage>;
+    pageLoadError: LH.LighthouseError | undefined;
+}>;
+export {};
+//# sourceMappingURL=navigation-runner.d.ts.map