lighthouse 9.5.0-dev.20221114 → 9.5.0-dev.20221116

package/core/computed/computed-artifact.js

@@ -12,9 +12,9 @@ import {ArbitraryEqualityMap} from '../lib/arbitrary-equality-map.js';
  * Decorate computableArtifact with a caching `request()` method which will
  * automatically call `computableArtifact.compute_()` under the hood.
  * @template {{name: string, compute_(dependencies: unknown, context: LH.Artifacts.ComputedContext): Promise<unknown>}} C
- * @template {Array<keyof FirstParamType<C['compute_']>>} K
+ * @template {Array<keyof LH.Util.FirstParamType<C['compute_']>>} K
  * @param {C} computableArtifact
- * @param {(K & ([keyof FirstParamType<C['compute_']>] extends [K[number]] ? unknown : never)) | null} keys List of properties of `dependencies` used by `compute_`; other properties are filtered out. Use `null` to allow all properties. Ensures that only required properties are used for caching result.
+ * @param {(K & ([keyof LH.Util.FirstParamType<C['compute_']>] extends [K[number]] ? unknown : never)) | null} keys List of properties of `dependencies` used by `compute_`; other properties are filtered out. Use `null` to allow all properties. Ensures that only required properties are used for caching result.
  */
 function makeComputedArtifact(computableArtifact, keys) {
   // tsc (3.1) has more difficulty with template inter-references in jsdoc, so
@@ -22,7 +22,7 @@ function makeComputedArtifact(computableArtifact, keys) {
   // polymorphic-this behavior for C.
   /**
    * Return an automatically cached result from the computed artifact.
-   * @param {FirstParamType<C['compute_']>} dependencies
+   * @param {LH.Util.FirstParamType<C['compute_']>} dependencies
    * @param {LH.Artifacts.ComputedContext} context
    * @return {ReturnType<C['compute_']>}
    */

package/core/computed/load-simulator.js

@@ -11,7 +11,7 @@ import {NetworkAnalysis} from './network-analysis.js';
 
 class LoadSimulator {
   /**
-   * @param {{devtoolsLog: LH.DevtoolsLog, settings: Immutable<LH.Config.Settings>}} data
+   * @param {{devtoolsLog: LH.DevtoolsLog, settings: LH.Audit.Context['settings']}} data
    * @param {LH.Artifacts.ComputedContext} context
    * @return {Promise<Simulator>}
    */

package/core/computed/metrics/responsiveness.js

@@ -131,7 +131,7 @@ class Responsiveness {
   }
 
   /**
-   * @param {{trace: LH.Trace, settings: Immutable<LH.Config.Settings>}} data
+   * @param {{trace: LH.Trace, settings: LH.Audit.Context['settings']}} data
    * @param {LH.Artifacts.ComputedContext} context
    * @return {Promise<EventTimingEvent|FallbackTimingEvent|null>}
    */

package/core/computed/metrics/timing-summary.js

@@ -24,7 +24,7 @@ class TimingSummary {
      * @param {LH.Trace} trace
      * @param {LH.DevtoolsLog} devtoolsLog
      * @param {LH.Artifacts['GatherContext']} gatherContext
-     * @param {ImmutableObject<LH.Config.Settings>} settings
+     * @param {LH.Util.ImmutableObject<LH.Config.Settings>} settings
      * @param {LH.Artifacts['URL']} URL
      * @param {LH.Artifacts.ComputedContext} context
      * @return {Promise<{metrics: LH.Artifacts.TimingSummary, debugInfo: Record<string,boolean>}>}
@@ -134,7 +134,7 @@ class TimingSummary {
     return {metrics, debugInfo};
   }
   /**
-   * @param {{trace: LH.Trace, devtoolsLog: LH.DevtoolsLog, gatherContext: LH.Artifacts['GatherContext']; settings: ImmutableObject<LH.Config.Settings>, URL: LH.Artifacts['URL']}} data
+   * @param {{trace: LH.Trace, devtoolsLog: LH.DevtoolsLog, gatherContext: LH.Artifacts['GatherContext']; settings: LH.Util.ImmutableObject<LH.Config.Settings>, URL: LH.Artifacts['URL']}} data
    * @param {LH.Artifacts.ComputedContext} context
    * @return {Promise<{metrics: LH.Artifacts.TimingSummary, debugInfo: Record<string,boolean>}>}
    */

package/core/computed/network-analysis.js

@@ -11,7 +11,7 @@ import {NetworkRecords} from './network-records.js';
 class NetworkAnalysis {
   /**
    * @param {Array<LH.Artifacts.NetworkRequest>} records
-   * @return {StrictOmit<LH.Artifacts.NetworkAnalysis, 'throughput'>}
+   * @return {LH.Util.StrictOmit<LH.Artifacts.NetworkAnalysis, 'throughput'>}
    */
   static computeRTTAndServerResponseTime(records) {
     // First pass compute the estimated observed RTT to each origin's servers.

package/core/computed/resource-summary.js

@@ -34,7 +34,7 @@ class ResourceSummary {
   /**
    * @param {Array<LH.Artifacts.NetworkRequest>} networkRecords
    * @param {LH.Artifacts.URL} URLArtifact
-   * @param {ImmutableObject<LH.Budget[]|null>} budgets
+   * @param {LH.Util.ImmutableObject<LH.Budget[]|null>} budgets
    * @return {Record<LH.Budget.ResourceType, ResourceEntry>}
    */
   static summarize(networkRecords, URLArtifact, budgets) {
@@ -99,7 +99,7 @@ class ResourceSummary {
   }
 
   /**
-   * @param {{URL: LH.Artifacts['URL'], devtoolsLog: LH.DevtoolsLog, budgets: ImmutableObject<LH.Budget[]|null>}} data
+   * @param {{URL: LH.Artifacts['URL'], devtoolsLog: LH.DevtoolsLog, budgets: LH.Util.ImmutableObject<LH.Budget[]|null>}} data
    * @param {LH.Artifacts.ComputedContext} context
    * @return {Promise<Record<LH.Budget.ResourceType,ResourceEntry>>}
    */

package/core/config/budget.js

@@ -135,9 +135,9 @@ class Budget {
    * Returns the budget that applies to a given URL.
    * If multiple budgets match based on thier 'path' property,
    * then the last-listed of those budgets is returned.
-   * @param {Immutable<Array<LH.Budget>>|null} budgets
+   * @param {LH.Util.Immutable<Array<LH.Budget>>|null} budgets
    * @param {string|undefined} url
-   * @return {Immutable<LH.Budget> | undefined} budget
+   * @return {LH.Util.Immutable<LH.Budget> | undefined} budget
    */
   static getMatchingBudget(budgets, url) {
     if (budgets === null || url === undefined) return;

package/core/config/config-helpers.js

@@ -299,10 +299,10 @@ function requireAudit(auditPath, coreAuditList, configDir) {
  * Creates a settings object from potential flags object by dropping all the properties
  * that don't exist on Config.Settings.
  * @param {Partial<LH.Flags>=} flags
- * @return {RecursivePartial<LH.Config.Settings>}
+ * @return {LH.Util.RecursivePartial<LH.Config.Settings>}
 */
 function cleanFlagsForSettings(flags = {}) {
-  /** @type {RecursivePartial<LH.Config.Settings>} */
+  /** @type {LH.Util.RecursivePartial<LH.Config.Settings>} */
   const settings = {};
 
   for (const key of Object.keys(flags)) {

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

@@ -25,7 +25,9 @@ const MAX_WEBP_SIZE = 16383;
  * @param {S} str
  */
 function kebabCaseToCamelCase(str) {
-  return /** @type {KebabToCamelCase<S>} */ (str.replace(/(-\w)/g, m => m[1].toUpperCase()));
+  return /** @type {LH.Util.KebabToCamelCase<S>} */ (
+    str.replace(/(-\w)/g, m => m[1].toUpperCase())
+  );
 }
 
 /* c8 ignore start */

package/core/index.js

@@ -10,9 +10,13 @@ import {Runner} from './runner.js';
 import {CriConnection} from './legacy/gather/connections/cri.js';
 import {Config} from './legacy/config/config.js';
 import UrlUtils from './lib/url-utils.js';
-import * as fraggleRock from './api.js';
 import {Driver} from './legacy/gather/driver.js';
 import {initializeConfig} from './config/config.js';
+import {UserFlow, auditGatherSteps} from './user-flow.js';
+import {ReportGenerator} from '../report/generator/report-generator.js';
+import {startTimespanGather} from './gather/timespan-runner.js';
+import {snapshotGather} from './gather/snapshot-runner.js';
+import {navigationGather} from './gather/navigation-runner.js';
 
 /** @typedef {import('./legacy/gather/connections/connection.js').Connection} Connection */
 
@@ -40,7 +44,7 @@ import {initializeConfig} from './config/config.js';
  * @return {Promise<LH.RunnerResult|undefined>}
  */
 async function lighthouse(url, flags = {}, configJSON, page) {
-  return fraggleRock.navigation(page, url, {config: configJSON, flags});
+  return navigation(page, url, {config: configJSON, flags});
 }
 
 /**
@@ -73,6 +77,75 @@ async function legacyNavigation(url, flags = {}, configJSON, userConnection) {
   return Runner.audit(artifacts, options);
 }
 
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {LH.UserFlow.Options} [options]
+ */
+async function startFlow(page, options) {
+  return new UserFlow(page, options);
+}
+
+/**
+ * @param {LH.Puppeteer.Page|undefined} page
+ * @param {LH.NavigationRequestor|undefined} requestor
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<LH.RunnerResult|undefined>}
+ */
+async function navigation(page, requestor, options) {
+  const gatherResult = await navigationGather(page, requestor, options);
+  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+}
+
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<LH.RunnerResult|undefined>}
+ */
+async function snapshot(page, options) {
+  const gatherResult = await snapshotGather(page, options);
+  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+}
+
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<{endTimespan: () => Promise<LH.RunnerResult|undefined>}>}
+ */
+async function startTimespan(page, options) {
+  const {endTimespanGather} = await startTimespanGather(page, options);
+  const endTimespan = async () => {
+    const gatherResult = await endTimespanGather();
+    return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+  };
+  return {endTimespan};
+}
+
+/**
+ * @template {LH.Result|LH.FlowResult} R
+ * @param {R} result
+ * @param {[R] extends [LH.Result] ? LH.OutputMode : Exclude<LH.OutputMode, 'csv'>} [format]
+ * @return {string}
+ */
+function generateReport(result, format = 'html') {
+  const reportOutput = ReportGenerator.generateReport(result, format);
+  if (Array.isArray(reportOutput)) {
+    // In theory the output should never be an array.
+    // This is mostly for type checking.
+    return reportOutput[0];
+  } else {
+    return reportOutput;
+  }
+}
+
+/**
+ * @param {LH.UserFlow.FlowArtifacts} flowArtifacts
+ * @param {LH.Config.Json} [config]
+ */
+async function auditFlowArtifacts(flowArtifacts, config) {
+  const {gatherSteps, name} = flowArtifacts;
+  return await auditGatherSteps(gatherSteps, {name, config});
+}
+
 /**
  * Generate a Lighthouse Config.
  * @param {LH.Config.Json=} configJson Configuration for the Lighthouse run. If
@@ -113,6 +186,12 @@ export {default as Gatherer} from './gather/base-gatherer.js';
 export {NetworkRecords} from './computed/network-records.js';
 export {
   legacyNavigation,
+  startFlow,
+  navigation,
+  startTimespan,
+  snapshot,
+  generateReport,
+  auditFlowArtifacts,
   generateConfig,
   generateLegacyConfig,
   getAuditList,

package/core/lib/lantern-trace-saver.js

@@ -130,7 +130,7 @@ function convertNodeTimingsToTrace(nodeTimings) {
     if (startTime === endTime) endTime += 0.3;
 
     const requestData = {requestId: requestId.toString(), frame};
-    /** @type {StrictOmit<LH.TraceEvent, 'name'|'ts'|'args'>} */
+    /** @type {LH.Util.StrictOmit<LH.TraceEvent, 'name'|'ts'|'args'>} */
     const baseRequestEvent = {...baseEvent, ph: 'I', s: 't', dur: 0};
 
     const sendRequestData = {

package/core/lib/network-request.js

@@ -89,7 +89,7 @@ const HEADER_PROTOCOL_IS_H2 = 'X-ProtocolIsH2';
  * @property {number} responseMs
  */
 
-/** @type {SelfMap<LH.Crdp.Network.ResourceType>} */
+/** @type {LH.Util.SelfMap<LH.Crdp.Network.ResourceType>} */
 const RESOURCE_TYPES = {
   XHR: 'XHR',
   Fetch: 'Fetch',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lighthouse",
   "type": "module",
-  "version": "9.5.0-dev.20221114",
+  "version": "9.5.0-dev.20221116",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./core/index.js",
   "bin": {

package/report/generator/report-generator.js

@@ -146,28 +146,42 @@ class ReportGenerator {
       .join(CRLF);
   }
 
+  /**
+   * @param {LHResult|FlowResult} result
+   * @return {result is FlowResult}
+   */
+  static isFlowResult(result) {
+    return 'steps' in result;
+  }
+
   /**
    * Creates the results output in a format based on the `mode`.
-   * @param {LHResult} lhr
+   * @param {LHResult|FlowResult} result
    * @param {LHResult['configSettings']['output']} outputModes
    * @return {string|string[]}
    */
-  static generateReport(lhr, outputModes) {
+  static generateReport(result, outputModes) {
     const outputAsArray = Array.isArray(outputModes);
     if (typeof outputModes === 'string') outputModes = [outputModes];
 
     const output = outputModes.map(outputMode => {
       // HTML report.
       if (outputMode === 'html') {
-        return ReportGenerator.generateReportHtml(lhr);
+        if (ReportGenerator.isFlowResult(result)) {
+          return ReportGenerator.generateFlowReportHtml(result);
+        }
+        return ReportGenerator.generateReportHtml(result);
       }
       // CSV report.
       if (outputMode === 'csv') {
-        return ReportGenerator.generateReportCSV(lhr);
+        if (ReportGenerator.isFlowResult(result)) {
+          throw new Error('CSV output is not support for user flows');
+        }
+        return ReportGenerator.generateReportCSV(result);
       }
       // JSON report.
       if (outputMode === 'json') {
-        return JSON.stringify(lhr, null, 2);
+        return JSON.stringify(result, null, 2);
       }
 
       throw new Error('Invalid output mode: ' + outputMode);

package/report/test/generator/report-generator-test.js

@@ -16,6 +16,7 @@ import {ReportGenerator} from '../../generator/report-generator.js';
 import {readJson} from '../../../core/test/test-utils.js';
 
 const sampleResults = readJson('core/test/results/sample_v2.json');
+const sampleFlowResult = readJson('core/test/fixtures/fraggle-rock/reports/sample-flow-result.json');
 
 describe('ReportGenerator', () => {
   describe('#replaceStrings', () => {
@@ -75,12 +76,23 @@ describe('ReportGenerator', () => {
       assert.doesNotThrow(_ => JSON.parse(jsonOutput));
     });
 
+    it('creates JSON for flow result', () => {
+      const jsonOutput = ReportGenerator.generateReport(sampleFlowResult, 'json');
+      assert.doesNotThrow(_ => JSON.parse(jsonOutput));
+    });
+
     it('creates HTML for results', () => {
       const htmlOutput = ReportGenerator.generateReport(sampleResults, 'html');
       assert.ok(/<!doctype/gim.test(htmlOutput));
       assert.ok(/<html lang="en"/gim.test(htmlOutput));
     });
 
+    it('creates HTML for flow result', () => {
+      const htmlOutput = ReportGenerator.generateReport(sampleFlowResult, 'html');
+      assert.ok(/<!doctype/gim.test(htmlOutput));
+      assert.ok(/<html lang="en"/gim.test(htmlOutput));
+    });
+
     it('creates CSV for results', async () => {
       const path = './.results-as-csv.csv';
 
@@ -126,6 +138,12 @@ category,audit,score,displayValue,description
       expect(csvOutput).toContain('pwa');
     });
 
+    it('throws when creating CSV for flow result', () => {
+      expect(() => {
+        ReportGenerator.generateReport(sampleFlowResult, 'csv');
+      }).toThrow('CSV output is not support for user flows');
+    });
+
     it('writes extended info', () => {
       const htmlOutput = ReportGenerator.generateReport(sampleResults, 'html');
       const outputCheck = new RegExp('dobetterweb/dbw_tester.css', 'i');

package/types/artifacts.d.ts

@@ -18,10 +18,12 @@ import Gatherer from './gatherer';
 import {IcuMessage} from './lhr/i18n';
 import LHResult from './lhr/lhr'
 import Protocol from './protocol';
+import Util from './utility-types.js';
+import Audit from './audit.js';
 
 export interface Artifacts extends BaseArtifacts, GathererArtifacts {}
 
-export type FRArtifacts = StrictOmit<Artifacts,
+export type FRArtifacts = Util.StrictOmit<Artifacts,
   | 'Fonts'
   | 'Manifest'
   | 'MixedContent'
@@ -179,7 +181,7 @@ export interface GathererArtifacts extends PublicGathererArtifacts,LegacyBaseArt
 }
 
 declare module Artifacts {
-  type ComputedContext = Immutable<{
+  type ComputedContext = Util.Immutable<{
     computedCache: Map<string, ArbitraryEqualityMap>;
   }>;
 
@@ -634,7 +636,7 @@ declare module Artifacts {
   interface MetricComputationDataInput {
     devtoolsLog: DevtoolsLog;
     trace: Trace;
-    settings: Immutable<Config.Settings>;
+    settings: Audit.Context['settings'];
     gatherContext: Artifacts['GatherContext'];
     simulator?: InstanceType<typeof Simulator>;
     URL: Artifacts['URL'];

package/types/audit.d.ts

@@ -11,6 +11,7 @@ import Config from './config';
 import Gatherer from './gatherer';
 import {IcuMessage} from './lhr/i18n';
 import * as AuditResult from './lhr/audit-result';
+import Util from './utility-types.js';
 
 declare module Audit {
   export import Details = AuditDetails;
@@ -18,7 +19,7 @@ declare module Audit {
   export type ScoreDisplayMode = AuditResult.ScoreDisplayMode;
   export type ScoreDisplayModes = AuditResult.ScoreDisplayModes;
 
-  type Context = Immutable<{
+  type Context = Util.Immutable<{
     /** audit options */
     options: Record<string, any>;
     settings: Config.Settings;

package/types/externs.d.ts

@@ -8,101 +8,6 @@ import {Artifacts} from './artifacts';
 import LHResult from './lhr/lhr';
 import {SharedFlagsSettings, OutputMode} from './lhr/settings';
 
-declare global {
-  // Augment Intl to include
-  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
-  namespace Intl {
-    var getCanonicalLocales: (locales?: string | Array<string>) => Array<string>;
-  }
-
-  interface Window {
-    // Cached native functions/objects for use in case the page overwrites them.
-    // See: `executionContext.cacheNativesOnNewDocument`.
-    __nativePromise: PromiseConstructor;
-    __nativePerformance: Performance;
-    __nativeFetch: typeof fetch,
-    __nativeURL: typeof URL;
-    __ElementMatches: Element['matches'];
-    __HTMLElementBoundingClientRect: HTMLElement['getBoundingClientRect'];
-
-    /** Used for monitoring long tasks in the test page. */
-    ____lastLongTask?: number;
-
-    /** Used by FullPageScreenshot gatherer. */
-    __lighthouseNodesDontTouchOrAllVarianceGoesAway: Map<Element, string>;
-    __lighthouseExecutionContextUniqueIdentifier?: number;
-
-    /** Injected into the page when the `--debug` flag is used. */
-    continueLighthouseRun(): void;
-
-    // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
-    requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
-  }
-
-  /** Make properties K in T optional. */
-  type MakeOptional<T, K extends keyof T> = {
-    [P in Exclude<keyof T, K>]: T[P]
-  } & {
-    [P in K]+?: T[P]
-  }
-
-  /** An object with the keys in the union K mapped to themselves as values. */
-  type SelfMap<K extends string> = {
-    [P in K]: P;
-  };
-
-  /** Make optional all properties on T and any properties on object properties of T. */
-  type RecursivePartial<T> =
-    // Recurse into arrays and tuples: elements aren't (newly) optional, but any properties they have are.
-    T extends (infer U)[] ? RecursivePartial<U>[] :
-    // Recurse into objects: properties and any of their properties are optional.
-    T extends object ? {[P in keyof T]?: RecursivePartial<T[P]>} :
-    // Strings, numbers, etc. (terminal types) end here.
-    T;
-
-  /** Recursively makes all properties of T read-only. */
-  type Immutable<T> =
-    T extends Function ? T :
-    T extends Array<infer R> ? ImmutableArray<R> :
-    T extends Map<infer K, infer V> ? ImmutableMap<K, V> :
-    T extends Set<infer M> ? ImmutableSet<M> :
-    T extends object ? ImmutableObject<T> :
-    T
-
-  // Intermediate immutable types. Prefer e.g. Immutable<Set<T>> over direct use.
-  type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
-  type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
-  type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
-  type ImmutableObject<T> = {
-    readonly [K in keyof T]: Immutable<T[K]>;
-  };
-
-  /**
-   * Exclude void from T
-   */
-  type NonVoid<T> = T extends void ? never : T;
-
-  /** Remove properties K from T. */
-  type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
-
-  /** Obtain the type of the first parameter of a function. */
-  type FirstParamType<T extends (arg1: any, ...args: any[]) => any> =
-    T extends (arg1: infer P, ...args: any[]) => any ? P : never;
-
-  /**
-   * If `S` is a kebab-style string `S`, convert to camelCase.
-   */
-  type KebabToCamelCase<S> =
-    S extends `${infer T}-${infer U}` ?
-    `${T}${Capitalize<KebabToCamelCase<U>>}` :
-    S
-
-  /** Returns T with any kebab-style property names rewritten as camelCase. */
-  type CamelCasify<T> = {
-    [K in keyof T as KebabToCamelCase<K>]: T[K];
-  }
-}
-
 /**
  * Extends the flags in SharedFlagsSettings with flags used to configure the
  * Lighthouse module but will not end up in the Config settings.

package/types/global-lh.d.ts

@@ -22,6 +22,7 @@ import * as Settings from './lhr/settings';
 import Treemap_ from './lhr/treemap';
 import UserFlow_ from './user-flow';
 import Puppeteer_ from './puppeteer';
+import Util_ from './utility-types.js';
 
 // Construct hierarchy of global types under the LH namespace.
 declare global {
@@ -29,6 +30,8 @@ declare global {
     export type ArbitraryEqualityMap = ArbitraryEqualityMap_;
     export type NavigationRequestor = string | (() => Promise<void> | void);
 
+    export import Util = Util_;
+
     export import Puppeteer = Puppeteer_;
 
     // artifacts.d.ts

package/types/node.d.ts

@@ -7,6 +7,38 @@
 declare global {
   var isDevtools: boolean | undefined;
   var isLightrider: boolean | undefined;
+
+  // Augment Intl to include
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
+  namespace Intl {
+    var getCanonicalLocales: (locales?: string | Array<string>) => Array<string>;
+  }
+
+  // Some functions defined in node are stringified and run in the browser.
+  // Ensure those functions are working with the correct browser environment.
+  interface Window {
+    // Cached native functions/objects for use in case the page overwrites them.
+    // See: `executionContext.cacheNativesOnNewDocument`.
+    __nativePromise: PromiseConstructor;
+    __nativePerformance: Performance;
+    __nativeFetch: typeof fetch,
+    __nativeURL: typeof URL;
+    __ElementMatches: Element['matches'];
+    __HTMLElementBoundingClientRect: HTMLElement['getBoundingClientRect'];
+
+    /** Used for monitoring long tasks in the test page. */
+    ____lastLongTask?: number;
+
+    /** Used by FullPageScreenshot gatherer. */
+    __lighthouseNodesDontTouchOrAllVarianceGoesAway: Map<Element, string>;
+    __lighthouseExecutionContextUniqueIdentifier?: number;
+
+    /** Injected into the page when the `--debug` flag is used. */
+    continueLighthouseRun(): void;
+
+    // Not defined in tsc yet: https://github.com/microsoft/TypeScript/issues/40807
+    requestIdleCallback(callback: (deadline: {didTimeout: boolean, timeRemaining: () => DOMHighResTimeStamp}) => void, options?: {timeout: number}): number;
+  }
 }
 
 export {};

package/types/utility-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license Copyright 2022 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.
+ */
+
+declare module Util {
+  /** Make properties K in T optional. */
+  type MakeOptional<T, K extends keyof T> = {
+    [P in Exclude<keyof T, K>]: T[P]
+  } & {
+    [P in K]+?: T[P]
+  }
+
+  /** An object with the keys in the union K mapped to themselves as values. */
+  type SelfMap<K extends string> = {
+    [P in K]: P;
+  };
+
+  /** Make optional all properties on T and any properties on object properties of T. */
+  type RecursivePartial<T> =
+    // Recurse into arrays and tuples: elements aren't (newly) optional, but any properties they have are.
+    T extends (infer U)[] ? RecursivePartial<U>[] :
+    // Recurse into objects: properties and any of their properties are optional.
+    T extends object ? {[P in keyof T]?: RecursivePartial<T[P]>} :
+    // Strings, numbers, etc. (terminal types) end here.
+    T;
+
+  /** Recursively makes all properties of T read-only. */
+  type Immutable<T> =
+    T extends Function ? T :
+    T extends Array<infer R> ? ImmutableArray<R> :
+    T extends Map<infer K, infer V> ? ImmutableMap<K, V> :
+    T extends Set<infer M> ? ImmutableSet<M> :
+    T extends object ? ImmutableObject<T> :
+    T
+
+  // Intermediate immutable types. Prefer e.g. Immutable<Set<T>> over direct use.
+  type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+  type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+  type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+  type ImmutableObject<T> = {
+    readonly [K in keyof T]: Immutable<T[K]>;
+  };
+
+  /**
+   * Exclude void from T
+   */
+  type NonVoid<T> = T extends void ? never : T;
+
+  /** Remove properties K from T. */
+  type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+  /** Obtain the type of the first parameter of a function. */
+  type FirstParamType<T extends (arg1: any, ...args: any[]) => any> =
+    T extends (arg1: infer P, ...args: any[]) => any ? P : never;
+
+  /**
+   * If `S` is a kebab-style string `S`, convert to camelCase.
+   */
+  type KebabToCamelCase<S> =
+    S extends `${infer T}-${infer U}` ?
+    `${T}${Capitalize<KebabToCamelCase<U>>}` :
+    S
+
+  /** Returns T with any kebab-style property names rewritten as camelCase. */
+  type CamelCasify<T> = {
+    [K in keyof T as KebabToCamelCase<K>]: T[K];
+  }
+}
+
+export default Util;