browsertime 27.1.0 → 27.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 27.3.0 - 2026-05-20
+
+### Added
+* `browsertime --help` is now navigable by topic. The default view shows a short curated list of common options plus the available topic names. `browsertime --help <topic>` shows just that topic, and `browsertime --help-all` reproduces the historical full dump for scripts and power users. The old single-screen dump of every option from all 13 topic groups was overwhelming for new users and slow to skim; the topic-filtered view follows the curl/ffmpeg pattern [#2467](https://github.com/sitespeedio/browsertime/pull/2467).
+
+### Fixed
+* TypeScript types and IntelliSense for navigation scripts are tightened across the script-facing surface. A new `BrowsertimeScript` type alias lets scripts annotate their default export and get both `context` and `commands` typed in one line. The high-level command helpers (`navigate`, `find`, `getText`, `fill`, `hover`, `press`, `getTitle`, `waitForUrl`, …) now surface their JSDoc parameter and return types in IntelliSense instead of being typed as `Function`, and `commands.find` resolves to a real `WebElement` so chained calls get completion from selenium-webdriver [#2476](https://github.com/sitespeedio/browsertime/pull/2476). `context.options`, `context.result`, and `context.taskData` are typed as `Record<string, any>` so editors offer completion on `context.options.` etc. [#2478](https://github.com/sitespeedio/browsertime/pull/2478). `commands.mouse` is now a proper shape (selector typed as `string`, `singleClick`'s options surface `waitForNavigation`) instead of an anonymous object literal, and `measure.stop` / `measure.clickAndMeasure` / `measure.stopAsError` return types are explicit (`Promise<void>` / `Promise<unknown>`) instead of `Promise<any>` [#2479](https://github.com/sitespeedio/browsertime/pull/2479).
+* How Browsertime publishes its TypeScript types is now safer. `scripting.d.ts` moved to the repo root next to `package.json` so it can't be clobbered by a future `tsc` outDir change, the `types` condition comes first under `exports` to match TypeScript's documented resolution rules, and `publint` runs as part of `prepublishOnly` so common package.json mistakes fail before a release goes out [#2477](https://github.com/sitespeedio/browsertime/pull/2477).
+* Replaced the direct `lodash.merge` dependency with a small in-tree `merge()` helper in `lib/support/util.js`. The helper matches lodash's actual semantics for the cases Browsertime relies on — arrays merged by index, `undefined` source values skipped unless the key is missing on the target, `Date`/`RegExp`/class instances passed by reference, prototype-pollution keys rejected — which finishes the lodash unbundling the same way sitespeed.io did [#2468](https://github.com/sitespeedio/browsertime/pull/2468).
+* Bumped dependencies: `chrome-har` 1.3.1 [#2469](https://github.com/sitespeedio/browsertime/pull/2469), `chrome-remote-interface` and `selenium-webdriver` [#2475](https://github.com/sitespeedio/browsertime/pull/2475), `@sitespeed.io/log` 2.0 [#2471](https://github.com/sitespeedio/browsertime/pull/2471), `chromedriver` / `edgedriver` / `geckodriver` [#2472](https://github.com/sitespeedio/browsertime/pull/2472).
+
+## 27.2.0 - 2026-05-12
+
+### Added
+* Surface the page-level `recalculateStyle` summary (beforeFCP / beforeLCP element counts + durations) on the first HAR page as `_renderBlocking.recalculateStyle`. The per-request `_renderBlocking` map already projected onto each entry stays where it is — the page-level summary is what powers the "Elements that needed recalculate style before FCP" view and was previously only reachable via `browsertime.json` [#2466](https://github.com/sitespeedio/browsertime/pull/2466).
+
 ## 27.1.0 - 2026-05-06
 
 ### Added

package/bin/browsertime.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import merge from 'lodash.merge';
 import { getLogger } from '@sitespeed.io/log';
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
@@ -13,6 +12,7 @@ import { configure } from '../lib/support/logging.js';
 import { parseCommandLine } from '../lib/support/cli.js';
 import { StorageManager } from '../lib/support/storageManager.js';
 import { loadScript } from '../lib/support/engineUtils.js';
+import { merge } from '../lib/support/util.js';
 import { setProperty, getProperty } from '../lib/support/util.js';
 import { isAndroidConfigured } from '../lib/android/index.js';
 

package/bin/browsertimeWebPageReplay.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import merge from 'lodash.merge';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { Engine } from '../lib/core/engine/index.js';
 import { configure as logging } from '../lib/support/logging.js';
+import { merge } from '../lib/support/util.js';
 
 async function runBrowsertime() {
   let yargsInstance = yargs(hideBin(process.argv));

package/lib/chrome/webdriver/chromium.js

@@ -415,6 +415,19 @@ export class Chromium {
               render.renderBlockingInfo[harRequest.request.url];
           }
         }
+        // Also stamp the page-level summary (recalculate-style
+        // elements + duration before FCP/LCP) onto the HAR's page
+        // object so HAR-only consumers can pick it up without
+        // needing browsertime.json. The per-request map is already
+        // projected onto each entry above, so we keep this payload
+        // to just the summary fields.
+        const harPage =
+          this.hars[index - 1].log.pages && this.hars[index - 1].log.pages[0];
+        if (harPage && render.renderBlocking.recalculateStyle) {
+          harPage._renderBlocking = {
+            recalculateStyle: render.renderBlocking.recalculateStyle
+          };
+        }
       }
 
       result.renderBlocking.requests = render.renderBlockingInfo;

package/lib/core/engine/command/measure.js

@@ -1,6 +1,5 @@
 import path from 'node:path';
 import { getLogger } from '@sitespeed.io/log';
-import merge from 'lodash.merge';
 import { timestamp as _timestamp } from '../../../support/engineUtils.js';
 import { pathToFolder } from '../../../support/pathToFolder.js';
 import {
@@ -9,7 +8,7 @@ import {
 } from '../../../support/userTiming.js';
 import { isAndroidConfigured, Android } from '../../../android/index.js';
 import { TCPDump } from '../../../support/tcpdump.js';
-import { getProperty } from '../../../support/util.js';
+import { getProperty, merge } from '../../../support/util.js';
 import { MeasureScreenshots } from './measure/screenshots.js';
 import { MeasureVideo } from './measure/video.js';
 const log = getLogger('browsertime.command.measure');
@@ -329,7 +328,7 @@ export class Measure {
    *
    * @async
    * @param {string} errorMessage - The message about the error. This will end up on the HTML report for sitespeed.io so give it a good message so you know what's gone wrong.
-   * @returns {Promise} A promise that resolves when the stop process has completed.
+   * @returns {Promise<void>} A promise that resolves when the stop process has completed.
    * @since 21.2.0
    */
   async stopAsError(errorMessage) {
@@ -362,7 +361,7 @@ export class Measure {
    * @async
    * @param {string} alias - The friendly name for this measurement.
    * @param {string} selector - The CSS selector of the element to click.
-   * @returns {Promise} A promise that resolves with the collected metrics data.
+   * @returns {Promise<unknown>} A promise that resolves with the collected metrics data.
    * @throws {Error} Throws an error if the element is not found or the measurement fails.
    */
   async clickAndMeasure(alias, selector) {
@@ -379,7 +378,7 @@ export class Measure {
    * @async
    * @param {string} testedStartUrl - The URL that was initially tested. If not provided, it will be obtained from the browser.
    * @throws {Error} Throws an error if there are issues in stopping the measurement or collecting data.
-   * @returns {Promise} A promise that resolves with the collected metrics data.
+   * @returns {Promise<unknown>} A promise that resolves with the collected metrics data.
    */
   async stop(testedStartUrl) {
     log.debug('Stop measuring');

package/lib/core/engine/commands.js

@@ -227,10 +227,10 @@ export class Commands {
      * Navigates to a specified URL and handles additional setup for a page visit.
      * @async
      * @example await commands.navigate('https://www.example.org');
-     * @type {Function}
      * @param {string} url - The URL to navigate to.
      * @throws {Error} Throws an error if navigation or setup fails.
      * @returns {Promise<void>} A promise that resolves when the navigation and setup are
+     * @type {(url: string) => Promise<void>}
      */
     this.navigate = measure._navigate.bind(measure);
 
@@ -244,7 +244,7 @@ export class Commands {
      * Add a text that will be an error attached to the current page.
      * @example await commands.error('My error message');
      * @param {string} message - The error message.
-     * @type {Function}
+     * @type {(message: string) => void}
      */
     this.error = measure._error.bind(measure);
 
@@ -252,7 +252,7 @@ export class Commands {
      * Mark this run as an failure. Add a message that explains the failure.
      * @example await commands.markAsFailure('My failure message');
      * @param {string} message - The message attached as a failure
-     * @type {Function}
+     * @type {(message: string) => void}
      */
     this.markAsFailure = measure._failure.bind(measure);
 
@@ -357,10 +357,6 @@ export class Commands {
      */
     this.debug = new Debug(browser, options);
 
-    /**
-     * Interact with the page using the mouse.
-     * @type {Object}
-     */
     const singleClickInstance = new SingleClick(
       browser,
       pageCompleteCheck,
@@ -375,6 +371,16 @@ export class Commands {
     const mouseMoveInstance = new MouseMove(browser, options);
     const clickAndHoldInstance = new ClickAndHold(browser);
 
+    /**
+     * Interact with the page using the mouse.
+     * @type {{
+     *   moveTo: (selector: string) => Promise<void>,
+     *   singleClick: (selector: string, mouseOptions?: { waitForNavigation?: boolean }) => Promise<void>,
+     *   doubleClick: (selector: string) => Promise<void>,
+     *   contextClick: (selector: string) => Promise<void>,
+     *   clickAndHold: ClickAndHold
+     * }}
+     */
     this.mouse = {
       moveTo: async selector => mouseMoveInstance.run(selector),
       singleClick: async (selector, mouseOptions) =>
@@ -485,7 +491,6 @@ export class Commands {
      * @param {string} text - The text to type into the element.
      * @returns {Promise<void>} A promise that resolves when the text has been added.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.type = async (selector, text) => {
       return this.addText(selector, text);
@@ -502,7 +507,7 @@ export class Commands {
      * @param {boolean} [options.visible=false] - If true, waits for the element to be visible.
      * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
+     * @type {(selector: string, options?: { timeout?: number, visible?: boolean }) => Promise<import('selenium-webdriver').WebElement>}
      */
     this.find = this.element.find.bind(this.element);
 
@@ -518,7 +523,6 @@ export class Commands {
      * @param {Object} [existsOptions] - Options.
      * @param {number} [existsOptions.timeout=0] - Maximum time to wait for the element. Default 0 (no wait).
      * @returns {Promise<boolean>} True if the element exists.
-     * @type {Function}
      */
     this.exists = async (selector, existsOptions = {}) => {
       const { locator } = parseSelector(selector);
@@ -552,7 +556,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<string>} The visible text content.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.getText = async selector => {
       const element = await findElement(selector);
@@ -567,7 +570,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<string>} The element's value.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.getValue = async selector => {
       const element = await findElement(selector);
@@ -581,7 +583,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<boolean>} True if the element is visible.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.isVisible = async selector => {
       const element = await findElement(selector);
@@ -597,7 +598,6 @@ export class Commands {
      * @param {string} attribute - The attribute name.
      * @returns {Promise<string>} The attribute value.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.getAttribute = async (selector, attribute) => {
       const element = await findElement(selector);
@@ -611,7 +611,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<boolean>} True if the element is enabled.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.isEnabled = async selector => {
       const element = await findElement(selector);
@@ -625,7 +624,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<boolean>} True if the element is checked/selected.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.isChecked = async selector => {
       const element = await findElement(selector);
@@ -640,7 +638,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<void>} A promise that resolves when the element is cleared.
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.clear = async selector => {
       const { locator } = parseSelector(selector);
@@ -665,7 +662,6 @@ export class Commands {
      * @param {Object<string, string>} fields - An object mapping selectors to values.
      * @returns {Promise<void>} A promise that resolves when all fields are filled.
      * @throws {Error} Throws an error if any element is not found.
-     * @type {Function}
      */
     this.fill = async fields => {
       for (const [selector, text] of Object.entries(fields)) {
@@ -682,7 +678,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<void>}
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.hover = async selector => {
       return this.mouse.moveTo(selector);
@@ -697,7 +692,6 @@ export class Commands {
      * @example await commands.press('Escape');
      * @param {string} key - The key name to press (e.g. 'Enter', 'Tab', 'Escape').
      * @returns {Promise<void>}
-     * @type {Function}
      */
     this.press = async key => {
       const keyValue = webdriver.Key[key.toUpperCase()] || key;
@@ -711,7 +705,6 @@ export class Commands {
      * @async
      * @example const title = await commands.getTitle();
      * @returns {Promise<string>} The page title.
-     * @type {Function}
      */
     this.getTitle = async () => {
       return browser.getDriver().getTitle();
@@ -722,7 +715,6 @@ export class Commands {
      * @async
      * @example const url = await commands.getUrl();
      * @returns {Promise<string>} The current URL.
-     * @type {Function}
      */
     this.getUrl = async () => {
       return browser.getDriver().getCurrentUrl();
@@ -736,7 +728,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<void>}
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.check = async selector => {
       const element = await findElement(selector);
@@ -754,7 +745,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<void>}
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.uncheck = async selector => {
       const element = await findElement(selector);
@@ -772,7 +762,6 @@ export class Commands {
      * @param {string} selector - The CSS selector or prefixed selector.
      * @returns {Promise<void>}
      * @throws {Error} Throws an error if the element is not found.
-     * @type {Function}
      */
     this.scrollIntoView = async selector => {
       const element = await findElement(selector);
@@ -795,7 +784,6 @@ export class Commands {
      * @param {number} [urlOptions.timeout=10000] - Maximum time to wait in milliseconds.
      * @returns {Promise<void>}
      * @throws {Error} Throws an error if the URL does not match within the timeout.
-     * @type {Function}
      */
     this.waitForUrl = async (pattern, urlOptions = {}) => {
       const timeout = urlOptions.timeout ?? 10_000;

package/lib/core/engine/context.js

@@ -30,13 +30,13 @@ export class Context {
   ) {
     /**
      * This is the yargs object you get from the cli. If you add --my.id you can get that using options.my.id.
-     * @type {Object}
+     * @type {Record<string, any>}
      */
     this.options = options;
 
     /**
      * Here the result from each run is stored.
-     * @type {Object}
+     * @type {Record<string, any>}
      */
     this.result = result;
 
@@ -58,7 +58,8 @@ export class Context {
     this.storageManager = storageManager;
 
     /**
-     * @type {Object}
+     * Scratch space shared between commands within a single iteration.
+     * @type {Record<string, any>}
      */
     this.taskData = {};
 
@@ -68,13 +69,7 @@ export class Context {
      * @type {{webdriver: WebDriverClass, driver: WebDriverInstance}}
      */
     this.selenium = {
-      /**
-       * @typedef {typeof import('selenium-webdriver')} WebDriverClass
-       */
       webdriver,
-      /**
-       * @typedef {import('selenium-webdriver').WebDriver} WebDriverInstance
-       */
       driver: instantiatedDriver
     };
   }

package/lib/core/engine/index.js

@@ -1,6 +1,5 @@
 import { arch as _arch } from 'node:os';
 import { getLogger } from '@sitespeed.io/log';
-import merge from 'lodash.merge';
 import { execaCommand as command } from 'execa';
 import { StorageManager } from '../../support/storageManager.js';
 import { Firefox } from '../../firefox/webdriver/firefox.js';
@@ -10,7 +9,12 @@ import {
   addConnectivity,
   removeConnectivity
 } from '../../connectivity/index.js';
-import { logResultLogLine, getProperty, toArray } from '../../support/util.js';
+import {
+  logResultLogLine,
+  getProperty,
+  toArray,
+  merge
+} from '../../support/util.js';
 import {
   getFullyLoaded,
   getMainDocumentTimings,

package/lib/core/seleniumRunner.js

@@ -1,5 +1,4 @@
 import { getLogger } from '@sitespeed.io/log';
-import merge from 'lodash.merge';
 import { Condition } from 'selenium-webdriver';
 import { isAndroidConfigured } from '../android/index.js';
 import { UrlLoadError, BrowserError, TimeoutError } from '../support/errors.js';
@@ -8,7 +7,7 @@ import { getViewPort } from '../support/getViewPort.js';
 import { defaultPageCompleteCheck } from './pageCompleteChecks/defaultPageCompleteCheck.js';
 import { pageCompleteCheckByInactivity } from './pageCompleteChecks/pageCompleteCheckByInactivity.js';
 import { spaInactivity as spaCheck } from './pageCompleteChecks/spaInactivity.js';
-import { getProperty } from '../support/util.js';
+import { getProperty, merge } from '../support/util.js';
 const log = getLogger('browsertime');
 
 const defaults = {

package/lib/safari/safariInspectorClient.js

@@ -1,4 +1,3 @@
-/* global WebSocket */
 import { execa } from 'execa';
 import { getLogger } from '@sitespeed.io/log';
 

package/lib/screenshot/index.js

@@ -1,5 +1,4 @@
 import path from 'node:path';
-import merge from 'lodash.merge';
 import { getLogger } from '@sitespeed.io/log';
 import { screenshotDefaults } from './defaults.js';
 import {
@@ -8,6 +7,7 @@ import {
   saveJpg
 } from '../support/images/index.js';
 import { loadCustomJimp } from './loadCustomJimp.js';
+import { merge } from '../support/util.js';
 
 const SCREENSHOT_DIR = 'screenshots';
 const log = getLogger('browsertime.screenshot');

package/lib/support/browserScript.js

@@ -141,8 +141,7 @@ async function findAndParseScripts(root, category) {
     const categoryName = path.basename(dirPath);
 
     return scriptsFromDirectory(dirPath).then(scripts => {
-      const categories = {};
-      categories[categoryName] = scripts;
+      const categories = { [categoryName]: scripts };
       return categories;
     });
   }
@@ -154,8 +153,7 @@ async function findAndParseScripts(root, category) {
           let scripts = {};
 
           scripts[name] = generateScriptObject(name, root, content);
-          let categories = {};
-          categories[category] = scripts;
+          let categories = { [category]: scripts };
 
           return categories;
         })

package/lib/support/cli.js

@@ -14,6 +14,12 @@ import { geckoProfilerDefaults } from '../firefox/settings/geckoProfilerDefaults
 import { findUpSync } from './fileUtil.js';
 import { setProperty, getProperty } from './util.js';
 import { execaSync } from 'execa';
+import {
+  classifyHelp,
+  captureTopics,
+  applyHelpFilter,
+  buildEpilog
+} from './helpTopics.js';
 
 const configPath = findUpSync(['.browsertime.json']);
 
@@ -152,7 +158,16 @@ export function parseCommandLine() {
     arg === '--android' ? '--android.enabled' : arg
   );
 
-  let yargsInstance = yargs(hideBin(argvFix));
+  // Detect --help <topic> / --help-all up front and rewrite them to a
+  // bare --help so yargs still triggers its normal help+exit flow.
+  const rawArgs = hideBin(argvFix);
+  const help = classifyHelp(rawArgs);
+
+  let yargsInstance = yargs(help.args);
+  // Wrap .option() to record each option's key under its inline
+  // `group: '<topic>'` field. Browsertime already annotates every option
+  // with a group, so this gives us a topic -> keys map for free.
+  const topicKeys = captureTopics(yargsInstance);
   let validated = yargsInstance
     .parserConfiguration({
       'camel-case-expansion': false,
@@ -923,76 +938,76 @@ export function parseCommandLine() {
       type: 'boolean',
       default: false,
       describe: 'Save one screenshot per iteration.',
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('screenshotLCP', {
       type: 'boolean',
       default: false,
       describe:
         'Save one screenshot per iteration that shows the largest contentful paint element (if the browser supports LCP).',
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('screenshotLS', {
       type: 'boolean',
       default: false,
       describe:
         'Save one screenshot per iteration that shows the layout shift elements (if the browser supports layout shift).',
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('screenshotParams.type', {
       describe: 'Set the file type of the screenshot',
       choices: ['png', 'jpg'],
       default: screenshotDefaults.type,
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('screenshotParams.jpg.quality', {
       describe: 'Quality of the JPEG screenshot. 1-100',
       default: screenshotDefaults.jpg.quality,
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('screenshotParams.maxSize', {
       describe: 'The max size of the screenshot (width and height).',
       default: screenshotDefaults.maxSize,
-      group: 'Screenshot'
+      group: 'screenshot'
     })
     .option('pageCompleteCheck', {
       describe:
         'Supply a JavaScript (inline or JavaScript file) that decides when the browser is finished loading the page and can start to collect metrics. The JavaScript snippet is repeatedly queried to see if page has completed loading (indicated by the script returning true). Use it to fetch timings happening after the loadEventEnd. By default the tests ends 2 seconds after loadEventEnd. Also checkout --pageCompleteCheckInactivity and --pageCompleteCheckPollTimeout',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageCompleteWaitTime', {
       describe:
         'How long time you want to wait for your pageComplteteCheck to finish, after it is signaled to closed. Extra parameter passed on to your pageCompleteCheck.',
       default: 8000,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageCompleteCheckInactivity', {
       describe:
         'Alternative way to choose when to end your test. This will wait for 2 seconds of inactivity that happens after loadEventEnd.',
       type: 'boolean',
       default: false,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageCompleteCheckNetworkIdle', {
       describe:
         'Alternative way to choose when to end your test that works in Chrome and Firefox. Uses CDP or WebDriver Bidi to look at network traffic instead of running JavaScript in the browser to know when to end the test. By default this will wait 5 seconds of inactivity in the network log (no requets/responses in 5 seconds). Use --timeouts.networkIdle to change the 5 seconds. The test will end after 2 minutes if there is still activity on the network. You can change that timout using --timeouts.pageCompleteCheck ',
       type: 'boolean',
       default: false,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageCompleteCheckPollTimeout', {
       type: 'number',
       default: 1500,
       describe:
         'The time in ms to wait for running the page complete check the next time.',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageCompleteCheckStartWait', {
       type: 'number',
       default: 5000,
       describe:
         'The time in ms to wait for running the page complete check for the first time. Use this when you have a pageLoadStrategy set to none',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('pageLoadStrategy', {
       type: 'string',
@@ -1000,7 +1015,7 @@ export function parseCommandLine() {
       choices: ['eager', 'none', 'normal'],
       describe:
         'Set the strategy to waiting for document readiness after a navigation event. After the strategy is ready, your pageCompleteCheck will start running.',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('iterations', {
       alias: 'n',
@@ -1025,14 +1040,14 @@ export function parseCommandLine() {
       default: 0,
       describe:
         'Extra time added for the browser to settle before starting to test a URL. This delay happens after the browser was opened and before the navigation to the URL',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('webdriverPageload', {
       type: 'boolean',
       describe:
         'Use webdriver.get to initialize the page load instead of window.location.',
       default: false,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('proxy.pac', {
       type: 'string',
@@ -1168,7 +1183,7 @@ export function parseCommandLine() {
         'Use internal browser functionality to clear browser cache between runs instead of only using Selenium.',
       type: 'boolean',
       default: false,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('basicAuth', {
       describe:
@@ -1310,7 +1325,7 @@ export function parseCommandLine() {
       default: false,
       describe:
         'Flush DNS between runs, works on Mac OS and Linux. Your user needs sudo rights to be able to flush the DNS.',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('extension', {
       describe:
@@ -1321,7 +1336,7 @@ export function parseCommandLine() {
         'Convenient parameter to use if you test a SPA application: will automatically wait for X seconds after last network activity and use hash in file names. Read more: https://www.sitespeed.io/documentation/sitespeed.io/spa/',
       type: 'boolean',
       default: false,
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('cjs', {
       describe:
@@ -1334,7 +1349,7 @@ export function parseCommandLine() {
       default: 3,
       describe:
         'If the browser fails to start, you can retry to start it this amount of times.',
-      group: 'PageLoad'
+      group: 'pageload'
     })
     .option('preWarmServer', {
       type: 'boolean',
@@ -1363,8 +1378,14 @@ export function parseCommandLine() {
     .alias('V', 'version')
     .alias('v', 'verbose')
     .wrap(yargsInstance.terminalWidth())
+    .epilog(buildEpilog(help.mode, help.topic, [...topicKeys.keys()]))
     .check(validateInput);
 
+  // Filter the visible options based on the requested help mode. This
+  // must happen before .argv is read because that's what triggers
+  // yargs to render help and exit.
+  applyHelpFilter(yargsInstance, help.mode, help.topic, topicKeys);
+
   let argv = validated.argv;
 
   if (

package/lib/support/har/index.js

@@ -1,12 +1,11 @@
 import { createRequire } from 'node:module';
-import merge from 'lodash.merge';
 import { pathToFolder } from '../pathToFolder.js';
 import { localTime } from '../util.js';
 import { getLogger } from '@sitespeed.io/log';
 const log = getLogger('browsertime');
 const require = createRequire(import.meta.url);
 const version = require('../../../package.json').version;
-import { pick, isEmpty, getProperty } from '../../support/util.js';
+import { pick, isEmpty, getProperty, merge } from '../../support/util.js';
 
 const sensitiveHeaders = new Set([
   'authorization',