browsertime 27.3.0 → 27.4.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 27.4.1 - 2026-05-25
+
+### Fixed
+* `--chrome.coverage` no longer reports "0 B unused" for functions that executed at least once. The JS used-bytes calculation took the union of every V8 range with count > 0, but V8 returns nested ranges — an outer range over the whole function body and inner ranges over sub-blocks. If a function ran at all, its outer range already covered the whole body and the inner count == 0 ranges (the actual dead branches) got absorbed into the union and contributed nothing. On modern bundles where module-evaluation top-level code runs for almost every function, the per-script unused-% collapsed to roughly zero across the board, leaving sitespeed.io rendering a "0 B unused" column on pages that obviously ship plenty of dead code. The calculation now walks the ranges as nested intervals, painting the innermost range's count at every byte (the same definition Chrome DevTools' Coverage panel uses), so dead branches inside executed functions show up correctly. CSS rule-usage tracking returns flat, non-overlapping ranges and is unchanged [#2484](https://github.com/sitespeedio/browsertime/pull/2484).
+
+## 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

package/bin/browsertime.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/lib/chrome/coverage.js

@@ -0,0 +1,232 @@
+import { getLogger } from '@sitespeed.io/log';
+
+const log = getLogger('browsertime.chrome.coverage');
+
+// Sum the union length of half-open [start, end) ranges. Used for the
+// flat, non-nested ranges that CSS rule-usage tracking returns.
+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;
+}
+
+// Count used bytes for a script under detailed (block-level) V8
+// coverage. The CDP returns nested ranges: the outermost range is the
+// function body and inner ranges are sub-blocks. An inner range with
+// count == 0 inside a containing range with count > 0 represents dead
+// code in an otherwise-executed function — those bytes must read as
+// unused. A naive union of every range whose count > 0 is wrong: the
+// outer range alone covers the entire function, so inner count == 0
+// ranges get masked and zero-count branches disappear, making typical
+// modern bundles look as if every byte was executed. Walk every range
+// across every function from outermost to innermost (start ascending,
+// length descending), painting a per-byte coverage flag; inner ranges
+// overwrite outer ones, so the final flag at each byte reflects the
+// innermost range's count.
+export function usedJsBytes(scriptCoverage, totalBytes) {
+  const ranges = [];
+  for (const fn of scriptCoverage.functions) {
+    for (const r of fn.ranges) {
+      if (r.endOffset > r.startOffset) ranges.push(r);
+    }
+  }
+  if (ranges.length === 0) return 0;
+  ranges.sort((a, b) =>
+    a.startOffset === b.startOffset
+      ? b.endOffset - a.endOffset
+      : a.startOffset - b.startOffset
+  );
+  const used = new Uint8Array(totalBytes);
+  for (const r of ranges) {
+    const start = Math.max(0, r.startOffset);
+    const end = Math.min(totalBytes, r.endOffset);
+    if (end > start) used.fill(r.count > 0 ? 1 : 0, start, end);
+  }
+  let count = 0;
+  for (let i = 0; i < totalBytes; i++) {
+    if (used[i] === 1) count++;
+  }
+  return count;
+}
+
+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 usedBytes = usedJsBytes(script, totalBytes);
+      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/support/cli.js

@@ -373,6 +373,20 @@ export function parseCommandLine() {
         'If you use --user-data-dir as an argument to Chrome and want to clean that directory between each iteration you should use --chrome.cleanUserDataDir true.',
       group: 'chrome'
     })
+    .option('chrome.coverage', {
+      type: 'boolean',
+      default: false,
+      describe:
+        'Collect JavaScript and CSS code coverage on every iteration. ' +
+        'Per-iteration summaries with a per-file breakdown land in the ' +
+        'per-URL result as coverage.js[] and coverage.css[]. This has a ' +
+        'real performance cost: detailed JS coverage causes V8 to ' +
+        'deoptimize and will skew timing metrics like LCP, TBT and INP. ' +
+        'Use --enableProfileRun instead if you want coverage without ' +
+        'affecting your timing data - it collects coverage during the ' +
+        'extra profile iteration only.',
+      group: 'chrome'
+    })
     .option('cpu', {
       type: 'boolean',
       describe:
@@ -651,7 +665,7 @@ export function parseCommandLine() {
     .option('enableProfileRun', {
       type: 'boolean',
       describe:
-        'Make one extra run that collects the profiling trace log (no other metrics is collected). For Chrome it will collect the timeline trace, for Firefox it will get the Geckoprofiler trace. This means you do not need to get the trace for all runs and can skip the overhead it produces.'
+        'Make one extra run that collects the profiling trace log (no other metrics is collected). For Chrome it will collect the timeline trace and JavaScript/CSS coverage, for Firefox it will get the Geckoprofiler trace. This means you do not need to get the trace for all runs and can skip the overhead it produces.'
     })
     .option('enableVideoRun', {
       type: 'boolean',

package/lib/support/har/index.js

@@ -42,6 +42,7 @@ function getDocumentRequests(entries, pageId) {
 
   do {
     entry = pageEntries.shift();
+    if (!entry) break;
     requests.push(entry);
   } while (entry.response.redirectURL);
 
@@ -52,7 +53,7 @@ function getFinalURL(entries, pageref) {
   const requests = getDocumentRequests(entries, pageref);
 
   const finalEntry = requests.pop();
-  return finalEntry.request.url;
+  return finalEntry ? finalEntry.request.url : undefined;
 }
 
 function addExtrasToHAR(
@@ -249,13 +250,16 @@ export function getMainDocumentTimings(har) {
     for (let page of har.log.pages) {
       const pageId = page.id;
       const url = page._url;
+      if (url === undefined) continue;
 
       let pageEntries = [...entries];
       const finalURL = getFinalURL(pageEntries, pageId);
+      if (finalURL === undefined) continue;
 
       pageEntries = pageEntries.filter(
         entry => entry.pageref === pageId && entry.request.url === finalURL
       );
+      if (pageEntries.length === 0) continue;
 
       timings.push({ url, timings: pageEntries[0].timings });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browsertime",
   "description": "Get performance metrics from your web page using Browsertime.",
-  "version": "27.3.0",
+  "version": "27.4.1",
   "bin": "./bin/browsertime.js",
   "type": "module",
   "types": "./scripting.d.ts",
@@ -9,7 +9,7 @@
     "@devicefarmer/adbkit": "3.3.8",
     "@sitespeed.io/chromedriver": "148.0.7778",
     "@sitespeed.io/edgedriver": "148.0.3967",
-    "@sitespeed.io/geckodriver": "0.36.1",
+    "@sitespeed.io/geckodriver": "0.36.2",
     "@sitespeed.io/log": "2.0.0",
     "@sitespeed.io/throttle": "6.0.0",
     "chrome-har": "1.3.1",