browsertime 27.2.0 → 27.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 27.4.0 - 2026-05-24
+
+### Added
+* JS/CSS coverage collection for Chrome. `--chrome.coverage` turns it on for every iteration for users who want the data and accept that detailed V8 coverage deoptimizes scripts and will skew their timing metrics. `--enableProfileRun` also turns coverage on for Chrome alongside the existing trace, so users who want coverage without affecting their timings can lean on the same extra-iteration pattern they already use for tracing — the result is merged back into the main `browsertime.json` so consumers like sitespeed.io see the data in the same place they read every other metric. Each entry has a per-file breakdown (`url`, `totalBytes`, `usedBytes`, `unusedBytes`, `unusedPercent`) [#2480](https://github.com/sitespeedio/browsertime/pull/2480).
+
+### Fixed
+* HAR post-processing no longer throws when a page has no matching entries. Occasionally a HAR contains a page whose `pageref` has no entries — typically a navigation that didn't produce any requests, or an extension-injected page. `getDocumentRequests` and `getFinalURL` dereferenced `shift()` / `pop()` without a guard, and `getMainDocumentTimings` wrapped its entire per-page loop in a single try/catch so one bad page wiped out the main-document timings for every other page in the same HAR. Downstream this surfaced as a noisy triplet of warnings followed by an empty coach-data payload in sitespeed.io. The three crash points are now guarded and unresolvable pages are skipped [#2483](https://github.com/sitespeedio/browsertime/pull/2483).
+* Bumped `geckodriver` to a version with native ARM-64 support [#2482](https://github.com/sitespeedio/browsertime/pull/2482).
+
+## 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

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';
 
@@ -95,12 +95,16 @@ async function run(urls, options) {
       scriptsByCategory = merge(scriptsByCategory, userScripts);
     }
 
+    let result;
+    let storageManager;
+    let jsonName;
+
     try {
       if (options.preWarmServer) {
         await preWarmServer(urls, options);
       }
       await engine.start();
-      const result = await engine.runMultiple(urls, scriptsByCategory);
+      result = await engine.runMultiple(urls, scriptsByCategory);
       let saveOperations = [];
 
       // TODO setup by name
@@ -109,9 +113,9 @@ async function run(urls, options) {
       if (Array.isArray(firstUrl)) {
         firstUrl = firstUrl[0];
       }
-      const storageManager = new StorageManager(firstUrl, options);
+      storageManager = new StorageManager(firstUrl, options);
       const harName = options.har ?? 'browsertime';
-      const jsonName = options.output ?? 'browsertime';
+      jsonName = options.output ?? 'browsertime';
 
       saveOperations.push(storageManager.writeJson(jsonName + '.json', result));
 
@@ -169,6 +173,7 @@ async function run(urls, options) {
           options.chrome.traceCategory = [
             'disabled-by-default-v8.cpu_profiler'
           ];
+          options.chrome.coverage = true;
         }
       }
       if (options.enableVideoRun) {
@@ -186,9 +191,30 @@ async function run(urls, options) {
       }
       const traceEngine = new Engine(options);
       await traceEngine.start();
-      await traceEngine.runMultiple(urls, scriptsByCategory);
+      const profileResult = await traceEngine.runMultiple(
+        urls,
+        scriptsByCategory
+      );
       await traceEngine.stop();
       log.info('Extra run finished');
+
+      // Fill the main JSON's coverage from the profile run only when
+      // the main iterations didn't collect any (--enableProfileRun
+      // without --chrome.coverage). Otherwise the main run's
+      // per-iteration samples are what the user asked for.
+      let mergedCoverage = false;
+      for (const [i, pr] of profileResult.entries()) {
+        const main = result[i];
+        if (!main || !pr.coverage) continue;
+        if (main.coverage.js.length > 0 || main.coverage.css.length > 0) {
+          continue;
+        }
+        main.coverage = pr.coverage;
+        mergedCoverage = true;
+      }
+      if (mergedCoverage) {
+        await storageManager.writeJson(jsonName + '.json', result);
+      }
     }
   } catch (error) {
     log.error('Error running browsertime', error);

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/coverage.js

@@ -0,0 +1,198 @@
+import { getLogger } from '@sitespeed.io/log';
+
+const log = getLogger('browsertime.chrome.coverage');
+
+// Sum the union length of half-open [start, end) ranges.
+function unionLength(ranges) {
+  if (ranges.length === 0) return 0;
+  const sorted = ranges
+    .map(r => [r.startOffset, r.endOffset])
+    .toSorted((a, b) => a[0] - b[0]);
+  let total = 0;
+  let [curStart, curEnd] = sorted[0];
+  for (let i = 1; i < sorted.length; i++) {
+    const [s, e] = sorted[i];
+    if (s <= curEnd) {
+      if (e > curEnd) curEnd = e;
+    } else {
+      total += curEnd - curStart;
+      curStart = s;
+      curEnd = e;
+    }
+  }
+  total += curEnd - curStart;
+  return total;
+}
+
+function summarize(files) {
+  let totalBytes = 0;
+  let usedBytes = 0;
+  for (const file of files) {
+    totalBytes += file.totalBytes;
+    usedBytes += file.usedBytes;
+  }
+  const unusedBytes = totalBytes - usedBytes;
+  return {
+    totalBytes,
+    usedBytes,
+    unusedBytes,
+    unusedPercent: totalBytes > 0 ? (unusedBytes / totalBytes) * 100 : 0
+  };
+}
+
+export class Coverage {
+  constructor(cdp) {
+    this.rawClient = cdp.getRawClient();
+    this.started = false;
+    this.styleSheetUrls = new Map();
+    this.disposeStyleSheetListener = undefined;
+  }
+
+  async start() {
+    const client = this.rawClient;
+    this.styleSheetUrls.clear();
+    this.disposeStyleSheetListener = client.CSS.styleSheetAdded(
+      ({ header }) => {
+        if (header && header.styleSheetId) {
+          this.styleSheetUrls.set(
+            header.styleSheetId,
+            header.sourceURL || header.sourceMapURL || ''
+          );
+        }
+      }
+    );
+
+    await client.Debugger.enable();
+    await client.Profiler.enable();
+    await client.DOM.enable();
+    await client.CSS.enable();
+    await client.Profiler.startPreciseCoverage({
+      callCount: false,
+      detailed: true,
+      allowTriggeredUpdates: false
+    });
+    await client.CSS.startRuleUsageTracking();
+    this.started = true;
+  }
+
+  async collect() {
+    if (!this.started) return;
+    const client = this.rawClient;
+
+    let js;
+    let css;
+    try {
+      const jsResult = await client.Profiler.takePreciseCoverage();
+      js = await this.#processJs(jsResult.result || []);
+    } catch (error) {
+      log.warn('Could not collect JS coverage: %s', error.message);
+      js = {
+        totalBytes: 0,
+        usedBytes: 0,
+        unusedBytes: 0,
+        unusedPercent: 0,
+        files: []
+      };
+    }
+
+    try {
+      const cssResult = await client.CSS.stopRuleUsageTracking();
+      css = await this.#processCss(cssResult.ruleUsage || []);
+    } catch (error) {
+      log.warn('Could not collect CSS coverage: %s', error.message);
+      css = {
+        totalBytes: 0,
+        usedBytes: 0,
+        unusedBytes: 0,
+        unusedPercent: 0,
+        files: []
+      };
+    }
+
+    try {
+      await client.Profiler.stopPreciseCoverage();
+    } catch {
+      // ignore — collection already returned data
+    }
+
+    if (this.disposeStyleSheetListener) {
+      this.disposeStyleSheetListener();
+      this.disposeStyleSheetListener = undefined;
+    }
+
+    this.started = false;
+    return { js, css };
+  }
+
+  async #processJs(scripts) {
+    const client = this.rawClient;
+    const files = [];
+    for (const script of scripts) {
+      if (!script.url || !/^https?:/i.test(script.url)) {
+        continue;
+      }
+      let source;
+      try {
+        const r = await client.Debugger.getScriptSource({
+          scriptId: script.scriptId
+        });
+        source = r.scriptSource || '';
+      } catch {
+        continue;
+      }
+      const totalBytes = source.length;
+      if (totalBytes === 0) continue;
+
+      const usedRanges = [];
+      for (const fn of script.functions) {
+        for (const r of fn.ranges) {
+          if (r.count > 0) usedRanges.push(r);
+        }
+      }
+      const usedBytes = unionLength(usedRanges);
+      const unusedBytes = totalBytes - usedBytes;
+      files.push({
+        url: script.url,
+        totalBytes,
+        usedBytes,
+        unusedBytes,
+        unusedPercent: (unusedBytes / totalBytes) * 100
+      });
+    }
+    return { ...summarize(files), files };
+  }
+
+  async #processCss(ruleUsage) {
+    const client = this.rawClient;
+    const byStylesheet = new Map();
+    for (const u of ruleUsage) {
+      const list = byStylesheet.get(u.styleSheetId) || [];
+      list.push(u);
+      byStylesheet.set(u.styleSheetId, list);
+    }
+    const files = [];
+    for (const [styleSheetId, usages] of byStylesheet) {
+      let text;
+      try {
+        const r = await client.CSS.getStyleSheetText({ styleSheetId });
+        text = r.text || '';
+      } catch {
+        continue;
+      }
+      const totalBytes = text.length;
+      if (totalBytes === 0) continue;
+
+      const usedBytes = unionLength(usages.filter(u => u.used));
+      const unusedBytes = totalBytes - usedBytes;
+      files.push({
+        url: this.styleSheetUrls.get(styleSheetId) || '',
+        styleSheetId,
+        totalBytes,
+        usedBytes,
+        unusedBytes,
+        unusedPercent: (unusedBytes / totalBytes) * 100
+      });
+    }
+    return { ...summarize(files), files };
+  }
+}

package/lib/chrome/webdriver/chromium.js

@@ -15,6 +15,7 @@ import { parse } from '../traceCategoriesParser.js';
 import { pathToFolder } from '../../support/pathToFolder.js';
 import { loadUsbPowerProfiler } from '../../support/usbPower.js';
 import { ChromeDevtoolsProtocol } from '../chromeDevtoolsProtocol.js';
+import { Coverage } from '../coverage.js';
 import { NetworkManager } from '../networkManager.js';
 import { Android, isAndroidConfigured } from '../../android/index.js';
 import { getRenderBlocking } from './traceUtilities.js';
@@ -181,6 +182,11 @@ export class Chromium {
       }
     }
 
+    if (this.chrome.coverage) {
+      this.coverage = new Coverage(this.cdpClient);
+      await this.coverage.start();
+    }
+
     if (
       this.collectTracingEvents &&
       !this.isTracing &&
@@ -325,6 +331,14 @@ export class Chromium {
       );
     }
 
+    if (this.coverage) {
+      const coverage = await this.coverage.collect();
+      this.coverage = undefined;
+      if (coverage) {
+        result.coverage = coverage;
+      }
+    }
+
     if (this.chrome.cdp && this.chrome.cdp.performance) {
       const rawCDPMetrics = await this.cdpClient.getPerformanceMetrics();
       const cleanedMetrics = {};

package/lib/core/engine/collector.js

@@ -39,6 +39,7 @@ function getNewResult(url, options) {
     markedAsFailure: 0,
     failureMessages: [],
     cdp: { performance: [] },
+    coverage: { js: [], css: [] },
     android: { batteryTemperature: [], power: [] },
     timestamps: [],
     browserScripts: [],
@@ -185,6 +186,13 @@ export class Collector {
         });
       }
 
+      // Only available for Chrome with --chrome.coverage or
+      // --enableProfileRun.
+      if (data.coverage) {
+        results.coverage.js.push(data.coverage.js);
+        results.coverage.css.push(data.coverage.css);
+      }
+
       this._logIterationMetrics(data, url);
 
       if (data.visualMetrics) {

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
     };
   }