Skip to content

fix(cli): keep complete lighthouse configs from extending the default - #350

Merged
ChristopherPHolder merged 2 commits into
mainfrom
fix/complete-lh-config
Nov 13, 2026
Merged

ChristopherPHolder merged 2 commits into
mainfrom
fix/complete-lh-config

Conversation

@ChristopherPHolder

@ChristopherPHolder ChristopherPHolder commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #348

Problem

mergeLhConfig added extends: 'lighthouse:default' to every non-empty config. A flow config that lists its own artifacts, audits and categories without extends is complete. Lighthouse then treated it as an extension of the default config and merged the artifacts by id, and failed on the first step when a gatherer was given as an implementation where the default config names it by path:

TypeError: Expected object but got string
    at _mergeConfigFragment (lighthouse/core/config/config-helpers.js:81:41)

A global collect.config with extends caused the same error, because { ...globalCfg, ...localCfg } kept the global extends.

Fix

A flow config with artifacts and no extends counts as complete (isCompleteLhConfig):

  • it gets no extends;
  • it takes only settings from the global config, with the flow's settings winning.

Configs without artifacts behave as before and still get extends: 'lighthouse:default'.

Tests

  • Unit tests for mergeLhConfig and isCompleteLhConfig. They cover a complete flow config on its own and with a global config that has extends, plus the existing behaviour.
  • e2e tests in e2e/cli-e2e/tests/collect/config.e2e.test.ts with a new complete-config.uf.mts mock. It gives the DevtoolsLog gatherer as an implementation and runs the flow with and without a global extends config. Both tests fail on main with Expected object but got string and pass with this change.

Behaviour change

A flow config that has artifacts and no extends no longer gets the default config added. If a config relied on user-flow adding extends, for example to add a custom artifact on top of the defaults, its report now only contains what the config lists. The fix is to set extends: 'lighthouse:default' explicitly. Lighthouse treats a config without extends the same way.

Docs

The README (also the npm page), packages/cli/docs/lh-configuraton.md and the docs site page now explain how configs are combined:

  • where a config can come from;
  • how the flow config is laid over the global one;
  • when extends is added, and what Lighthouse does with it;
  • the priority order for a single setting: Lighthouse default → global config → flow config → flowOptions.flags → step options;
  • complete configs.

They also correct an earlier claim that --configPath overrides the rc file. It replaces collect.configPath, and combining it with collect.config stops the run.

A flow config that lists its own artifacts and has no extends is complete.
user-flow added extends: 'lighthouse:default' to it, and Lighthouse then
failed merging its artifacts with the default ones (Expected object but got
string). A complete config now gets no extends and takes only settings from
the global config.

Closes #348
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

Document the order in which the global config, the flow config, flags and
step options apply, when user-flow adds extends, and how complete configs
are handled. The README (also the npm page), the GitHub docs and the docs
site all describe the same rules. Also correct the claim that --configPath
overrides the rc file: it replaces collect.configPath, and combining it
with collect.config stops the run.
@github-actions

Copy link
Copy Markdown

❗❗❗ report generated by this PR ❗❗❗

☕ Order Coffee ☕

Date/Time: 2026-11-13 16:03

Step Name Gather Mode Performance Accessibility Best Practices Seo Agentic Browsing
🧭 Navigate to coffee cart navigation 77 93 100 83 50
☕ Select coffee timespan 17/17 - 8/8 - -
✔ Coffee selected snapshot Ø 1/1 16/18 4/4 3/5 1/3
🛒 Checkout order timespan 19/19 - 8/8 - -
🧾 Order checked out snapshot Ø 1/1 19/20 4/4 3/5 1/3
💌 Submit order timespan 18/18 - 8/8 - -
📧 Order submitted snapshot Ø 1/1 20/22 4/4 3/5 1/3
🧭 Navigate to github navigation 98 92 100 83 50

@github-actions

Copy link
Copy Markdown

☕ Order Coffee ☕

Date/Time: 2026-11-13 16:03

Step Name Gather Mode Performance Accessibility Best Practices Seo Agentic Browsing
🧭 Navigate to coffee cart navigation 92 93 100 83 50
☕ Select coffee timespan 17/17 - 8/8 - -
✔ Coffee selected snapshot Ø 1/1 16/18 4/4 3/5 1/3
🛒 Checkout order timespan 19/19 - 8/8 - -
🧾 Order checked out snapshot Ø 1/1 19/20 4/4 3/5 1/3
💌 Submit order timespan 18/18 - 8/8 - -
📧 Order submitted snapshot Ø 1/1 20/22 4/4 3/5 1/3
🧭 Navigate to github navigation 94 92 100 83 50

@ChristopherPHolder
ChristopherPHolder merged commit 3ddbaba into main Nov 13, 2026
5 checks passed
@ChristopherPHolder
ChristopherPHolder deleted the fix/complete-lh-config branch November 13, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

flowOptions.config without extends fails: user-flow adds extends: 'lighthouse:default' to complete configs

1 participant