lighthouse 9.6.8 → 10.0.0-dev.20230210

package/core/audits/service-worker.js

@@ -0,0 +1,182 @@
+/**
+ * @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 {Audit} from './audit.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on a page's service worker. This descriptive title is shown to users when a service worker is registered and valid. */
+  title: 'Registers a service worker that controls page and `start_url`',
+  /** Title of a Lighthouse audit that provides detail on a page's service worker. This descriptive title is shown to users when a service worker is not present or invalid. */
+  failureTitle: 'Does not register a service worker that controls page and `start_url`',
+  /** Description of a Lighthouse audit that tells the user why they should use a service worker. This is displayed after a user expands the section to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
+  description: 'The service worker is the technology that enables your app to use many ' +
+    'Progressive Web App features, such as offline, add to homescreen, and push ' +
+    'notifications. [Learn more about Service Workers](https://developer.chrome.com/docs/lighthouse/pwa/service-worker/).',
+  /**
+   * @description Message explaining that the website may have service workers, but none are in scope to control the tested web page.
+   * @example {https://example.com/} pageUrl
+   * */
+  explanationOutOfScope: 'This origin has one or more service workers, however the page ' +
+    '({pageUrl}) is not in scope.',
+  /** Message explaining that the page has no manifest file so can't specify a starting url. */
+  explanationNoManifest: 'This page is controlled by a service worker, however ' +
+    'no `start_url` was found because no manifest was fetched.',
+  /** Message explaining that the page had an invalid manifest file so can't specify a starting url. */
+  explanationBadManifest: 'This page is controlled by a service worker, however ' +
+    'no `start_url` was found because manifest failed to parse as valid JSON',
+  /**
+   * @description Message explaining that the website has a service worker, but none are in scope to control the tested starting url.
+   * @example {https://example.com/} startUrl
+   * @example {https://othersite.com/} scopeUrl
+   * */
+  explanationBadStartUrl: 'This page is controlled by a service worker, however ' +
+    'the `start_url` ({startUrl}) is not in the service worker\'s scope ({scopeUrl})',
+};
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+class ServiceWorker extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'service-worker',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.failureTitle),
+      description: str_(UIStrings.description),
+      supportedModes: ['navigation'],
+      requiredArtifacts: ['URL', 'ServiceWorker', 'WebAppManifest'],
+    };
+  }
+
+  /**
+   * Find active service workers for this origin.
+   * @param {Array<LH.Crdp.ServiceWorker.ServiceWorkerVersion>} versions
+   * @param {URL} pageUrl
+   * @return {Array<LH.Crdp.ServiceWorker.ServiceWorkerVersion>}
+   */
+  static getVersionsForOrigin(versions, pageUrl) {
+    return versions
+      .filter(v => v.status === 'activated')
+      .filter(v => new URL(v.scriptURL).origin === pageUrl.origin);
+  }
+
+  /**
+   * From the set of active service workers for this origin, find the controlling SW (if any)
+   * and return its scope URL.
+   * @param {Array<LH.Crdp.ServiceWorker.ServiceWorkerVersion>} matchingSWVersions
+   * @param {Array<LH.Crdp.ServiceWorker.ServiceWorkerRegistration>} registrations
+   * @param {URL} pageUrl
+   * @return {{scopeUrl: string; scriptUrl: string} | undefined}
+   */
+  static getControllingServiceWorker(matchingSWVersions, registrations, pageUrl) {
+    // Find the normalized scope URLs of possibly-controlling SWs.
+    /** @type {Array<{scopeUrl: string; scriptUrl: string}>} */
+    const scriptByScopeUrlList = [];
+
+    // Populate serviceWorkerUrls map with the scriptURLs and scopeUrls of matchingSWVersions and registrations
+    for (const version of matchingSWVersions) {
+      const matchedRegistration = registrations
+        .find(r => r.registrationId === version.registrationId);
+
+      if (matchedRegistration) {
+        const scopeUrl = new URL(matchedRegistration.scopeURL).href;
+        const scriptUrl = new URL(version.scriptURL).href;
+        scriptByScopeUrlList.push({scopeUrl, scriptUrl});
+      }
+    }
+
+    // Find most-specific applicable scope, the one controlling the page.
+    // See https://w3c.github.io/ServiceWorker/v1/#scope-match-algorithm
+    const pageControllingUrls = scriptByScopeUrlList
+      .filter(ss => pageUrl.href.startsWith(ss.scopeUrl))
+      .sort((ssA, ssB) => ssA.scopeUrl.length - ssB.scopeUrl.length)
+      .pop();
+
+    return pageControllingUrls;
+  }
+
+  /**
+   * Returns a failure message if there is no start_url or if the start_url isn't
+   * contolled by the scopeUrl.
+   * @param {LH.Artifacts['WebAppManifest']} WebAppManifest
+   * @param {string} scopeUrl
+   * @return {LH.IcuMessage|undefined}
+   */
+  static checkStartUrl(WebAppManifest, scopeUrl) {
+    if (!WebAppManifest) {
+      return str_(UIStrings.explanationNoManifest);
+    }
+    if (!WebAppManifest.value) {
+      return str_(UIStrings.explanationBadManifest);
+    }
+
+    const startUrl = WebAppManifest.value.start_url.value;
+    if (!startUrl.startsWith(scopeUrl)) {
+      return str_(UIStrings.explanationBadStartUrl, {startUrl, scopeUrl});
+    }
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @return {LH.Audit.Product}
+   */
+  static audit(artifacts) {
+    // Match against `artifacts.URL.mainDocumentUrl` so audit accounts for any redirects.
+    // Service workers won't control network requests if the page uses `history.pushState` to "enter" the SW scope.
+    // For this reason it is better to evaluate the SW in relation to the main document url rather than the final frame url.
+    const {mainDocumentUrl} = artifacts.URL;
+    if (!mainDocumentUrl) throw new Error('mainDocumentUrl must exist in navigation mode');
+    const pageUrl = new URL(mainDocumentUrl);
+    const {versions, registrations} = artifacts.ServiceWorker;
+
+    const versionsForOrigin = ServiceWorker.getVersionsForOrigin(versions, pageUrl);
+    if (versionsForOrigin.length === 0) {
+      return {
+        score: 0,
+      };
+    }
+
+    const serviceWorkerUrls = ServiceWorker.getControllingServiceWorker(versionsForOrigin,
+        registrations, pageUrl);
+    if (!serviceWorkerUrls) {
+      return {
+        score: 0,
+        explanation: str_(UIStrings.explanationOutOfScope, {pageUrl: pageUrl.href}),
+      };
+    }
+
+    // Include the SW details as diagnostic data.
+    const {scriptUrl, scopeUrl} = serviceWorkerUrls;
+    /** @type {LH.Audit.Details.DebugData} */
+    const details = {
+      type: 'debugdata',
+      scriptUrl,
+      scopeUrl,
+    };
+
+    const startUrlFailure = ServiceWorker.checkStartUrl(artifacts.WebAppManifest,
+      serviceWorkerUrls.scopeUrl);
+    if (startUrlFailure) {
+      return {
+        score: 0,
+        details,
+        explanation: startUrlFailure,
+      };
+    }
+
+    // SW controls both finalDisplayedUrl and start_url.
+    return {
+      score: 1,
+      details,
+    };
+  }
+}
+
+export default ServiceWorker;
+export {UIStrings};

package/core/audits/splash-screen.d.ts

@@ -0,0 +1,37 @@
+export default SplashScreen;
+/**
+ * @fileoverview
+ * Audits if a page is configured for a custom splash screen when launched
+ * https://github.com/GoogleChrome/lighthouse/issues/24
+ *
+ * Requirements:
+ *   * manifest is not empty
+ *   * manifest has a valid name
+ *   * manifest has a valid background_color
+ *   * manifest has a valid theme_color
+ *   * manifest contains icon that's a png and size >= 512px
+ */
+declare class SplashScreen extends MultiCheckAudit {
+    /**
+     * @param {LH.Artifacts.ManifestValues} manifestValues
+     * @param {Array<string>} failures
+     */
+    static assessManifest(manifestValues: LH.Artifacts.ManifestValues, failures: Array<string>): void;
+    /**
+     * @param {LH.Artifacts} artifacts
+     * @param {LH.Audit.Context} context
+     * @return {Promise<{failures: Array<string>, manifestValues: LH.Artifacts.ManifestValues}>}
+     */
+    static audit_(artifacts: LH.Artifacts, context: LH.Audit.Context): Promise<{
+        failures: Array<string>;
+        manifestValues: LH.Artifacts.ManifestValues;
+    }>;
+}
+export namespace UIStrings {
+    const title: string;
+    const failureTitle: string;
+    const description: string;
+}
+import MultiCheckAudit from "./multi-check-audit.js";
+import { ManifestValues } from "../computed/manifest-values.js";
+//# sourceMappingURL=splash-screen.d.ts.map

package/core/audits/splash-screen.js

@@ -0,0 +1,98 @@
+/**
+ * @license Copyright 2017 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 MultiCheckAudit from './multi-check-audit.js';
+import {ManifestValues} from '../computed/manifest-values.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on splash screens. This descriptive title is shown to users when the site has a custom splash screen. */
+  title: 'Configured for a custom splash screen',
+  /** Title of a Lighthouse audit that provides detail on splash screens. This descriptive title is shown to users when the site does not have a custom splash screen. */
+  failureTitle: 'Is not configured for a custom splash screen',
+  /** Description of a Lighthouse audit that tells the user why they should configure a custom splash screen. This is displayed after a user expands the section to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
+  description: 'A themed splash screen ensures a high-quality experience when ' +
+    'users launch your app from their homescreens. ' +
+    '[Learn more about splash screens](https://developer.chrome.com/docs/lighthouse/pwa/splash-screen/).',
+};
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+/**
+ * @fileoverview
+ * Audits if a page is configured for a custom splash screen when launched
+ * https://github.com/GoogleChrome/lighthouse/issues/24
+ *
+ * Requirements:
+ *   * manifest is not empty
+ *   * manifest has a valid name
+ *   * manifest has a valid background_color
+ *   * manifest has a valid theme_color
+ *   * manifest contains icon that's a png and size >= 512px
+ */
+
+class SplashScreen extends MultiCheckAudit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'splash-screen',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.failureTitle),
+      description: str_(UIStrings.description),
+      supportedModes: ['navigation'],
+      requiredArtifacts: ['WebAppManifest', 'InstallabilityErrors'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts.ManifestValues} manifestValues
+   * @param {Array<string>} failures
+   */
+  static assessManifest(manifestValues, failures) {
+    if (manifestValues.isParseFailure && manifestValues.parseFailureReason) {
+      failures.push(manifestValues.parseFailureReason);
+      return;
+    }
+
+    const splashScreenCheckIds = [
+      'hasName',
+      'hasBackgroundColor',
+      'hasThemeColor',
+      'hasIconsAtLeast512px',
+    ];
+
+    manifestValues.allChecks
+      .filter(item => splashScreenCheckIds.includes(item.id))
+      .forEach(item => {
+        if (!item.passing) {
+          failures.push(item.failureText);
+        }
+      });
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<{failures: Array<string>, manifestValues: LH.Artifacts.ManifestValues}>}
+   */
+  static async audit_(artifacts, context) {
+    /** @type {Array<string>} */
+    const failures = [];
+
+    const manifestValues = await ManifestValues.request(artifacts, context);
+    SplashScreen.assessManifest(manifestValues, failures);
+
+    return {
+      failures,
+      manifestValues,
+    };
+  }
+}
+
+export default SplashScreen;
+export {UIStrings};

package/core/audits/themed-omnibox.d.ts

@@ -0,0 +1,42 @@
+export default ThemedOmnibox;
+/**
+ * @fileoverview
+ * Audits if a page is configured for a themed address bar
+ *
+ * Requirements:
+ *   * manifest is not empty
+ *   * manifest has a theme_color
+ *   * HTML has a theme-color meta
+ *
+ * Color validity is explicitly not checked.
+ */
+declare class ThemedOmnibox extends MultiCheckAudit {
+    /**
+     * @param {LH.Artifacts.MetaElement|undefined} themeColorMeta
+     * @param {Array<string>} failures
+     */
+    static assessMetaThemecolor(themeColorMeta: LH.Artifacts.MetaElement | undefined, failures: Array<string>): void;
+    /**
+     * @param {LH.Artifacts.ManifestValues} manifestValues
+     * @param {Array<string>} failures
+     */
+    static assessManifest(manifestValues: LH.Artifacts.ManifestValues, failures: Array<string>): void;
+    /**
+     * @param {LH.Artifacts} artifacts
+     * @param {LH.Audit.Context} context
+     * @return {Promise<{failures: Array<string>, manifestValues: LH.Artifacts.ManifestValues, themeColor: ?string}>}
+     */
+    static audit_(artifacts: LH.Artifacts, context: LH.Audit.Context): Promise<{
+        failures: Array<string>;
+        manifestValues: LH.Artifacts.ManifestValues;
+        themeColor: string | null;
+    }>;
+}
+export namespace UIStrings {
+    const title: string;
+    const failureTitle: string;
+    const description: string;
+}
+import MultiCheckAudit from "./multi-check-audit.js";
+import { ManifestValues } from "../computed/manifest-values.js";
+//# sourceMappingURL=themed-omnibox.d.ts.map

package/core/audits/themed-omnibox.js

@@ -0,0 +1,102 @@
+/**
+ * @license Copyright 2017 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 MultiCheckAudit from './multi-check-audit.js';
+import {ManifestValues} from '../computed/manifest-values.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the theme color the web page has set for the browser's address bar. This descriptive title is shown to users when an address-bar theme color has been set. */
+  title: 'Sets a theme color for the address bar.',
+  /** Title of a Lighthouse audit that provides detail on the theme color the web page has set for the browser's address bar. This descriptive title is shown to users when an address-bar theme color has not been set. */
+  failureTitle: 'Does not set a theme color for the address bar.',
+  /** Description of a Lighthouse audit that tells the user why they should set a theme color for the browser's address bar. This is displayed after a user expands the section to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
+  description: 'The browser address bar can be themed to match your site. ' +
+    '[Learn more about theming the address bar](https://developer.chrome.com/docs/lighthouse/pwa/themed-omnibox/).',
+};
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+/**
+ * @fileoverview
+ * Audits if a page is configured for a themed address bar
+ *
+ * Requirements:
+ *   * manifest is not empty
+ *   * manifest has a theme_color
+ *   * HTML has a theme-color meta
+ *
+ * Color validity is explicitly not checked.
+ */
+
+class ThemedOmnibox extends MultiCheckAudit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'themed-omnibox',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.failureTitle),
+      description: str_(UIStrings.description),
+      supportedModes: ['navigation'],
+      requiredArtifacts: ['WebAppManifest', 'InstallabilityErrors', 'MetaElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts.MetaElement|undefined} themeColorMeta
+   * @param {Array<string>} failures
+   */
+  static assessMetaThemecolor(themeColorMeta, failures) {
+    if (!themeColorMeta) {
+      // TODO(#7238): i18n
+      failures.push('No `<meta name="theme-color">` tag found');
+    } else if (!themeColorMeta.content) {
+      failures.push('The theme-color meta tag did not contain a content value');
+    }
+  }
+
+  /**
+   * @param {LH.Artifacts.ManifestValues} manifestValues
+   * @param {Array<string>} failures
+   */
+  static assessManifest(manifestValues, failures) {
+    if (manifestValues.isParseFailure && manifestValues.parseFailureReason) {
+      failures.push(manifestValues.parseFailureReason);
+      return;
+    }
+
+    const themeColorCheck = manifestValues.allChecks.find(i => i.id === 'hasThemeColor');
+    if (themeColorCheck && !themeColorCheck.passing) {
+      failures.push(themeColorCheck.failureText);
+    }
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<{failures: Array<string>, manifestValues: LH.Artifacts.ManifestValues, themeColor: ?string}>}
+   */
+  static async audit_(artifacts, context) {
+    /** @type {Array<string>} */
+    const failures = [];
+
+    const themeColorMeta = artifacts.MetaElements.find(meta => meta.name === 'theme-color');
+    const manifestValues = await ManifestValues.request(artifacts, context);
+    ThemedOmnibox.assessManifest(manifestValues, failures);
+    ThemedOmnibox.assessMetaThemecolor(themeColorMeta, failures);
+
+    return {
+      failures,
+      manifestValues,
+      themeColor: themeColorMeta?.content || null,
+    };
+  }
+}
+
+export default ThemedOmnibox;
+export {UIStrings};

package/core/audits/third-party-facades.d.ts

@@ -0,0 +1,42 @@
+export default ThirdPartyFacades;
+export type ThirdPartyEntity = import("third-party-web").IEntity;
+export type ThirdPartyProduct = import("third-party-web").IProduct;
+export type ThirdPartyFacade = import("third-party-web").IFacade;
+export type FacadableProduct = {
+    product: ThirdPartyProduct;
+    entity: ThirdPartyEntity;
+};
+declare class ThirdPartyFacades extends Audit {
+    /**
+     * Sort items by transfer size and combine small items into a single row.
+     * Items will be mutated in place to a maximum of 6 rows.
+     * @param {import('./third-party-summary.js').URLSummary[]} items
+     */
+    static condenseItems(items: import('./third-party-summary.js').URLSummary[]): void;
+    /**
+     * @param {Map<string, import('./third-party-summary.js').Summary>} byURL
+     * @param {LH.Artifacts.EntityClassification} classifiedEntities
+     * @return {FacadableProduct[]}
+     */
+    static getProductsWithFacade(byURL: Map<string, import('./third-party-summary.js').Summary>, classifiedEntities: LH.Artifacts.EntityClassification): FacadableProduct[];
+    /**
+     * @param {LH.Artifacts} artifacts
+     * @param {LH.Audit.Context} context
+     * @return {Promise<LH.Audit.Product>}
+     */
+    static audit(artifacts: LH.Artifacts, context: LH.Audit.Context): Promise<LH.Audit.Product>;
+}
+export namespace UIStrings {
+    const title: string;
+    const failureTitle: string;
+    const description: string;
+    const displayValue: string;
+    const columnProduct: string;
+    const categoryVideo: string;
+    const categoryCustomerSuccess: string;
+    const categoryMarketing: string;
+    const categorySocial: string;
+}
+import { Audit } from "./audit.js";
+import { EntityClassification } from "../computed/entity-classification.js";
+//# sourceMappingURL=third-party-facades.d.ts.map