feat: add category filtering for Lighthouse config and prompts

- Introduced category filtering in the Lighthouse configuration, allowing users to specify a subset of categories for audits.
- Added tests to validate the behavior of category filtering, including handling of empty and undefined categories.
- Implemented a new function to parse category flags from command line inputs, ensuring only valid categories are accepted.
- Updated prompts to allow users to select categories interactively if not provided via command line.
- Exported LAB_CATEGORIES for easier access to available categories.
- Updated type definitions to include categories in lab options.
- Bumped version to 0.2.1 and updated dependencies, including Lighthouse to version 13.3.0.

Author: Hugoer

bin/web-perf.js

@@ -25,12 +25,19 @@ async function labAction(url, options, cmd) {
         const logger = require('../lib/logger');
         const stripJsonPropsOpt = cmd?.getOptionValueSource('stripJsonProps') === 'cli' ? options.stripJsonProps : undefined;
         const cleanOpt = cmd?.getOptionValueSource('clean') === 'cli' ? options.clean : undefined;
+        const { LAB_CATEGORIES } = require('../lib/profiles');
         const resolved = await promptLab(url, { ...options, stripJsonProps: stripJsonPropsOpt, clean: cleanOpt });
         const skipAudits = parseSkipAuditsFlag(options.skipAudits) || resolved.skipAudits;
         const blockedUrlPatterns = parseBlockedUrlPatternsFlag(options.blockedUrlPatterns) || resolved.blockedUrlPatterns;
+        // promptLab always sets resolved.categories (parsed from --category or the checkbox)
+        const categories = resolved.categories || [];
         const stripJsonProps = resolved.stripJsonProps ?? options.stripJsonProps;
         const clean = resolved.clean ?? false;
 
+        if (categories.length > 0 && categories.length < LAB_CATEGORIES.length) {
+            logger.info(`Categories: ${categories.join(', ')}`);
+        }
+
         const totalUrls = resolved.urls.length;
         const totalRuns = totalUrls * resolved.runs.length;
         const isBatch = totalUrls > 1;
@@ -59,7 +66,7 @@ async function labAction(url, options, cmd) {
                     }
                     try {
                         // eslint-disable-next-line no-await-in-loop
-                        const outputPath = await runLab(targetUrl, { ...run, skipAudits, blockedUrlPatterns, stripJsonProps, clean, port: chrome.port, silent: isBatch });
+                        const outputPath = await runLab(targetUrl, { ...run, skipAudits, blockedUrlPatterns, categories, stripJsonProps, clean, port: chrome.port, silent: isBatch });
                         results.push({ url: targetUrl, profile: label, outputPath });
                         if (!isBatch) {
                             const elapsed = formatElapsed(Date.now() - startTime);
@@ -434,6 +441,7 @@ program
     .option('--urls-file <path>', 'Path to a file with one URL per line')
     .option('--skip-audits <audits>', 'Comma-separated audits to skip (default: full-page-screenshot,screenshot-thumbnails,final-screenshot,valid-source-maps)')
     .option('--blocked-url-patterns <patterns>', 'Comma-separated URL patterns to block during audit (e.g. *.google-analytics.com,*.facebook.net)')
+    .option('--category <categories>', 'Lighthouse categories, comma-separated: performance, accessibility, best-practices, seo, agentic-browsing (default: all)')
     .option('--no-strip-json-props', 'Disable stripping of unneeded properties (i18n, timing) from JSON output')
     .option('--clean', 'Write an AI-friendly clean copy to results/lab/clean/ alongside the raw file')
     .action(withCatch(labAction));

lib/clean.test.js

@@ -55,8 +55,8 @@ const ROOT_KEYS = ['i18n', 'timing', 'configSettings', 'categoryGroups',
 function makeLabReport(overrides = {}) {
     return {
         requestedUrl: 'https://example.com',
-        mainDocumentUrl: 'https://example.com',      // LH13 new field
-        finalDisplayedUrl: 'https://example.com',    // LH13 new field
+        mainDocumentUrl: 'https://example.com',
+        finalDisplayedUrl: 'https://example.com',
         finalUrl: 'https://example.com',
         fetchTime: '2024-01-01T00:00:00.000Z',
         formFactor: 'desktop',

lib/lab.js

@@ -3,7 +3,7 @@ const path = require('path');
 
 const { cleanLabReport } = require('./clean');
 const logger = require('./logger');
-const { resolveProfileSettings } = require('./profiles');
+const { resolveProfileSettings, LAB_CATEGORIES } = require('./profiles');
 const { SKIPPABLE_AUDITS } = require('./prompts');
 const { stripJsonProps } = require('./strip-props');
 const { ensureCommandDir, buildFilename } = require('./utils');
@@ -49,19 +49,24 @@ function buildLighthouseConfig(labOptions, profileSettings = {}) {
     const disableFullPageScreenshot = rawSkipAudits.includes('full-page-screenshot');
     const skipAudits = rawSkipAudits.filter((a) => a !== 'full-page-screenshot');
     const blockedUrlPatterns = labOptions.blockedUrlPatterns || [];
+    // Only pin onlyCategories for a proper subset; an empty or full selection keeps the
+    // Lighthouse default (all categories, including agentic-browsing).
+    const categories = labOptions.categories || [];
+    const filterCategories = categories.length > 0 && categories.length < LAB_CATEGORIES.length;
     const settings = {
         ...profileSettings,
         skipAudits,
         ...(disableFullPageScreenshot && { disableFullPageScreenshot: true }),
         ...(blockedUrlPatterns.length > 0 && { blockedUrlPatterns }),
+        ...(filterCategories && { onlyCategories: categories }),
     };
-    const hasSettings = Object.keys(profileSettings).length > 0 || skipAudits.length > 0 || disableFullPageScreenshot || blockedUrlPatterns.length > 0;
+    const hasSettings = Object.keys(profileSettings).length > 0 || skipAudits.length > 0 || disableFullPageScreenshot || blockedUrlPatterns.length > 0 || filterCategories;
     return hasSettings ? { extends: 'lighthouse:default', settings } : undefined;
 }
 
 /**
  * @param {string} url
- * @param {{ port?: number, profile?: string, network?: string, device?: string, skipAudits?: string[], blockedUrlPatterns?: string[], stripJsonProps?: boolean, silent?: boolean }} [labOptions]
+ * @param {{ port?: number, profile?: string, network?: string, device?: string, skipAudits?: string[], blockedUrlPatterns?: string[], categories?: string[], stripJsonProps?: boolean, silent?: boolean }} [labOptions]
  * @returns {Promise<LabReport>}
  */
 async function runLabAudit(url, labOptions = {}) {

lib/lab.test.js

@@ -68,6 +68,40 @@ describe('runLab Lighthouse config', () => {
     });
 });
 
+describe('runLab Lighthouse config — category filtering', () => {
+    it('sets onlyCategories for a proper subset', () => {
+        const config = buildLighthouseConfig({ categories: ['performance', 'seo'] });
+        expect(config.settings.onlyCategories).toEqual(['performance', 'seo']);
+    });
+
+    it('sets onlyCategories when filtering to a single category (agentic-browsing)', () => {
+        const config = buildLighthouseConfig({ categories: ['agentic-browsing'] });
+        expect(config.settings.onlyCategories).toEqual(['agentic-browsing']);
+    });
+
+    it('omits onlyCategories when all five categories are selected (Lighthouse default)', () => {
+        const config = buildLighthouseConfig({
+            categories: ['performance', 'accessibility', 'best-practices', 'seo', 'agentic-browsing'],
+        });
+        expect(config.settings.onlyCategories).toBeUndefined();
+    });
+
+    it('omits onlyCategories when categories is empty or undefined', () => {
+        expect(buildLighthouseConfig({ categories: [] }).settings.onlyCategories).toBeUndefined();
+        expect(buildLighthouseConfig({}).settings.onlyCategories).toBeUndefined();
+    });
+
+    it('composes onlyCategories with profile settings and skipAudits', () => {
+        const config = buildLighthouseConfig(
+            { categories: ['performance'], skipAudits: ['screenshot-thumbnails'] },
+            { formFactor: 'desktop' },
+        );
+        expect(config.settings.onlyCategories).toEqual(['performance']);
+        expect(config.settings.formFactor).toBe('desktop');
+        expect(config.settings.skipAudits).toEqual(['screenshot-thumbnails']);
+    });
+});
+
 describe('runLabAudit — I/O isolation', () => {
     afterEach(() => {
         vi.restoreAllMocks();

lib/profiles.js

@@ -1,6 +1,8 @@
 const MOBILE_UA = 'Mozilla/5.0 (Linux; Android 11; moto g power (2022)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36';
 const DESKTOP_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
 
+const LAB_CATEGORIES = ['performance', 'accessibility', 'best-practices', 'seo', 'agentic-browsing'];
+
 const NETWORK_PRESETS = {
     '3g-slow': {
         rttMs: 400,
@@ -225,6 +227,7 @@ module.exports = {
     PROFILES,
     NETWORK_PRESETS,
     DEVICE_PRESETS,
+    LAB_CATEGORIES,
     MOBILE_UA,
     DESKTOP_UA,
     resolveProfileSettings,

lib/profiles.test.js

@@ -1,6 +1,12 @@
 import { describe, it, expect } from 'vitest';
 
-const { buildThrottling, buildScreenEmulation, resolveProfileSettings } = require('./profiles');
+const { buildThrottling, buildScreenEmulation, resolveProfileSettings, LAB_CATEGORIES } = require('./profiles');
+
+describe('LAB_CATEGORIES', () => {
+    it('exports the five Lighthouse 13 category IDs', () => {
+        expect(LAB_CATEGORIES).toEqual(['performance', 'accessibility', 'best-practices', 'seo', 'agentic-browsing']);
+    });
+});
 
 describe('buildThrottling', () => {
     it('should return correct throttling object for preset', () => {

lib/prompts.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 
 const { CRUX_FORM_FACTORS, DEFAULT_CRUX_FORM_FACTORS } = require('./crux');
 const logger = require('./logger');
-const { PROFILES, NETWORK_PRESETS, DEVICE_PRESETS } = require('./profiles');
+const { PROFILES, NETWORK_PRESETS, DEVICE_PRESETS, LAB_CATEGORIES } = require('./profiles');
 const { PSI_STRATEGIES, DEFAULT_PSI_STRATEGIES } = require('./psi');
 
 // Lazy-load inquirer (~230ms cold require) — only needed when prompts actually run
@@ -203,6 +203,19 @@ function parseProfileFlag(profileStr) {
     return names;
 }
 
+function parseLabCategoriesFlag(categoryStr) {
+    if (!categoryStr) {
+        return [];
+    }
+    const names = categoryStr.split(',').map((c) => c.trim().toLowerCase()).filter(Boolean);
+    for (const name of names) {
+        if (!LAB_CATEGORIES.includes(name)) {
+            throw new Error(`Unknown category: "${name}". Valid categories: ${LAB_CATEGORIES.join(', ')}`);
+        }
+    }
+    return [...new Set(names)];
+}
+
 function parseCruxFormFactors(formFactorStr) {
     if (!formFactorStr) {
         return [...DEFAULT_CRUX_FORM_FACTORS];
@@ -350,6 +363,24 @@ async function promptLab(url, options) {
         }
     }
 
+    // Category selection — prompt if not provided via --category flag.
+    // All categories (including agentic-browsing) are checked by default.
+    if (options.category) {
+        resolved.categories = parseLabCategoriesFlag(options.category);
+    } else {
+        assertTTY();
+        const categoryChoices = LAB_CATEGORIES.map((c) => ({ name: c, value: c, checked: true }));
+        const { categories } = await inquirer.prompt([
+            {
+                type: 'checkbox',
+                name: 'categories',
+                message: 'Lighthouse categories (all selected by default):',
+                choices: categoryChoices,
+            },
+        ]);
+        resolved.categories = categories;
+    }
+
     // Skip audits selection — prompt if not provided via --skip-audits flag
     if (!options.skipAudits) {
         assertTTY();
@@ -872,6 +903,7 @@ module.exports = {
     parseProfileFlag,
     parsePsiStrategies,
     parseCruxFormFactors,
+    parseLabCategoriesFlag,
     parseSkipAuditsFlag,
     parseBlockedUrlPatternsFlag,
     validateUrl,

lib/prompts.test.js

@@ -224,8 +224,44 @@ describe('parseBlockedUrlPatternsFlag', () => {
     });
 });
 
+describe('parseLabCategoriesFlag', () => {
+    it('should return empty array for falsy input', () => {
+        expect(prompts.parseLabCategoriesFlag(undefined)).toEqual([]);
+        expect(prompts.parseLabCategoriesFlag('')).toEqual([]);
+    });
+
+    it('should parse a single category', () => {
+        expect(prompts.parseLabCategoriesFlag('performance')).toEqual(['performance']);
+    });
+
+    it('should parse comma-separated categories and preserve order', () => {
+        expect(prompts.parseLabCategoriesFlag('seo,performance')).toEqual(['seo', 'performance']);
+    });
+
+    it('should accept agentic-browsing', () => {
+        expect(prompts.parseLabCategoriesFlag('agentic-browsing')).toEqual(['agentic-browsing']);
+    });
+
+    it('should normalize case and trim whitespace', () => {
+        expect(prompts.parseLabCategoriesFlag(' Performance , SEO ')).toEqual(['performance', 'seo']);
+    });
+
+    it('should de-duplicate categories', () => {
+        expect(prompts.parseLabCategoriesFlag('performance,performance,seo')).toEqual(['performance', 'seo']);
+    });
+
+    it('should throw on unknown category', () => {
+        expect(() => prompts.parseLabCategoriesFlag('pwa')).toThrow('Unknown category: "pwa". Valid categories: performance, accessibility, best-practices, seo, agentic-browsing');
+    });
+
+    it('should throw on unknown category in comma list', () => {
+        expect(() => prompts.parseLabCategoriesFlag('performance,foo')).toThrow('Unknown category: "foo"');
+    });
+});
+
 describe('promptLab', () => {
-    const baseOpts = { profile: undefined, network: undefined, device: undefined, urls: undefined, urlsFile: undefined, clean: false };
+    // category set so the interactive category prompt is skipped in tests that don't exercise it
+    const baseOpts = { profile: undefined, network: undefined, device: undefined, urls: undefined, urlsFile: undefined, category: 'performance', clean: false };
 
     it('should return runs array with single profile when provided via flag', async () => {
         promptSpy.mockResolvedValueOnce({ skipAudits: [] });
@@ -584,6 +620,35 @@ describe('promptLab', () => {
             expect(promptSpy).toHaveBeenCalledTimes(3);
         });
     });
+
+    describe('--category', () => {
+        it('parses categories from the --category flag without prompting', async () => {
+            promptSpy.mockResolvedValueOnce({ skipAudits: [] });
+            promptSpy.mockResolvedValueOnce({ blockedUrlPatternsInput: '' });
+            promptSpy.mockResolvedValueOnce({ stripJsonProps: true });
+            const result = await prompts.promptLab('https://example.com', { ...baseOpts, profile: 'low', category: 'agentic-browsing,seo' });
+            expect(result.categories).toEqual(['agentic-browsing', 'seo']);
+            expect(promptSpy).toHaveBeenCalledTimes(3);
+        });
+
+        it('prompts with a checkbox (all selected by default) when no --category flag', async () => {
+            promptSpy.mockResolvedValueOnce({ categories: ['performance', 'accessibility', 'best-practices', 'seo', 'agentic-browsing'] });
+            promptSpy.mockResolvedValueOnce({ skipAudits: [] });
+            promptSpy.mockResolvedValueOnce({ blockedUrlPatternsInput: '' });
+            promptSpy.mockResolvedValueOnce({ stripJsonProps: true });
+            const result = await prompts.promptLab('https://example.com', { ...baseOpts, profile: 'low', category: undefined });
+            expect(result.categories).toEqual(['performance', 'accessibility', 'best-practices', 'seo', 'agentic-browsing']);
+        });
+
+        it('returns the subset selected in the interactive checkbox', async () => {
+            promptSpy.mockResolvedValueOnce({ categories: ['agentic-browsing'] });
+            promptSpy.mockResolvedValueOnce({ skipAudits: [] });
+            promptSpy.mockResolvedValueOnce({ blockedUrlPatternsInput: '' });
+            promptSpy.mockResolvedValueOnce({ stripJsonProps: true });
+            const result = await prompts.promptLab('https://example.com', { ...baseOpts, profile: 'low', category: undefined });
+            expect(result.categories).toEqual(['agentic-browsing']);
+        });
+    });
 });
 
 describe('promptPsi', () => {