feat(plugin-lighthouse): export default Chrome flags

Author: hanna-skryl

code-pushup.preset.ts

@@ -1,4 +1,3 @@
-import { DEFAULT_FLAGS } from 'chrome-launcher/dist/flags.js';
 import coveragePlugin, {
   getNxCoveragePaths,
 } from './dist/packages/plugin-coverage';
@@ -107,11 +106,7 @@ export const lighthouseCoreConfig = async (
   url: string,
 ): Promise<CoreConfig> => {
   return {
-    plugins: [
-      await lighthousePlugin(url, {
-        chromeFlags: DEFAULT_FLAGS.concat(['--headless']),
-      }),
-    ],
+    plugins: [await lighthousePlugin(url)],
     categories: lighthouseCategories,
   };
 };

e2e/plugin-lighthouse-e2e/mocks/fixtures/code-pushup.config.lh-default.ts

@@ -1,5 +1,5 @@
-import { DEFAULT_FLAGS } from 'chrome-launcher/dist/flags.js';
 import lighthousePlugin, {
+  DEFAULT_CHROME_FLAGS,
   lighthouseGroupRef,
 } from '@code-pushup/lighthouse-plugin';
 import type { CoreConfig } from '@code-pushup/models';
@@ -18,7 +18,7 @@ export default {
         // seo category
         `hreflang`,
       ],
-      chromeFlags: DEFAULT_FLAGS.concat([`--headless`, `--verbose`]),
+      chromeFlags: DEFAULT_CHROME_FLAGS.concat([`--verbose`]),
     }),
   ],
   categories: [

packages/plugin-lighthouse/README.md

@@ -119,24 +119,27 @@ export default {
 
 ## Flags
 
-The plugin accepts a second optional argument, `flags`.
+The plugin accepts an optional second argument, `flags`.
 
-`flags` is the Lighthouse [CLI flags](https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80) as a JS object.
+`flags` is a JavaScript object containing Lighthouse [CLI flags](https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80).
 
-Within the flags object a couple of other external configuration files can be referenced. E.g. `configPath` , `preset` or `budgetPath` reference external `json` or JavaScript files.
+Within the `flags` object, external configuration files can be referenced using options like `configPath` , `preset`, or `budgetPath`. These options allow Lighthouse to load custom configurations, audit presets, or performance budgets from external `json` or JavaScript files.
 
-For a complete list the [official documentation of CLI flags](https://github.com/GoogleChrome/lighthouse/blob/main/readme.md#cli-options)
+For a complete list of available options, refer to [the official Lighthouse documentation](https://github.com/GoogleChrome/lighthouse/blob/main/readme.md#cli-options).
 
 > [!TIP]  
-> If you are not used to work with the Lighthouse CLI you would pass flags like this:
+> If you are new to working with the Lighthouse CLI, flags can be passed like this:
 > `lighthouse https://example.com --output=json --chromeFlags='--headless=shell'`
 >
-> Now with the plugin it would look like this:
+> With the plugin, the configuration would be:
 >
 > ```ts
 > // code-pushup.config.ts
 > ...
-> lighthousePlugin('https://example.com', { output: 'json', chromeFlags: ['--headless=shell']});
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: ['--headless=shell'],
+> });
 > ```
 
 > [!note]
@@ -149,14 +152,47 @@ For a complete list the [official documentation of CLI flags](https://github.com
 
 ## Chrome Flags for Tooling
 
-We recommend using Chrome flags for more stable runs in a tooling environment.
-The [`chrome-launcher`](https://www.npmjs.com/package/chrome-launcher) package provides a set of flags dedicated to tooling that they also documented very well.
+We recommend using Chrome flags for more stable runs in a tooling environment. The [`chrome-launcher`](https://www.npmjs.com/package/chrome-launcher) package offers a well-documented set of flags specifically designed to ensure reliable execution.
+
+The latest version of `@code-pushup/lighthouse-plugin` provides `DEFAULT_CHROME_FLAGS`, a pre-configured constant that includes Chrome’s default flags for stable, headless execution out of the box. This means you do not need to specify `chromeFlags` manually unless you want to modify them.
+
+### Default Usage
+
+If no `chromeFlags` are provided, the plugin automatically applies the default configuration:
 
 > ```ts
-> // code-pushup.config.ts
-> import { DEFAULT_FLAGS } from 'chrome-launcher/dist/flags.js';
-> ...
-> lighthousePlugin('https://example.com', { output: 'json', chromeFlags: DEFAULT_FLAGS });
+> import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   // Defaults to DEFAULT_CHROME_FLAGS internally
+> });
+> ```
+
+### Adding Extra Flags
+
+If additional Chrome flags are required (e.g., verbose logging or debugging), they can be appended to the default flags:
+
+> ```ts
+> import lighthousePlugin, { DEFAULT_CHROME_FLAGS } from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: DEFAULT_CHROME_FLAGS.concat(['--verbose']),
+> });
+> ```
+
+### Overriding Default Flags
+
+To completely override the default flags and provide a custom configuration:
+
+> ```ts
+> import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: ['--verbose'],
+> });
 > ```
 
 ## Config

packages/plugin-lighthouse/package.json

@@ -7,6 +7,7 @@
     "@code-pushup/models": "0.51.0",
     "@code-pushup/utils": "0.51.0",
     "ansis": "^3.3.0",
+    "chrome-launcher": "^1.1.1",
     "lighthouse": "^12.0.0",
     "lighthouse-logger": "2.0.1"
   }

packages/plugin-lighthouse/src/index.ts

@@ -2,6 +2,7 @@ import { lighthousePlugin } from './lib/lighthouse-plugin';
 
 export { LIGHTHOUSE_REPORT_NAME } from './lib/runner';
 export {
+  DEFAULT_CHROME_FLAGS,
   LIGHTHOUSE_PLUGIN_SLUG,
   LIGHTHOUSE_OUTPUT_PATH,
 } from './lib/constants';

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

@@ -1,6 +1,10 @@
+import { DEFAULT_FLAGS } from 'chrome-launcher/dist/flags.js';
 import { join } from 'node:path';
 import { DEFAULT_PERSIST_OUTPUT_DIR } from '@code-pushup/models';
 
+// headless is needed to pass CI on Linux and Windows (locally it works without headless too)
+export const DEFAULT_CHROME_FLAGS = [...DEFAULT_FLAGS, '--headless'];
+
 export const LIGHTHOUSE_PLUGIN_SLUG = 'lighthouse';
 export const LIGHTHOUSE_OUTPUT_PATH = join(
   DEFAULT_PERSIST_OUTPUT_DIR,

packages/plugin-lighthouse/src/lib/normalize-flags.unit.test.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { getLogMessages } from '@code-pushup/test-utils';
 import { ui } from '@code-pushup/utils';
-import { LIGHTHOUSE_OUTPUT_PATH } from './constants';
+import { DEFAULT_CHROME_FLAGS, LIGHTHOUSE_OUTPUT_PATH } from './constants';
 import { logUnsupportedFlagsInUse, normalizeFlags } from './normalize-flags';
 import { LIGHTHOUSE_REPORT_NAME } from './runner/constants';
 import type { LighthouseOptions } from './types';
@@ -46,8 +46,7 @@ describe('normalizeFlags', () => {
   const normalizedDefaults = {
     verbose: false,
     saveAssets: false,
-    // needed to pass CI on linux and windows (locally it works without headless too)
-    chromeFlags: ['--headless=shell'],
+    chromeFlags: DEFAULT_CHROME_FLAGS,
     port: 0,
     hostname: '127.0.0.1',
     view: false,

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

@@ -7,7 +7,7 @@ import {
 } from 'lighthouse';
 import { join } from 'node:path';
 import type { Audit, Group } from '@code-pushup/models';
-import { LIGHTHOUSE_OUTPUT_PATH } from '../constants';
+import { DEFAULT_CHROME_FLAGS, LIGHTHOUSE_OUTPUT_PATH } from '../constants';
 
 const { audits, categories } = defaultConfig;
 
@@ -89,8 +89,7 @@ export const DEFAULT_CLI_FLAGS = {
   // https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80
   verbose: false,
   saveAssets: false,
-  // needed to pass CI on linux and windows (locally it works without headless too)
-  chromeFlags: ['--headless=shell'],
+  chromeFlags: DEFAULT_CHROME_FLAGS,
   port: 0,
   hostname: '127.0.0.1',
   view: false,