feat(plugin-lighthouse): implement multiple URL support

Author: hanna-skryl

code-pushup.preset.ts

@@ -20,7 +20,9 @@ import {
 } from './packages/plugin-jsdocs/src/lib/constants.js';
 import { filterGroupsByOnlyAudits } from './packages/plugin-jsdocs/src/lib/utils.js';
 import lighthousePlugin, {
+  type LighthouseUrls,
   lighthouseGroupRef,
+  mergeLighthouseCategories,
 } from './packages/plugin-lighthouse/src/index.js';
 import typescriptPlugin, {
   type TypescriptPluginOptions,
@@ -135,11 +137,14 @@ export const jsPackagesCoreConfig = async (): Promise<CoreConfig> => ({
 });
 
 export const lighthouseCoreConfig = async (
-  url: string,
-): Promise<CoreConfig> => ({
-  plugins: [await lighthousePlugin(url)],
-  categories: lighthouseCategories,
-});
+  urls: LighthouseUrls,
+): Promise<CoreConfig> => {
+  const lhPlugin = await lighthousePlugin(urls);
+  return {
+    plugins: [lhPlugin],
+    categories: mergeLighthouseCategories(lhPlugin, lighthouseCategories),
+  };
+};
 
 export const jsDocsCoreConfig = (
   config: JsDocsPluginConfig | string[],

e2e/plugin-lighthouse-e2e/tests/__snapshots__/collect.e2e.test.ts.snap

@@ -77,6 +77,12 @@ exports[`PLUGIN collect report with lighthouse-plugin NPM package > should run p
           "title": "Document has a valid \`hreflang\`",
         },
       ],
+      "context": {
+        "urlCount": 1,
+        "weights": {
+          "1": 1,
+        },
+      },
       "groups": [
         {
           "refs": [

packages/cli/src/lib/implementation/filter.middleware.ts

@@ -116,10 +116,13 @@ function applyPluginFilters(
   options: Pick<FilterOptions, 'skipPlugins' | 'onlyPlugins'>,
 ): CoreConfig['plugins'] {
   const { skipPlugins = [], onlyPlugins = [] } = options;
-  const filteredPlugins = filterPluginsFromCategories({
-    categories,
-    plugins,
-  });
+  const filteredPlugins =
+    onlyPlugins.length === 0
+      ? filterPluginsFromCategories({
+          categories,
+          plugins,
+        })
+      : plugins;
   if (skipPlugins.length === 0 && onlyPlugins.length === 0) {
     return filteredPlugins;
   }

packages/cli/src/lib/implementation/filter.middleware.unit.test.ts

@@ -414,6 +414,44 @@ describe('filterMiddleware', () => {
       ),
     );
   });
+
+  it('should allow onlyPlugins to include plugins not referenced by categories', () => {
+    const { plugins } = filterMiddleware({
+      plugins: [
+        {
+          slug: 'p1',
+          audits: [{ slug: 'a1-p1', isSkipped: false }],
+          groups: [
+            {
+              slug: 'g1-p1',
+              refs: [{ slug: 'a1-p1', weight: 1 }],
+              isSkipped: false,
+            },
+          ],
+        },
+        {
+          slug: 'p2',
+          audits: [{ slug: 'a1-p2', isSkipped: false }],
+          groups: [
+            {
+              slug: 'g1-p2',
+              refs: [{ slug: 'a1-p2', weight: 1 }],
+              isSkipped: false,
+            },
+          ],
+        },
+      ] as PluginConfig[],
+      categories: [
+        {
+          slug: 'c1',
+          refs: [{ type: 'group', plugin: 'p1', slug: 'g1-p1', weight: 1 }],
+        },
+      ] as CategoryConfig[],
+      onlyPlugins: ['p2'],
+    });
+
+    expect(plugins.map(plugin => plugin.slug)).toStrictEqual(['p2']);
+  });
 });
 
 describe('filterSkippedInPlugins', () => {

packages/models/src/index.ts

@@ -67,8 +67,10 @@ export {
 } from './lib/persist-config.js';
 export {
   pluginConfigSchema,
+  pluginContextSchema,
   pluginMetaSchema,
   type PluginConfig,
+  type PluginContext,
   type PluginMeta,
 } from './lib/plugin-config.js';
 export {

packages/models/src/lib/plugin-config.ts

@@ -10,6 +10,12 @@ import {
 import { errorItems, hasMissingStrings } from './implementation/utils.js';
 import { runnerConfigSchema, runnerFunctionSchema } from './runner-config.js';
 
+export const pluginContextSchema = z
+  .record(z.unknown())
+  .optional()
+  .describe('Plugin-specific context data for helpers');
+export type PluginContext = z.infer<typeof pluginContextSchema>;
+
 export const pluginMetaSchema = packageVersionSchema()
   .merge(
     metaSchema({
@@ -31,6 +37,7 @@ export const pluginDataSchema = z.object({
   runner: z.union([runnerConfigSchema, runnerFunctionSchema]),
   audits: pluginAuditsSchema,
   groups: groupsSchema,
+  context: pluginContextSchema,
 });
 type PluginData = z.infer<typeof pluginDataSchema>;
 

packages/plugin-lighthouse/README.md

@@ -117,6 +117,100 @@ export default {
 };
 ```
 
+## Multiple URLs
+
+The Lighthouse plugin supports running audits against multiple URLs in a single invocation. To do this, provide an array of URLs as the first argument to the plugin:
+
+```ts
+import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+
+export default {
+  // ...
+  plugins: [
+    // ...
+    await lighthousePlugin(['https://example.com', 'https://example.com/contact']),
+  ],
+};
+```
+
+### Assigning weights to URLs
+
+You can assign custom weights to URLs by passing an object instead of an array. This is useful when some pages are more important than others (e.g., your homepage vs. a contact page). The keys are URLs, and the values are their weights.
+
+URLs with higher weights contribute more to the overall category scores. For example, a URL with weight 2 has twice the influence of a URL with weight 1.
+
+```ts
+import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+
+export default {
+  // ...
+  plugins: [
+    // ...
+    await lighthousePlugin({
+      'https://example.com': 2,
+      'https://example.com/contact': 1,
+    })
+  ];
+};
+```
+
+### Categories with multiple URLs
+
+When running Lighthouse against multiple URLs, use the `mergeLighthouseCategories` utility to ensure categories are correctly expanded and results are aggregated per URL.
+
+#### Basic usage
+
+```ts
+import lighthousePlugin, { mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
+
+const lhPlugin = await lighthousePlugin(urls);
+
+export default {
+  plugins: [
+    // ...
+    lhPlugin,
+  ],
+  categories: [
+    // ...
+    ...mergeLighthouseCategories(lhPlugin),
+  ],
+};
+```
+
+#### Custom categories
+
+If you provide custom categories, you can reference both groups and audits as usual. The merging utility will expand each referenced group or audit for every URL, assigning the correct per-URL weight.
+
+```ts
+import lighthousePlugin, { lighthouseAuditRef, lighthouseGroupRef, mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
+
+const lhPlugin = await lighthousePlugin(urls);
+
+export default {
+  // ...
+  plugins: [
+    // ...
+    lhPlugin,
+  ],
+  categories: [
+    // ...
+    ...mergeLighthouseCategories(lhPlugin, [
+      {
+        slug: 'performance',
+        title: 'Performance',
+        refs: [lighthouseGroupRef('performance'), lighthouseAuditRef('first-contentful-paint', 2)],
+      },
+    ]),
+  ],
+};
+```
+
+### Behavior Summary
+
+- **No categories**: The plugin auto-generates categories from the plugin's default Lighthouse groups.
+- **Custom categories**: The plugin expands all referenced audits and groups for each URL, applying appropriate weights.
+- **Empty array** (`categories: []`): No categories are created or expanded, which is useful when you only want audit data.
+
 ## Flags
 
 The plugin accepts an optional second argument, `flags`.

packages/plugin-lighthouse/src/index.ts

@@ -6,11 +6,12 @@ export {
   LIGHTHOUSE_PLUGIN_SLUG,
   LIGHTHOUSE_OUTPUT_PATH,
 } from './lib/constants.js';
-export {
-  lighthouseAuditRef,
-  lighthouseGroupRef,
-  type LighthouseGroupSlugs,
-} from './lib/utils.js';
-export type { LighthouseOptions } from './lib/types.js';
+export { lighthouseAuditRef, lighthouseGroupRef } from './lib/utils.js';
+export type {
+  LighthouseGroupSlug,
+  LighthouseOptions,
+  LighthouseUrls,
+} from './lib/types.js';
 export { lighthousePlugin } from './lib/lighthouse-plugin.js';
 export default lighthousePlugin;
+export { mergeLighthouseCategories } from './lib/merge-categories.js';

packages/plugin-lighthouse/src/lib/constants.ts

@@ -10,3 +10,13 @@ export const LIGHTHOUSE_OUTPUT_PATH = path.join(
   DEFAULT_PERSIST_OUTPUT_DIR,
   LIGHTHOUSE_PLUGIN_SLUG,
 );
+
+export const LIGHTHOUSE_GROUP_SLUGS = [
+  'performance',
+  'accessibility',
+  'best-practices',
+  'seo',
+  'pwa',
+] as const;
+
+export const SINGLE_URL_THRESHOLD = 1;

packages/plugin-lighthouse/src/lib/lighthouse-plugin.ts

@@ -2,26 +2,24 @@ import { createRequire } from 'node:module';
 import type { PluginConfig } from '@code-pushup/models';
 import { LIGHTHOUSE_PLUGIN_SLUG } from './constants.js';
 import { normalizeFlags } from './normalize-flags.js';
-import {
-  LIGHTHOUSE_GROUPS,
-  LIGHTHOUSE_NAVIGATION_AUDITS,
-} from './runner/constants.js';
+import { normalizeUrlInput, processAuditsAndGroups } from './processing.js';
 import { createRunnerFunction } from './runner/runner.js';
-import type { LighthouseOptions } from './types.js';
-import { markSkippedAuditsAndGroups } from './utils.js';
+import type { LighthouseOptions, LighthouseUrls } from './types.js';
 
 export function lighthousePlugin(
-  url: string,
+  urls: LighthouseUrls,
   flags?: LighthouseOptions,
 ): PluginConfig {
   const { skipAudits, onlyAudits, onlyCategories, ...unparsedFlags } =
     normalizeFlags(flags ?? {});
 
-  const { audits, groups } = markSkippedAuditsAndGroups(
-    LIGHTHOUSE_NAVIGATION_AUDITS,
-    LIGHTHOUSE_GROUPS,
-    { skipAudits, onlyAudits, onlyCategories },
-  );
+  const { urls: normalizedUrls, context } = normalizeUrlInput(urls);
+
+  const { audits, groups } = processAuditsAndGroups(normalizedUrls, {
+    skipAudits,
+    onlyAudits,
+    onlyCategories,
+  });
 
   const packageJson = createRequire(import.meta.url)(
     '../../package.json',
@@ -35,11 +33,12 @@ export function lighthousePlugin(
     icon: 'lighthouse',
     audits,
     groups,
-    runner: createRunnerFunction(url, {
+    runner: createRunnerFunction(normalizedUrls, {
       skipAudits,
       onlyAudits,
       onlyCategories,
       ...unparsedFlags,
     }),
+    context,
   };
 }