lighthouse 13.5.0 → 13.6.0-dev.20261027

package/.agents/skills/update-ard-port/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: update-ard-port
+description: Sync Lighthouse's Agentic Resource Discovery (ARD) port with upstream ards-project/ard-spec. Invoke when `node core/scripts/update-ard-spec.js --check` reports the ARD spec is out of sync, when the weekly cron CI job fails on it, or when asked to update the ARD conformance script, schema, or discovery rules.
+---
+
+# Update the ARD port
+
+Lighthouse vendors a JavaScript port of the upstream ARD conformance tester. When
+upstream changes, the port must be brought back to **1:1 parity** while preserving the
+Lighthouse-specific adaptations listed in `third-party/ard/README.md`.
+
+## What lives where
+
+| Upstream (ards-project/ard-spec) | Lighthouse | Notes |
+|---|---|---|
+| `conformance/bin/conformance-test` → `validate_manifest` and helpers | `third-party/ard/ard.js` | `ConformanceTester` (`validate_manifest`, `run_json_schema_validation`, `add_error/warning/info`), `parse_media_type`, `classify_media_type`, `format_schema_error`. Keep upstream `snake_case` names and **word-for-word message text**. |
+| `spec/schemas/ard-entry.schema.json` | `third-party/ard/spec/schemas/ard-entry.schema.json` | Must stay byte-identical to upstream. |
+| (generated) | `third-party/ard/schema-validator.js` | Precompiled Ajv standalone validator, built by `build/build-ard-schema.js` (`yarn build-ard-schema`). Never hand-edit. |
+| `spec/ard.md` §5.1 Discovery Mechanisms (+ `resolve_publisher` in the script) | `core/gather/gatherers/agentic/ard.js` | Candidate order: robots.txt `agentmap` → `<link rel="ard">` → `Link` header → `/.well-known/ard.json` → legacy `ai-catalog` equivalents. Source names in `Artifacts.ArdDiscoverySource` (`types/artifacts.d.ts`). |
+| severity / scoring (Lighthouse-only) | `core/audits/agentic/ard-schema.js` | errors → score 0; warnings/legacy/broken-link → 0.9; clean → 1. `infos` are not surfaced. |
+| pinned SHA + reviewed hashes + deviation list | `third-party/ard/README.md` | `**Pinned Commit SHA**` and the `**Reviewed Upstream Files**` SHA-256 lines are parsed/written by the update script. Never edit the hashes by hand — they are the proof that the port was reviewed against that exact upstream content. |
+
+Tests:
+- `third-party/ard/ard-test.js` — port unit tests
+- `core/test/gather/gatherers/agentic/ard-test.js` — gatherer
+- `core/test/audits/agentic/ard-schema-test.js` — audit
+- `cli/test/smokehouse/test-definitions/ard.js`, `ard-invalid.js` + fixtures in `cli/test/fixtures/agentic/`
+- `core/test/results/artifacts/artifacts.json` — sample `AgentResourceDiscovery` artifact
+
+## Procedure
+
+### 1. See what changed
+
+```
+node core/scripts/update-ard-spec.js --check
+```
+
+"In sync" means upstream HEAD matches the vendored schema byte-for-byte **and** the
+SHA-256 of `conformance/bin/conformance-test` and `spec/ard.md` match the hashes recorded
+in the README. The output lists which of the three differ, plus old/new SHA and a compare
+link. Pull the upstream files at **both** SHAs for side-by-side review (the compare API
+patch is often truncated):
+
+```
+https://raw.githubusercontent.com/ards-project/ard-spec/<sha>/conformance/bin/conformance-test
+https://raw.githubusercontent.com/ards-project/ard-spec/<sha>/spec/schemas/ard-entry.schema.json
+https://raw.githubusercontent.com/ards-project/ard-spec/<sha>/spec/ard.md
+```
+
+Save them in the conversation scratch dir and diff old vs new. Also check
+`conformance/` for new test fixtures/expected outputs and `docs/adr/` for ADRs explaining
+renamed or removed fields (e.g. `collections`, media type renames).
+
+### 2. Sync the schema
+
+```
+yarn update:ard-spec
+```
+
+This writes `third-party/ard/spec/schemas/ard-entry.schema.json` verbatim from upstream
+and prints the `conformance-test` diff. If a hand-ported file changed it **exits 1 and
+does not bump the pinned SHA** — that is expected; the SHA is bumped in step 8 after
+porting. Do not pass `--ack-port` yet.
+
+### 3. Port conformance-test changes into `third-party/ard/ard.js`
+
+For every hunk in the upstream `conformance-test` diff decide whether it touches:
+- **Validation rules** (new/removed checks, changed thresholds such as the
+  `representativeQueries` 2–5 range, new deprecated media types, URN regex) → port 1:1.
+- **Severity** (error ↔ warning ↔ info) → mirror it; this changes audit scoring.
+- **Message text** → copy exactly; the audit shows these strings to users and tests
+  assert on them.
+- **CLI/ANSI output, argparse, `main()`, `resolve_publisher`** → not ported (see README
+  deviations); skip unless the discovery logic itself changed (then see step 4).
+- **`format_schema_error`** → only adapt if upstream changes how schema errors are
+  phrased. Ajv's messages differ from Python `jsonschema`; keep the
+  `'x' is a required property` mapping.
+
+Rules to preserve:
+- Treat non-object roots/entries as empty instead of throwing.
+- Push `{element, message}` objects; never return formatted strings.
+- Log through `lighthouse-logger`, not `console`.
+- Only `ARD_VERSION`, `ConformanceTester` and `classify_media_type` are exported; add exports only if
+  tests need them.
+
+If `classify_media_type` / `parse_media_type` changed, run a parity check against the
+real Python script on a list of tricky inputs (params, quoted strings, casing,
+deprecated/unknown `application/*` types) and fix any mismatch.
+
+### 4. If `spec/ard.md` changed
+
+Read §5.1 (and any section the script's `resolve_publisher` references). If the
+mechanisms, well-known path, `rel` names, header names, or precedence changed:
+- Update the candidate list/order in `core/gather/gatherers/agentic/ard.js`
+  (`resolveManifest`) and the `getArdLinksInDOM` rel names.
+- Update `Artifacts.ArdDiscoverySource` and `discoverySignals` in `types/artifacts.d.ts`.
+- Update `LEGACY_SOURCES` / UIStrings in `core/audits/agentic/ard-schema.js` if what counts
+  as legacy changed.
+
+### 5. Rebuild the validator (only if the schema changed)
+
+```
+yarn build-ard-schema
+```
+
+Review the `schema-validator.js` diff: it should only reflect schema changes. The build
+throws if any `require(` survives or a `$id` is missing — fix `build/build-ard-schema.js`
+rather than the output.
+
+### 6. Update tests and fixtures
+
+- `third-party/ard/ard-test.js`: add a case for every new/changed rule and message.
+- Gatherer/audit tests if discovery or scoring changed.
+- Smoke: `cli/test/fixtures/agentic/ard.json` / `ai-catalog-invalid.json` and the
+  expectations in `cli/test/smokehouse/test-definitions/ard-invalid.js`. Smokehouse
+  asserts the **exact count and order** of `details.items`.
+- `core/test/results/artifacts/artifacts.json` if the artifact shape changed.
+
+### 7. Update docs
+
+- README "Modifications for Lighthouse" if a new deviation was introduced, and the
+  "Updating Conformance Script" steps if the process changed.
+- `ARD_VERSION` in `ard.js` is updated automatically by `yarn update:ard-spec --ack-port`;
+  update `@fileoverview` comments in `ard.js`, the gatherer and the audit if the major/minor
+  spec version changed.
+- Audit `UIStrings` if user-facing wording or the spec link changed.
+
+### 8. Verify, then acknowledge
+
+```
+yarn mocha third-party/ard/ard-test.js core/test/gather/gatherers/agentic/ard-test.js core/test/audits/agentic/ard-schema-test.js
+yarn smoke ard ardInvalid
+yarn type-check
+yarn lint --fix
+yarn update:sample-json
+```
+
+`yarn update:sample-json` also runs `i18n:collect-strings`; audit tests resolve
+UIStrings through `shared/localization/locales/en-US.json`, so new strings fail tests
+until this runs. Do not run `yarn unit`.
+
+Only once everything above is green:
+
+```
+yarn update:ard-spec --ack-port                 # records reviewed hashes + bumps pinned SHA
+node core/scripts/update-ard-spec.js --check   # must now report in sync
+```
+
+`--ack-port` is the single statement that "the port matches this upstream content". Never
+run it to silence the check without having ported the diff.
+
+### 9. Report
+
+Summarize for the user: upstream SHA range, each rule/message/severity change and its
+effect on audit scoring, any discovery changes, and any deviation added to the README.
+Do not commit or open a PR unless asked.
+
+## Gotchas
+
+- The check compares *content*, not commit IDs. A green check after a deps upgrade means
+  nothing changed upstream, not that someone looked. `upgrade-deps.sh` only runs
+  `--check`; it cannot acknowledge changes.
+- `run_command` rejects `grep`; use `grep_search`, `awk`, or `sed`.
+- Upstream v0.91 has no `specVersion` check, logs unknown root members only, warns on
+  `collections` (removed by ADR-0003), does not check HTTPS, and does not validate
+  `capabilities`. Do not add Lighthouse-only checks to the port — put them in the audit
+  if ever wanted.
+- The `[label]` prefix upstream prepends to entry messages is carried in `element`, not
+  in `message`.
+- The gatherer, not the port, decides which manifest URL is validated; the port only
+  receives `raw_content` and `source_label`.

package/.agents/skills/update-trace-engine/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: update-trace-engine
+description: Build, validate, publish, and roll @paulirish/trace_engine from devtools-frontend into Lighthouse. Invoke when asked to update or roll the trace_engine package.
+---
+
+# Update `@paulirish/trace_engine`
+
+Lighthouse consumes Chrome DevTools' trace processor (`front_end/models/trace`) via the standalone `@paulirish/trace_engine` npm package, built from the `trace-engine-lib` branch of `paulirish/devtools-frontend`.
+
+## What lives where
+
+| Location | Purpose | Notes |
+|---|---|---|
+| `devtools-frontend` checkout (branch `trace-engine-lib`) | Source & packaging scripts | Tracks `origin/main` (`https://chromium.googlesource.com/devtools/devtools-frontend`) + packaging scripts in `scripts/trace/`. Common local path: `~/devtools/devtools-frontend` (ask user if not found). |
+| `scripts/trace/prep-trace-engine-package.sh` (in `devtools-frontend`) | Builds `out/TraceEngine` and prepares standalone package | Converts `export const enum` → `export enum` in `front_end/models/trace/**/*.ts`, builds with `gn` + `autoninja`, applies shims from `scripts/trace/replacements/`, extracts insight locale strings, and invokes `copy-build-trace-engine-for-publish.sh`. |
+| `scripts/trace/copy-build-trace-engine-for-publish.sh` (in `devtools-frontend`) | Copies dist to `$HOME/code/trace_engine` and tests | Copies `out/TraceEngine/dist` to `$HOME/code/trace_engine`, runs `npm install` and `npm test` (Mocha tests in `test/test-trace-engine.mjs` + `tsc --build ./tsconfig.json`). |
+| `$HOME/code/trace_engine` | Standalone npm package staging directory | Where `npm version` and `npm publish` are run. |
+| `core/lib/trace-engine.js` (in Lighthouse) | Lighthouse entry point for `@paulirish/trace_engine` | Re-exports `TraceProcessor`, `TraceHandlers`, `Insights`, `Helpers`, and `Types`. |
+
+## Procedure
+
+### 1. Merge `origin/main` into `trace-engine-lib` in `devtools-frontend`
+
+1. Find the previous `devtools-frontend` `main` commit SHA from the most recent `deps: upgrade trace_engine` commit or PR in Lighthouse (or via `git log -n 1 --merges --pretty=format:"%P"` on `trace-engine-lib`).
+2. In the `devtools-frontend` checkout:
+   ```sh
+   git checkout trace-engine-lib
+   git fetch origin main
+   git merge origin/main --no-edit
+   ```
+3. Record the commit range `<old_sha>...<new_sha>` and inspect upstream changes:
+   ```sh
+   git log --oneline <old_sha>..<new_sha> -- front_end/models/trace front_end/models/cpu_profile
+   ```
+4. If there are merge conflicts in `front_end/models/trace/**/*.ts` due to `export const enum` vs `export enum`, resolve in favor of `origin/main` — `prep-trace-engine-package.sh` automatically converts `export const enum` to `export enum`.
+
+### 2. Build and test the standalone package
+
+Ensure `depot_tools` (`gn`, `autoninja`) and Node/npm are on `PATH`, then run:
+
+```sh
+scripts/trace/prep-trace-engine-package.sh
+```
+
+This builds `out/TraceEngine`, populates `$HOME/code/trace_engine`, and runs `npm test` (`mocha` + `tsc --build ./tsconfig.json`).
+
+#### Fixing build or test failures in `trace-engine-lib`
+
+- **TypeScript (`tsc --build ./tsconfig.json`) errors in `$HOME/code/trace_engine`**:
+  - `prep-trace-engine-package.sh` replaces several DevTools modules using `scripts/trace/replacements/` so Lighthouse can bundle `trace_engine` into an IIFE (`esbuild`) and defer localization (`LH.IcuMessage`):
+    - `HostRuntime.js`: synchronous stub replacing top-level `await` in `core/platform/HostRuntime.js`.
+    - `UIString.d.ts` & `i18n.{js,d.ts}`: types `LocalizedString` as a deferred `{i18nId, values}` object instead of a branded `string`. If a file in `core/platform/` (such as `UserVisibleError.d.ts`) fails type-checking because it expects `LocalizedString` to be assignable to `string` and isn't needed by `models/trace`, stub its `.d.ts` in `prep-trace-engine-package.sh` (`echo 'export {};' > "$dist/core/platform/<File>.d.ts"`).
+    - `common.{js,d.ts}`, `sdk.d.ts`, `crux-manager.d.ts`: minimal stubs for `core/common`, `core/sdk`, and `models/crux-manager`. Update these if `models/trace` references new symbols from those modules.
+- **Mocha (`test/test-trace-engine.mjs`) failures**:
+  - If an assertion in `scripts/trace/test/test-trace-engine.mjs` fails due to an intentional upstream calculation change in `front_end/models/trace`, update `scripts/trace/test/test-trace-engine.mjs` and re-run `scripts/trace/copy-build-trace-engine-for-publish.sh`.
+- Commit any updated files on `trace-engine-lib` and push to Paul's fork (`git push paulirish trace-engine-lib`) when requested.
+
+### 3. Bump the package version
+
+Determine the next patch version (`0.0.X` → `0.0.(X+1)`) from `package.json` in Lighthouse or `npm view @paulirish/trace_engine version --registry https://registry.npmjs.org/`:
+
+```sh
+cd $HOME/code/trace_engine
+npm version v0.0.XXX --no-git-tag-version
+```
+
+### 4. Validate locally in Lighthouse before publishing
+
+Copy the built package into Lighthouse's `node_modules/@paulirish/trace_engine` to validate before publishing to npm:
+
+```sh
+rm -rf node_modules/@paulirish/trace_engine/{models,core,generated,third_party,locales,test}
+cp -rp $HOME/code/trace_engine/{models,core,generated,third_party,locales,package.json,tsconfig.json} node_modules/@paulirish/trace_engine/
+```
+
+Run the Lighthouse validation checks:
+
+1. **Type-checking**:
+   ```sh
+   yarn type-check
+   ```
+   Fix any Lighthouse code or JSDoc types broken by upstream `TraceEngine` API/type changes (commonly in `core/audits/insights/`, `core/computed/`, `core/gather/gatherers/trace-elements.js`, or `core/lib/trace-engine.js`).
+
+2. **Bundles**:
+   ```sh
+   yarn build-devtools && yarn build-lr && yarn build-devtools-mcp
+   ```
+   Confirms `esbuild` can bundle `trace_engine` into IIFE (`dt-bundle.js`, Lightrider) and ESM without top-level `await` or missing module errors.
+
+3. **Unit tests**:
+   ```sh
+   yarn mocha core/test/audits/insights/*-test.js core/test/audits/metrics-test.js core/test/audits/predictive-perf-test.js core/test/audits/byte-efficiency/byte-efficiency-audit-test.js core/test/computed/metrics/*-test.js core/test/computed/trace-engine-result-test.js core/test/computed/navigation-insights-test.js core/test/computed/entity-classification-test.js core/test/computed/tbt-impact-tasks-test.js
+   INTERNAL_LANTERN_USE_TRACE=1 yarn mocha core/test/computed/metrics/*-test.js core/test/audits/metrics-test.js core/test/audits/predictive-perf-test.js
+   ```
+   Update test expectations and snapshots (`yarn mocha --update <test-file>`) where upstream changes intentionally affect metrics, insights, or Lantern trace simulations.
+
+4. **Sample JSON, locale strings, flow fixtures, and Lantern baselines**:
+   ```sh
+   yarn update:sample-json
+   bash core/scripts/assert-baseline-flow-result-unchanged.sh
+   yarn test-lantern
+   ```
+   - If `assert-baseline-flow-result-unchanged.sh` fails due to expected changes, update flow fixtures with `yarn update:flow-fixtures`.
+   - If `yarn test-lantern` reports expected metric changes on the Lantern dataset (or if `models/trace/lantern` changed upstream), update the Lantern baseline files (`core/test/fixtures/lantern-baseline-computed-values.json` and `core/test/fixtures/lantern-baseline-accuracy.json`):
+     ```sh
+     FORCE=1 ./core/scripts/lantern/update-baseline-lantern-values.js
+     ./core/scripts/lantern/assert-baseline-lantern-values-unchanged.js
+     ```
+   - Review `git diff core/test/results/sample_v2.json` and `git diff shared/localization/locales/en-US.json` to make sure every change is accounted for by an upstream commit.
+
+5. **Linter**:
+   ```sh
+   yarn lint --fix
+   ```
+
+### 5. Pause for npm publish
+
+Once local validation passes, pause and ask the user to publish `$HOME/code/trace_engine` to npm (requires interactive npm authentication):
+
+```sh
+cd $HOME/code/trace_engine
+npm publish --access public --registry https://registry.npmjs.org/
+```
+
+### 6. Roll `package.json`, `yarn.lock`, and open the PR
+
+After the user confirms `@paulirish/trace_engine@0.0.XXX` is published on npm:
+
+1. Update `"@paulirish/trace_engine": "0.0.XXX"` in `package.json` and run `yarn` to update `yarn.lock`.
+2. Commit all changes (`deps: upgrade trace_engine to 0.0.XXX`).
+3. Run `yarn diff:sample-json` after committing (note: `assert-strings-collected.sh` runs `git diff --exit-code shared/localization/locales/`, so uncommitted locale changes will cause it to fail).
+4. Push the branch and open a PR against `GoogleChrome/lighthouse` with title `deps: upgrade trace_engine to 0.0.XXX` and description formatted like [PR #17307](https://github.com/GoogleChrome/lighthouse/pull/17307) (including the collapsible `<details><summary>` block with the full `git log <old_sha>...<new_sha> -- front_end/models/trace` output):
+
+````markdown
+Roll `@paulirish/trace_engine` from `0.0.OLD` to `0.0.NEW` (`<old_sha>...<new_sha>`).
+
+https://chromium.googlesource.com/devtools/devtools-frontend.git/+log/<old_sha>..<new_sha>
+
+### Highlights for Lighthouse
+
+- **<Category>**:
+  - **<Highlight>** ([CL <cl_number>](https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/<cl_number>)): <summary of upstream change and impact on Lighthouse>
+
+`git log <old_sha>...<new_sha> -- front_end/models/trace`:
+
+<details>
+  <summary>Changelog (just front_end/models/trace, mostly relevant to our usage in LH)</summary>
+
+```
+<full output of: git log <old_sha>...<new_sha> -- front_end/models/trace>
+```
+
+</details>
+````

package/cli/bin.d.ts

@@ -1,5 +1,5 @@
 /**
- * @return {Promise<LH.RunnerResult|void>}
+ * @return {Promise<LH.RunnerResult|LH.RunnerResult[]|void>}
  */
-export function begin(): Promise<LH.RunnerResult | void>;
+export function begin(): Promise<LH.RunnerResult | LH.RunnerResult[] | void>;
 //# sourceMappingURL=bin.d.ts.map

package/cli/bin.js

@@ -41,7 +41,7 @@ function isDev() {
 }
 
 /**
- * @return {Promise<LH.RunnerResult|void>}
+ * @return {Promise<LH.RunnerResult|LH.RunnerResult[]|void>}
  */
 async function begin() {
   const cliFlags = getFlags();
@@ -61,7 +61,7 @@ async function begin() {
     commands.listTraceCategories();
   }
 
-  const urlUnderTest = cliFlags._[0];
+  const urlsUnderTest = cliFlags._.length > 1 ? cliFlags._ : cliFlags._[0];
 
   /** @type {LH.Config|undefined} */
   let config;
@@ -89,6 +89,7 @@ async function begin() {
   log.setLevel(cliFlags.logLevel);
 
   if (
+    cliFlags._.length <= 1 &&
     cliFlags.output.length === 1 &&
     cliFlags.output[0] === Printer.OutputMode.json &&
     !cliFlags.outputPath
@@ -120,7 +121,7 @@ async function begin() {
   }
   if (cliFlags.enableErrorReporting) {
     await Sentry.init({
-      url: urlUnderTest,
+      url: cliFlags._.join(', '),
       flags: cliFlags,
       config,
       environmentData: {
@@ -131,7 +132,7 @@ async function begin() {
     });
   }
 
-  return runLighthouse(urlUnderTest, cliFlags, config);
+  return runLighthouse(urlsUnderTest, cliFlags, config);
 }
 
 export {

package/cli/cli-flags.d.ts

@@ -24,7 +24,7 @@ export function getYargsParser(manualArgv?: string | undefined): import("yargs")
         default: boolean;
         describe: string;
     };
-}>, "port" | "screenEmulation" | "emulatedUserAgent" | "hostname" | "preset" | "save-assets" | "list-all-audits" | "list-locales" | "list-trace-categories" | "debug-navigation" | "additional-trace-categories" | "config-path" | "chrome-flags" | "form-factor" | "max-wait-for-load" | "enable-error-reporting" | "gather-mode" | "audit-mode" | "only-audits" | "only-categories" | "skip-audits" | "disable-full-page-screenshot" | "ignore-status-code"> & import("yargs").InferredOptionTypes<{
+}>, "port" | "screenEmulation" | "emulatedUserAgent" | "hostname" | "preset" | "save-assets" | "list-all-audits" | "list-locales" | "list-trace-categories" | "debug-navigation" | "additional-trace-categories" | "config-path" | "chrome-flags" | "form-factor" | "max-wait-for-load" | "enable-error-reporting" | "gather-mode" | "audit-mode" | "only-audits" | "only-categories" | "skip-audits" | "disable-full-page-screenshot" | "ignore-status-code" | "url-file" | "fail-fast"> & import("yargs").InferredOptionTypes<{
     'save-assets': {
         type: "boolean";
         default: boolean;
@@ -133,6 +133,15 @@ export function getYargsParser(manualArgv?: string | undefined): import("yargs")
         type: "boolean";
         describe: string;
     };
+    'url-file': {
+        type: "string";
+        coerce: typeof coerceUrlFile;
+        describe: string;
+    };
+    'fail-fast': {
+        type: "boolean";
+        describe: string;
+    };
 }>, "output" | "view" | "output-path"> & import("yargs").InferredOptionTypes<{
     output: {
         type: "array";
@@ -221,6 +230,12 @@ declare function coerceOptionalStringBoolean(value: unknown): boolean | string |
  * @return {Array<string>=}
  */
 declare function splitCommaSeparatedValues(strings?: Array<string> | undefined): Array<string> | undefined;
+/**
+ * Reads newline-delimited URLs from a file, ignoring empty lines and `#` comments.
+ * @param {unknown=} value
+ * @return {Array<string>=}
+ */
+declare function coerceUrlFile(value?: unknown | undefined): Array<string> | undefined;
 /**
  * Coerce output CLI input to `LH.SharedFlagsSettings['output']` or throw if not possible.
  * @param {Array<unknown>} values

package/cli/cli-flags.js

@@ -20,7 +20,6 @@ import {isObjectOfUnknownValues} from '../shared/type-verifiers.js';
  */
 function getYargsParser(manualArgv) {
   const y = manualArgv ?
-    // @ts-expect-error - undocumented, but yargs() supports parsing a single `string`.
     yargs(manualArgv) :
     yargs(yargsHelpers.hideBin(process.argv));
 
@@ -204,12 +203,22 @@ function getYargsParser(manualArgv) {
         type: 'boolean',
         describe: 'Disables failing on all error status codes, and instead issues a warning.',
       },
+      'url-file': {
+        type: 'string',
+        coerce: coerceUrlFile,
+        describe: 'The path to a file containing newline-delimited URLs to audit.',
+      },
+      'fail-fast': {
+        type: 'boolean',
+        describe: 'Stop auditing remaining URLs immediately if a run fails.',
+      },
     })
     .group([
       'save-assets', 'list-all-audits', 'list-locales', 'list-trace-categories', 'additional-trace-categories',
       'config-path', 'preset', 'chrome-flags', 'port', 'hostname', 'form-factor', 'screenEmulation', 'emulatedUserAgent',
       'max-wait-for-load', 'enable-error-reporting', 'gather-mode', 'audit-mode',
       'only-audits', 'only-categories', 'skip-audits', 'disable-full-page-screenshot', 'ignore-status-code',
+      'url-file', 'fail-fast',
     ], 'Configuration:')
 
     // Output
@@ -223,7 +232,8 @@ function getYargsParser(manualArgv) {
       'output-path': {
         type: 'string',
         coerce: coerceOutputPath,
-        describe: `The file path to output the results. Use 'stdout' to write to stdout.
+        describe: `The file or directory path to output the results. Use 'stdout' to write to stdout.
+Directories in the path must already exist. If a directory is specified, the file name will be based on the test URL and date.
 If using JSON output, default is stdout.
 If using HTML or CSV output, default is a file in the working directory with a name based on the test URL and date.
 If using multiple outputs, --output-path is appended with the standard extension for each output type. "reports/my-run" -> "reports/my-run.report.html", "reports/my-run.report.json", etc.
@@ -306,6 +316,24 @@ Example: --output-path=./lighthouse-results.html`,
     .choices('preset', /** @type {const} */ (['perf', 'experimental', 'desktop']))
 
     .check(argv => {
+      if (Array.isArray(argv.urlFile)) {
+        argv._.push(...argv.urlFile);
+      }
+
+      if (argv._.length > 1) {
+        if (argv.gatherMode || argv.auditMode) {
+          throw new Error('Cannot use -G/--gather-mode or -A/--audit-mode when auditing multiple URLs');
+        }
+
+        if (
+          typeof argv.outputPath === 'string' &&
+          argv.outputPath &&
+          (!fs.existsSync(argv.outputPath) || !fs.statSync(argv.outputPath).isDirectory())
+        ) {
+          throw new Error('--output-path must be an existing directory when auditing multiple URLs');
+        }
+      }
+
       // Lighthouse doesn't need a URL if...
       //   - We're just listing the available options.
       //   - We're just printing the config.
@@ -419,6 +447,29 @@ function coerceOutputPath(value) {
   return value;
 }
 
+/**
+ * Reads newline-delimited URLs from a file, ignoring empty lines and `#` comments.
+ * @param {unknown=} value
+ * @return {Array<string>=}
+ */
+function coerceUrlFile(value) {
+  if (value === undefined) return;
+
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    !fs.existsSync(value) ||
+    fs.statSync(value).isDirectory()
+  ) {
+    throw new Error(`--url-file (${value}) cannot be read`);
+  }
+
+  return fs.readFileSync(value, 'utf-8')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line.length > 0 && !line.startsWith('#'));
+}
+
 /**
  * Verifies value is a string, then coerces type to LH.Locale for convenience. However, don't
  * allowlist specific locales. Why? So we can support the user who requests 'es-MX' (unsupported)

package/cli/printer.js

@@ -6,6 +6,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import {setTimeout} from 'timers/promises';
 
 import log from 'lighthouse-logger';
 
@@ -40,14 +41,10 @@ function checkOutputPath(path) {
  * @param {string} output
  * @return {Promise<void>}
  */
-function writeToStdout(output) {
-  return new Promise(resolve => {
-    // small delay to avoid race with debug() logs
-    setTimeout(_ => {
-      process.stdout.write(`${output}\n`);
-      resolve();
-    }, 50);
-  });
+async function writeToStdout(output) {
+  // small delay to avoid race with debug() logs
+  await setTimeout(50);
+  process.stdout.write(`${output}\n`);
 }
 
 /**

package/cli/run.d.ts

@@ -11,14 +11,14 @@ export function parseChromeFlags(flags?: string | Array<string>): Array<string>;
 /**
  * @param {LH.RunnerResult} runnerResult
  * @param {LH.CliFlags} flags
- * @return {Promise<void>}
+ * @return {Promise<string|undefined>}
  */
-export function saveResults(runnerResult: LH.RunnerResult, flags: LH.CliFlags): Promise<void>;
+export function saveResults(runnerResult: LH.RunnerResult, flags: LH.CliFlags): Promise<string | undefined>;
 /**
- * @param {string} url
+ * @param {string|string[]|undefined} urlOrUrls
  * @param {LH.CliFlags} flags
  * @param {LH.Config|undefined} config
- * @return {Promise<LH.RunnerResult|undefined>}
+ * @return {Promise<LH.RunnerResult|LH.RunnerResult[]|undefined>}
  */
-export function runLighthouse(url: string, flags: LH.CliFlags, config: LH.Config | undefined): Promise<LH.RunnerResult | undefined>;
+export function runLighthouse(urlOrUrls: string | string[] | undefined, flags: LH.CliFlags, config: LH.Config | undefined): Promise<LH.RunnerResult | LH.RunnerResult[] | undefined>;
 //# sourceMappingURL=run.d.ts.map