lighthouse 8.5.1 → 8.6.0-dev.20211013

package/shared/test/localization/locales-test.js

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright 2018 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.
+ */
+'use strict';
+
+const locales = require('../../localization/locales.js');
+const assert = require('assert').strict;
+
+/* eslint-env jest */
+
+describe('locales', () => {
+  it('has only canonical (or expected-deprecated) language tags', () => {
+    // Map of deprecated codes to their canonical version. Depending on the ICU
+    // version used to run Lighthouse/this test, these *may* come back as their
+    // substitute, not themselves.
+    const deprecatedCodes = {
+      in: 'id',
+      iw: 'he',
+      mo: 'ro',
+      tl: 'fil',
+    };
+
+    for (const locale of Object.keys(locales)) {
+      const canonicalLocale = Intl.getCanonicalLocales(locale)[0];
+      const substitute = deprecatedCodes[locale];
+      assert.ok(locale === canonicalLocale || substitute === canonicalLocale,
+        `locale code '${locale}' not canonical ('${canonicalLocale}' found instead)`);
+    }
+
+    // Deprecation subsitutes should be removed from the test if no longer used.
+    for (const locale of Object.keys(deprecatedCodes)) {
+      assert.ok(locales[locale], `${locale} substitute should be removed from test`);
+    }
+  });
+
+  it('has a base language prefix fallback for all supported languages', () => {
+    for (const locale of Object.keys(locales)) {
+      const basePrefix = locale.split('-')[0];
+      // The internet sez there is no canonical Chinese, so we exclude that one.
+      if (basePrefix !== 'zh') {
+        assert.ok(locales[basePrefix], `${locale} is missing a base fallback`);
+      }
+    }
+  });
+});

package/shared/test/localization/swap-locale-test.js

@@ -0,0 +1,140 @@
+/**
+ * @license Copyright 2019 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.
+ */
+'use strict';
+
+const swapLocale = require('../../localization/swap-locale.js');
+const {isNode12SmallIcu} = require('../../../lighthouse-core/test/test-utils.js');
+
+const lhr = require('../../../lighthouse-core/test/results/sample_v2.json');
+
+/* eslint-env jest */
+describe('swap-locale', () => {
+  // COMPAT: Node 12 only has 'en' by default. Skip these tests since they're all about swapping locales.
+  if (isNode12SmallIcu()) {
+    // Jest requires at least one test per suite.
+    it('throws if locale is not supported', () => {
+      // Even though 'pt' is requested, 'en' is all that's available.
+      expect(() => swapLocale(lhr, 'pt')).toThrow('Unsupported locale \'pt\'');
+    });
+
+    return;
+  }
+
+  it('does not mutate the original lhr', () => {
+    /** @type {LH.Result} */
+    const lhrClone = JSON.parse(JSON.stringify(lhr));
+
+    const lhrPt = swapLocale(lhr, 'pt').lhr;
+    expect(lhrPt).not.toStrictEqual(lhr);
+    expect(lhr).toStrictEqual(lhrClone);
+  });
+
+  it('can change golden LHR english strings into german', () => {
+    /** @type {LH.Result} */
+    const lhrEn = JSON.parse(JSON.stringify(lhr));
+    const lhrDe = swapLocale(lhrEn, 'de').lhr;
+
+    // Basic replacement
+    expect(lhrEn.audits.plugins.title).toEqual('Document avoids plugins');
+    expect(lhrDe.audits.plugins.title).toEqual('Dokument verwendet keine Plug-ins');
+
+    // With ICU string argument values
+    expect(lhrEn.audits['dom-size'].displayValue).toMatchInlineSnapshot(`"153 elements"`);
+    /* eslint-disable no-irregular-whitespace */
+    expect(lhrDe.audits['dom-size'].displayValue).toMatchInlineSnapshot(`"153 Elemente"`);
+
+    // Renderer formatted strings
+    expect(lhrEn.i18n.rendererFormattedStrings.labDataTitle).toEqual('Lab Data');
+    expect(lhrDe.i18n.rendererFormattedStrings.labDataTitle).toEqual('Labdaten');
+
+    // Formatted numbers in placeholders.
+    expect(lhrEn.audits['mainthread-work-breakdown'].displayValue).
+toMatchInlineSnapshot(`"2.2 s"`);
+    expect(lhrDe.audits['mainthread-work-breakdown'].displayValue).
+toMatchInlineSnapshot(`"2,2 s"`);
+    /* eslint-enable no-irregular-whitespace */
+  });
+
+  it('can roundtrip back to english correctly', () => {
+    /** @type {LH.Result} */
+    const lhrEn = JSON.parse(JSON.stringify(lhr));
+
+    // via Spanish
+    const lhrEnEsRT = swapLocale(swapLocale(lhrEn, 'es').lhr, 'en-US').lhr;
+    expect(lhrEnEsRT).toEqual(lhrEn);
+
+    // via Arabic
+    const lhrEnArRT = swapLocale(swapLocale(lhrEn, 'ar').lhr, 'en-US').lhr;
+    expect(lhrEnArRT).toEqual(lhrEn);
+  });
+
+  it('leaves alone messages where there is no translation available', () => {
+    const miniLHR = {
+      audits: {
+        redirects: {
+          id: 'redirects',
+          title: 'Avoid multiple page redirects',
+          doesntExist: 'A string that does not have localized versions',
+        },
+        fakeaudit: {
+          id: 'fakeaudit',
+          title: 'An audit without translations',
+        },
+      },
+      configSettings: {
+        locale: 'en-US',
+      },
+      i18n: {
+        icuMessagePaths: {
+          'lighthouse-core/audits/redirects.js | title': ['audits.redirects.title'],
+          // File that exists, but `doesntExist` message within it does not.
+          'lighthouse-core/audits/redirects.js | doesntExist': ['audits.redirects.doesntExist'],
+          // File and message which do not exist.
+          'lighthouse-core/audits/fakeaudit.js | title': ['audits.fakeaudit.title'],
+        },
+      },
+    };
+    const {missingIcuMessageIds} = swapLocale(miniLHR, 'es');
+
+    // Updated strings are not found, so these remain in the original language
+    expect(missingIcuMessageIds).toMatchInlineSnapshot(`
+Array [
+  "lighthouse-core/audits/redirects.js | doesntExist",
+  "lighthouse-core/audits/fakeaudit.js | title",
+]
+`);
+  });
+
+  it('does not change properties that are not strings', () => {
+    // Unlikely, but possible e.g. if an audit details changed shape over LH versions.
+    const miniLhr = {
+      audits: {
+        redirects: {
+          id: 'redirects',
+          title: 'Avoid multiple page redirects',
+        },
+      },
+      configSettings: {
+        locale: 'en-US',
+      },
+      i18n: {
+        icuMessagePaths: {
+          // Points to audit object, not string.
+          'lighthouse-core/audits/redirects.js | title': ['audits.redirects'],
+          // Path does not point to anything in LHR.
+          'lighthouse-core/audits/redirects.js | description': ['gatherers..X'],
+        },
+      },
+    };
+    const testLocale = 'ru';
+    const {lhr} = swapLocale(miniLhr, testLocale);
+
+    // LHR remains unchanged except for locale and injected `rendererFormattedStrings`.
+    miniLhr.configSettings.locale = testLocale;
+    miniLhr.i18n.rendererFormattedStrings = expect.any(Object);
+    expect(lhr).toEqual(miniLhr);
+  });
+});

package/shared/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "../../.tmp/tsbuildinfo/shared/",
+
+    // Limit defs to base JS.
+    "lib": ["es2020"],
+    // Only include `@types/node` from node_modules/.
+    "types": ["node"],
+    // "listFiles": true,
+  },
+  "references": [
+    {"path": "../types/lhr/"},
+  ],
+  "include": [
+    "**/*.js",
+    "types/**/*.d.ts",
+  ],
+  "exclude": [
+    "test/**/*.js",
+  ],
+}

package/shared/types/shared.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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 {IcuMessage as IcuMessage_} from '../../types/lhr/i18n';
+import LHResult from '../../types/lhr/lhr';
+import FlowResult_ from '../../types/lhr/flow';
+
+import {Locale as Locale_} from '../../types/lhr/settings';
+ 
+declare global {
+  // Expose global types in LH namespace.
+  module LH {
+    export import Result = LHResult;
+    export import FlowResult = FlowResult_;
+    export type IcuMessage = IcuMessage_;
+    export type IcuMessagePaths = LHResult.IcuMessagePaths;
+    export type Locale = Locale_;
+  }
+}
+
+export {};

package/third-party/chromium-synchronization/inspector-issueAdded-types-test.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const fetch = require('node-fetch');
-const {LH_ROOT} = require('../../../root.js');
+const {LH_ROOT} = require('../../root.js');
 
 const inspectorIssuesGathererPath = LH_ROOT +
   '/lighthouse-core/gather/gatherers/inspector-issues.js';
@@ -31,7 +31,8 @@ describe('issueAdded types', () => {
       .sort();
   });
 
-  it('should notify us if something changed', () => {
+  // TODO: https://github.com/GoogleChrome/lighthouse/issues/13147
+  it.skip('should notify us if something changed', () => {
     expect(inspectorIssueDetailsTypes).toMatchInlineSnapshot(`
       Array [
         "blockedByResponseIssueDetails",
@@ -44,7 +45,8 @@ describe('issueAdded types', () => {
     `);
   });
 
-  it('are each handled explicitly in the gatherer', () => {
+  // TODO: https://github.com/GoogleChrome/lighthouse/issues/13147
+  it.skip('are each handled explicitly in the gatherer', () => {
     // Regex relies on the typecasts
     const sourceTypeMatches = inspectorIssuesGathererSource.matchAll(
       /LH\.Crdp\.Audits\.(.*?Details)>/g

package/third-party/chromium-synchronization/installability-errors-test.js

@@ -74,7 +74,8 @@ Array [
 `);
   });
 
-  it('are each handled explicitly in the gatherer', () => {
+  // TODO: https://github.com/GoogleChrome/lighthouse/issues/13147
+  it.skip('are each handled explicitly in the gatherer', () => {
     const errorStrings = Object.keys(InstallableManifestAudit.UIStrings)
       .filter(key => chromiumErrorIds.includes(key))
       .sort();

package/tsconfig-all.json

@@ -9,6 +9,7 @@
     {"path": "./lighthouse-viewer/"},
     {"path": "./lighthouse-treemap/"},
     {"path": "./flow-report/"},
+    {"path": "./shared/"},
   ],
   "files": [],
   "include": [],

package/tsconfig-base.json

@@ -19,6 +19,6 @@
 
     // "listFiles": true,
     // "noErrorTruncation": true,
-    "extendedDiagnostics": true,
+    // "extendedDiagnostics": true,
   },
 }

package/tsconfig.json

@@ -10,6 +10,7 @@
     {"path": "./types/lhr/"},
     {"path": "./report/"},
     {"path": "./report/generator/"},
+    {"path": "./shared/"},
   ],
   "include": [
     "root.js",
@@ -22,13 +23,13 @@
 
     // TODO(esmodules): JSON files included via resolveJsonModule. Removable on the switch to ES Modules.
     "package.json",
-    "lighthouse-core/lib/i18n/locales/en-US.json",
     "lighthouse-core/test/results/sample_v2.json",
     "lighthouse-core/lib/sd-validation/assets/*.json",
     "lighthouse-core/test/fixtures/unresolved-perflog.json",
     "lighthouse-core/test/fixtures/traces/lcp-m78.devtools.log.json",
     "third-party/snyk/snapshot.json",
     "lighthouse-core/audits/byte-efficiency/polyfill-graph-data.json",
+    "shared/localization/locales/en-US.json",
   ],
   "exclude": [
     "lighthouse-core/test/audits/**/*.js",
@@ -79,8 +80,6 @@
     "lighthouse-core/test/lib/dependency-graph/simulator/simulator-test.js",
     "lighthouse-core/test/lib/emulation-test.js",
     "lighthouse-core/test/lib/i18n/i18n-test.js",
-    "lighthouse-core/test/lib/i18n/locales-test.js",
-    "lighthouse-core/test/lib/i18n/swap-locale-test.js",
     "lighthouse-core/test/lib/icons-test.js",
     "lighthouse-core/test/lib/lh-element-test.js",
     "lighthouse-core/test/lib/manifest-parser-test.js",

package/types/config.d.ts

@@ -134,6 +134,7 @@ declare module Config {
     auditRefs: AuditRefJson[];
     description?: string | IcuMessage;
     manualDescription?: string | IcuMessage;
+    supportedModes?:  Gatherer.GatherMode[];
   }
 
   interface GroupJson {

package/types/es-main.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 Types for the `es-main` npm module.
+ */
+
+/**
+ * Test if an ES module is run directly with Node.js.
+ * @param importMeta `import.meta` 
+ */
+declare function esMain(importMeta: ImportMeta): boolean;
+declare module 'es-main' {
+  export = esMain;
+}

package/types/externs.d.ts

@@ -155,6 +155,8 @@ export interface CliFlags extends Flags {
   enableErrorReporting?: boolean;
   /** Flag to print a list of all audits + categories. */
   listAllAudits: boolean;
+  /** Flag to print a list of all supported locales. */
+  listLocales: boolean;
   /** Flag to print a list of all required trace categories. */
   listTraceCategories: boolean;
   /** A preset audit of selected audit categories to run. */

package/types/lhr/flow.d.ts

@@ -11,6 +11,11 @@ declare module FlowResult {
     lhr: Result;
     name: string;
   }
+
+  interface LhrRef {
+    value: Result;
+    index: number;
+  }
 }
 
 /**
@@ -19,6 +24,8 @@ declare module FlowResult {
 interface FlowResult {
   /** Ordered list of flow steps, each corresponding to a navigation, timespan, or snapshot. */
   steps: FlowResult.Step[];
+  /** Name given to this user flow. */
+  name: string;
 }
 
 export default FlowResult;

package/types/lhr/i18n.d.ts

@@ -4,9 +4,6 @@
  * 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.
  */
 
-// TODO(bckenny): i18n types should not be necessary for the LHR, but too difficult
-// to unravel from audit-details right now.
-
 export type IcuMessage = {
   // NOTE: `i18nId` rather than just `id` to make tsc typing easier (vs type branding which won't survive JSON roundtrip).
   /** The id locating this message in the locale message json files. */