browsertime 26.3.1 → 27.0.0

package/CHANGELOG.md

@@ -1,9 +1,78 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 27.0.0 - 2026-05-01
+
+### Highlights
+
+This release is a big push on the scripting API and on iOS real-device testing. All old scripting commands will work but we have new and improveed
+syntax that you can use if you follow our documentation. This release also tries to support the upcoming Chrome soft navigations.
+
+* **Unified selector syntax across commands.** All interaction commands now accept selectors directly (`commands.click('#btn')`, `commands.addText('#input', 'text')`, etc.) with optional `id:`/`xpath:`/`text:`/`link:`/`name:`/`class:` prefixes. The old `AndWait` family is deprecated in favour of `{ waitForNavigation: true }`.
+* **A much bigger convenience-command surface.** New `type`, `find`, `getText`, `getValue`, `isVisible`, `exists`, `clear`, `fill`, `getAttribute`, `isEnabled`, `isChecked`, `hover`, `press`, `getTitle`, `getUrl`, `check`, `uncheck`, `scrollIntoView`, `select.byText`, `waitForUrl`, `clickAndMeasure`, `click.byText`, plus a full `cookie` command.
+* **Chrome soft navigations.** SPA route changes (React, Next.js, Vue, Turbo) now produce a HAR page and the standard FCP/LCP/CLS/INP metrics, using Chrome's PerformanceObserver soft-navigation entry type.
+* **Safari on iOS over USB.** HAR via `ios_webkit_debug_proxy`, plus video recording and visual metrics via a CoreMediaIO screen-capture helper.
+* **TypeScript navigation scripts** are now supported on Node.js 22.18.0+ via native type stripping.
+
+### Breaking
+* Changed default `--timeouts.elementWait` from 0 to 6000ms. All element commands (click, addText) now auto-wait up to 6 seconds for elements to appear. Set `--timeouts.elementWait 0` to restore the old behavior [#2389](https://github.com/sitespeedio/browsertime/pull/2389).
+* Click commands now use the Selenium Actions API for real OS-level mouse events instead of JavaScript `.click()`. Elements must be visible and interactable. If you need to click a hidden element, use `commands.js.run()` instead [#2381](https://github.com/sitespeedio/browsertime/pull/2381).
+
+### Added
+* Unified selector syntax for all interaction commands. You can now call `commands.click('#btn')`, `commands.addText('#input', 'text')`, `commands.wait('#el', { timeout: 5000 })`, `commands.select('#dropdown', 'value')`, and `commands.set('#field', 'value')` directly. Supports prefixes: `id:`, `xpath:`, `text:`, `link:`, `name:`, `class:` — CSS selector is the default [#2390](https://github.com/sitespeedio/browsertime/pull/2390) [#2408](https://github.com/sitespeedio/browsertime/pull/2408).
+* The `AndWait` methods are deprecated in favour of `{ waitForNavigation: true }` [#2390](https://github.com/sitespeedio/browsertime/pull/2390) [#2396](https://github.com/sitespeedio/browsertime/pull/2396).
+* Navigation methods (back, forward, refresh) now support `{ waitForNavigation: true }` for consistency [#2408](https://github.com/sitespeedio/browsertime/pull/2408).
+* Added `commands.type(selector, text)` as a shorthand for `addText` with a more conventional parameter order [#2387](https://github.com/sitespeedio/browsertime/pull/2387).
+* Added `commands.find(selector, options)` helper that combines element lookup with optional waiting and visibility checks [#2386](https://github.com/sitespeedio/browsertime/pull/2386).
+* Added `commands.measure.clickAndMeasure(alias, selector)` shortcut for the common measure.start/click/measure.stop pattern [#2382](https://github.com/sitespeedio/browsertime/pull/2382).
+* Added `commands.click.byText(text)` to click any element by visible text, not just links [#2384](https://github.com/sitespeedio/browsertime/pull/2384).
+* Added `--timeouts.elementWait` option for auto-waiting on elements before interaction [#2383](https://github.com/sitespeedio/browsertime/pull/2383).
+* Added support for TypeScript scripts (.ts, .mts, .cts) using Node.js native type stripping (requires Node.js 22.18.0+) [#2363](https://github.com/sitespeedio/browsertime/pull/2363).
+* Added `commands.getText(selector)`, `commands.getValue(selector)`, and `commands.isVisible(selector)` convenience methods [#2411](https://github.com/sitespeedio/browsertime/pull/2411).
+* Added `commands.exists(selector, { timeout })` for checking element presence without throwing [#2412](https://github.com/sitespeedio/browsertime/pull/2412).
+* Added `commands.clear(selector)` to clear form element content [#2413](https://github.com/sitespeedio/browsertime/pull/2413).
+* Added `commands.fill({ selector: text, ... })` for filling multiple form fields at once [#2414](https://github.com/sitespeedio/browsertime/pull/2414).
+* Added unified selector syntax to mouse commands: `commands.mouse.singleClick(selector)`, `commands.mouse.doubleClick(selector)`, `commands.mouse.contextClick(selector)`, `commands.mouse.moveTo(selector)` [#2415](https://github.com/sitespeedio/browsertime/pull/2415).
+* Added `commands.cookie` for managing browser cookies: `get`, `getAll`, `set`, `delete`, `deleteAll` [#2420](https://github.com/sitespeedio/browsertime/pull/2420).
+* Added `commands.getAttribute(selector, name)`, `commands.isEnabled(selector)`, and `commands.isChecked(selector)` for element state queries [#2421](https://github.com/sitespeedio/browsertime/pull/2421).
+* Added `commands.hover(selector)` as alias for mouse.moveTo, `commands.press(key)` for keyboard input, `commands.getTitle()` and `commands.getUrl()` for page info [#2422](https://github.com/sitespeedio/browsertime/pull/2422).
+* Added `commands.check(selector)` and `commands.uncheck(selector)` for checkbox/radio interactions [#2423](https://github.com/sitespeedio/browsertime/pull/2423).
+* Added `commands.scrollIntoView(selector)` to scroll elements into the viewport [#2425](https://github.com/sitespeedio/browsertime/pull/2425).
+* Added `commands.select.byText(selector, text)` to select dropdown options by visible text [#2426](https://github.com/sitespeedio/browsertime/pull/2426).
+* Added `commands.waitForUrl(pattern, { timeout })` to wait for URL changes after navigation [#2427](https://github.com/sitespeedio/browsertime/pull/2427).
+* Added video recording and visual metrics for Safari on iOS over USB. A native helper captures the device's screen via CoreMediaIO and pipes frames to ffmpeg. The device is woken into screen-capture mode automatically — no manual QuickTime step required [#2432](https://github.com/sitespeedio/browsertime/pull/2432) [#2436](https://github.com/sitespeedio/browsertime/pull/2436).
+* Added HAR capture for Safari on iOS via `ios_webkit_debug_proxy`. Browsertime starts and stops `iwdp` automatically and exits with a clear error if it isn't installed (`brew install ios-webkit-debug-proxy`). New `--safari.includeResponseBodies` CLI option. macOS Safari is unaffected [#2431](https://github.com/sitespeedio/browsertime/pull/2431).
+* Added soft navigation support for Chrome. Single-page app route changes (React, Next.js, Vue, Turbo) now produce a HAR page and the standard FCP/LCP/CLS/INP metrics, using Chrome's PerformanceObserver soft-navigation entry type to confirm user interaction + URL change + visible paint [#2438](https://github.com/sitespeedio/browsertime/pull/2438).
+* Updated dependencies to latest compatible versions: chrome-har 1.2.1, selenium-webdriver 4.43.0, execa 9.6.1, jimp 1.6.1 [#2437](https://github.com/sitespeedio/browsertime/pull/2437).
+* Firefox 149 in the Docker container [#2375](https://github.com/sitespeedio/browsertime/pull/2375).
+* Record the full Chrome/Edge configuration browsertime applied to the browser (args, preferences, mobile emulation, binary path, extensions count) under `info.browser` in the result JSON, not just what the user passed via `--chrome.args` [#2447](https://github.com/sitespeedio/browsertime/pull/2447).
+* Record Firefox preferences and the resolved binary path under `info.browser` in the result JSON [#2448](https://github.com/sitespeedio/browsertime/pull/2448).
+* Write long-task ranges and user-timing marks/measures into the HAR under `pages[].pageTimings` as `_longTasks` (array of `[startMs, endMs]` tuples) and `_userTimings` (object keyed by entry name → startTime), so downstream waterfall viewers can show what the browser was doing between requests [#2449](https://github.com/sitespeedio/browsertime/pull/2449).
+* Added modern device profiles to the mobile emulation device list [#2446](https://github.com/sitespeedio/browsertime/pull/2446).
+
+### Fixed
+* Pin the iOS Safari tab being measured so unrelated open tabs cannot clobber the active inspector target. The WebDriver tab is navigated to a sentinel URL and identified by it before iWDP messages are processed, otherwise an unrelated `Target.targetCreated` event could leave the HAR empty [#2440](https://github.com/sitespeedio/browsertime/pull/2440).
+* Fixed `drawtext` failing on ffmpeg 8 by quoting font paths and forwarding ffmpeg stderr so font/filter errors are visible [#2435](https://github.com/sitespeedio/browsertime/pull/2435).
+* Fixed Firefox network idle timeout on repeated iterations. The WebSocket message listener was never removed between iterations, causing the inflight counter to go negative [#2391](https://github.com/sitespeedio/browsertime/pull/2391).
+* Fixed Firefox network idle timeout when no network events arrive. Timestamps were initialized as undefined causing the idle check to never trigger [#2394](https://github.com/sitespeedio/browsertime/pull/2394).
+* Fixed intermittent crash when setting orange background before document.body exists on Edge/Windows [#2393](https://github.com/sitespeedio/browsertime/pull/2393).
+* Element interaction error messages now include the current page URL for easier debugging [#2385](https://github.com/sitespeedio/browsertime/pull/2385).
+* Added `actions.clear()` after `perform()` in all mouse commands to prevent pointer/key state leaking between actions [#2406](https://github.com/sitespeedio/browsertime/pull/2406).
+* Standardized error handling in all command `run()` methods using `executeCommand` with URL context. Fixed typo in select.deselectById and removed dead code in wait [#2410](https://github.com/sitespeedio/browsertime/pull/2410).
+* Added clear error message when loading TypeScript scripts on Node.js older than 22.18.0 [#2404](https://github.com/sitespeedio/browsertime/pull/2404).
+* Disabled the "You can zoom in and out" popup on Android [#2378](https://github.com/sitespeedio/browsertime/pull/2378).
+* Warn when `--viewPort` is set with a width below 500px on desktop Chrome. Chrome enforces a hard ~500px minimum window width and silently clamps narrower requests, but browsertime kept recording the filmstrip and video at the requested size, leaving captures cropped. The warning points users at mobile emulation, which lays out at the requested size while the OS window stays desktop-sized [#2445](https://github.com/sitespeedio/browsertime/pull/2445).
+* Stop a perceptual SSIM failure from discarding every other visual metric for the iteration. `calculate_perceptual_speed_index` now returns `(None, None)` on internal errors instead of letting the exception propagate up through `calculate_visual_metrics`, so SpeedIndex, FCP, LCP and the rest still flow through when SSIM can't run [#2444](https://github.com/sitespeedio/browsertime/pull/2444).
+* Drain ffmpeg/ffprobe stderr after the process exits in `visualmetrics-portable.py`. The previous Popen+poll loop dropped output buffered between the last read and exit — silently losing `keep pts:` lines and therefore filmstrip frames — and could deadlock when ffmpeg's debug output filled the OS pipe buffer [#2443](https://github.com/sitespeedio/browsertime/pull/2443).
+* Converted `visualmetrics-portable.py` path handling to `pathlib` for consistent cross-platform behaviour [#2442](https://github.com/sitespeedio/browsertime/pull/2442).
+
+## 26.3.2 - 2026-01-24
+### Fixed
+* Hello the new and fixed bidi-har 0.0.22 that fixes the response body [#2361](https://github.com/sitespeedio/browsertime/pull/2361).
+
+
 ## 26.3.1 - 2026-01-11
 ### Fixed
-* Reverting back to bidi-har 0.0.18. There where error/failures either in bidi har or in combination with browsertime in the latest release [#2360](https://github.com/sitespeedio/browsertime/pull/2360)
-
+* Reverting back to bidi-har 0.0.18. There where error/failures either in bidi har or in combination with browsertime in the latest release [#2360](https://github.com/sitespeedio/browsertime/pull/2360).
 
 ## 26.3.0 - 2026-01-09
 

package/README.md

@@ -157,7 +157,7 @@ The default video will include a timer and showing when the metrics happens, but
 
 
 ## Browser Support
-Browsertime supports Firefox, Chrome, and Edge (Chromium version) on desktop and Safari on Mac OS. On Android we support Chrome and Firefox. Safari on iOS has limited support: there's no HAR file and no visual metrics. You can also use the Safari simulator on Mac OS.
+Browsertime supports Firefox, Chrome, and Edge (Chromium version) on desktop and Safari on Mac OS. On Android we support Chrome and Firefox. Safari on iOS supports HAR (via `ios_webkit_debug_proxy`) and video / visual metrics (via screen capture over USB). You can also use the Safari simulator on Mac OS.
 
 ## How does it work
 Browsertime uses Selenium NodeJS to drive the browser. It starts the browser, load a URL, executes configurable Javascripts to collect metrics, collect a HAR file.

package/browserscripts/timings/softNavigations.js

@@ -0,0 +1,94 @@
+(function () {
+  const supported = PerformanceObserver.supportedEntryTypes;
+  if (!supported || supported.indexOf('soft-navigation') === -1) {
+    return;
+  }
+  var startIndex = window.__bt_softNavCount || 0;
+  const allNew = performance.getEntriesByType('soft-navigation').slice(startIndex);
+  if (allNew.length === 0) {
+    return;
+  }
+  // Use the last entry — a single user interaction can trigger
+  // multiple intermediate soft navigations (e.g. React, Turbo)
+  const entry = allNew[allNew.length - 1];
+  var navId = entry.navigationId;
+
+  // CLS for this soft navigation
+  var cls = 0;
+  if (supported.indexOf('layout-shift') !== -1) {
+    const observer = new PerformanceObserver(list => {});
+    observer.observe({type: 'layout-shift', buffered: true});
+    const shifts = observer.takeRecords().filter(function (s) {
+      return s.navigationId === navId;
+    });
+    var max = 0;
+    var curr = 0;
+    var firstTs = Number.NEGATIVE_INFINITY;
+    var prevTs = Number.NEGATIVE_INFINITY;
+    for (let s of shifts) {
+      if (s.hadRecentInput) continue;
+      if (s.startTime - firstTs > 5000 || s.startTime - prevTs > 1000) {
+        firstTs = s.startTime;
+        curr = 0;
+      }
+      prevTs = s.startTime;
+      curr += s.value;
+      max = Math.max(max, curr);
+    }
+    cls = max;
+  }
+
+  // INP for this soft navigation
+  var inp = 0;
+  if (supported.indexOf('event') !== -1) {
+    const observer = new PerformanceObserver(list => {});
+    observer.observe({type: 'event', buffered: true});
+    const events = observer.takeRecords().filter(function (e) {
+      return e.navigationId === navId && e.interactionId;
+    });
+    const MAX_INTERACTIONS = 10;
+    const longestList = [];
+    const longestMap = {};
+    for (let e of events) {
+      var minLongest = longestList[longestList.length - 1];
+      var existing = longestMap[e.interactionId];
+      if (existing || longestList.length < MAX_INTERACTIONS || e.duration > minLongest.latency) {
+        if (existing) {
+          existing.latency = Math.max(existing.latency, e.duration);
+        } else {
+          var interaction = { id: e.interactionId, latency: e.duration };
+          longestMap[interaction.id] = interaction;
+          longestList.push(interaction);
+        }
+        longestList.sort(function (a, b) { return b.latency - a.latency; });
+        longestList.splice(MAX_INTERACTIONS).forEach(function (i) { delete longestMap[i.id]; });
+      }
+    }
+    var inpEntry = longestList[longestList.length - 1];
+    inp = inpEntry ? inpEntry.latency : 0;
+  }
+
+  // LCP value
+  var lcp = 0;
+  if (entry.largestInteractionContentfulPaint) {
+    lcp = typeof entry.largestInteractionContentfulPaint === 'number'
+      ? entry.largestInteractionContentfulPaint
+      : entry.largestInteractionContentfulPaint.renderTime ||
+        entry.largestInteractionContentfulPaint.loadTime ||
+        entry.largestInteractionContentfulPaint.startTime || 0;
+  }
+
+  return [{
+    name: entry.name,
+    navigationId: navId,
+    interactionId: entry.interactionId,
+    startTime: Number(entry.startTime.toFixed(0)),
+    duration: Number(entry.duration.toFixed(0)),
+    firstContentfulPaint: entry.presentationTime
+      ? Number(entry.presentationTime.toFixed(0))
+      : 0,
+    largestInteractionContentfulPaint: Number(lcp.toFixed(0)),
+    cumulativeLayoutShift: cls,
+    interactionToNextPaint: inp
+  }];
+})();

package/lib/chrome/har.js

@@ -23,6 +23,32 @@ export async function getHar(
   const logs = await runner.getLogs(Type.PERFORMANCE);
   const messages = logs.map(entry => JSON.parse(entry.message).message);
 
+  // Inject a SoftNavigation.detected event so chrome-har renames the
+  // current HAR page with the soft navigation URL. The PerformanceObserver
+  // API is the only reliable source that confirms all three soft navigation
+  // criteria (user interaction + URL change + visible paint).
+  try {
+    const softNavEntries = await runner.runScript(
+      `const supported = PerformanceObserver.supportedEntryTypes;
+       if (!supported || supported.indexOf('soft-navigation') === -1) return [];
+       const startIndex = window.__bt_softNavCount || 0;
+       const entries = performance.getEntriesByType('soft-navigation').slice(startIndex);
+       if (entries.length === 0) return [];
+       const last = entries[entries.length - 1];
+       return [{ url: last.name, startTime: last.startTime }];`,
+      'GET_SOFT_NAVIGATIONS_FOR_HAR'
+    );
+    if (softNavEntries && softNavEntries.length > 0) {
+      const entry = softNavEntries[0];
+      messages.push({
+        method: 'SoftNavigation.detected',
+        params: { url: entry.url, startTime: entry.startTime }
+      });
+    }
+  } catch {
+    // Soft navigations not supported, ignore
+  }
+
   if (logPerfEntries) {
     if (!result.extraJson) {
       result.extraJson = {};
@@ -68,15 +94,20 @@ export async function getHar(
   }
 
   if (har.log.pages.length > 0) {
-    har.log.pages[0].title = `${result.url} run ${index}`;
+    const page = har.log.pages[0];
+    // For soft navigations, use the soft navigation URL as the title
+    const pageUrl = page._softNavigation ? page.title : result.url;
+    page.title = `${pageUrl} run ${index}`;
     // Hack to add the URL from a SPA
-    if (result.alias && !aliasAndUrl[result.alias]) {
+    if (page._softNavigation) {
+      page._url = pageUrl;
+    } else if (result.alias && !aliasAndUrl[result.alias]) {
       aliasAndUrl[result.alias] = result.url;
-      har.log.pages[0]._url = result.url;
+      page._url = result.url;
     } else if (result.alias && aliasAndUrl[result.alias]) {
-      har.log.pages[0]._url = aliasAndUrl[result.alias];
+      page._url = aliasAndUrl[result.alias];
     } else {
-      har.log.pages[0]._url = result.url;
+      page._url = result.url;
     }
   }
   return har;

package/lib/chrome/settings/chromeAndroidOptions.js

@@ -26,5 +26,6 @@ export const chromeAndroidOptions = [
   '--disable-breakpad',
   '--dont-require-litepage-redirect-infobar',
   '--override-https-image-compression-infobar',
-  '--disable-fetching-hints-at-navigation-start'
+  '--disable-fetching-hints-at-navigation-start',
+  '--propagate-iph-for-testing'
 ];

package/lib/chrome/webdriver/chromium.js

@@ -420,6 +420,45 @@ export class Chromium {
       result.renderBlocking.requests = render.renderBlockingInfo;
     }
 
+    // If a soft navigation was detected, promote its metrics to the
+    // standard locations so they flow through googleWebVitals, logging,
+    // and statistics just like regular page load metrics.
+    if (
+      result.browserScripts.timings &&
+      result.browserScripts.timings.softNavigations &&
+      result.browserScripts.timings.softNavigations.length > 0
+    ) {
+      const softNav = result.browserScripts.timings.softNavigations.at(-1);
+      const navStart = softNav.startTime;
+
+      if (softNav.firstContentfulPaint) {
+        result.browserScripts.timings.paintTiming =
+          result.browserScripts.timings.paintTiming || {};
+        result.browserScripts.timings.paintTiming['first-contentful-paint'] =
+          softNav.firstContentfulPaint - navStart;
+      }
+
+      if (softNav.largestInteractionContentfulPaint > 0) {
+        result.browserScripts.timings.largestContentfulPaint = {
+          renderTime: Math.max(
+            0,
+            softNav.largestInteractionContentfulPaint - navStart
+          )
+        };
+      }
+
+      if (softNav.cumulativeLayoutShift !== undefined) {
+        result.browserScripts.pageinfo = result.browserScripts.pageinfo || {};
+        result.browserScripts.pageinfo.cumulativeLayoutShift =
+          softNav.cumulativeLayoutShift;
+      }
+
+      if (softNav.interactionToNextPaint) {
+        result.browserScripts.timings.interactionToNextPaint =
+          softNav.interactionToNextPaint;
+      }
+    }
+
     // Google Web Vitals hacksery
     result.googleWebVitals = {};
     if (result.browserScripts.pageinfo) {

package/lib/chrome/webdriver/setupChromiumOptions.js

@@ -19,6 +19,8 @@ const CHROME_AMD_EDGE_INTERNAL_PHONE_HOME = [
   'MAP optimizationguide-pa.googleapis.com 127.0.0.1'
 ];
 
+const CHROME_FEATURES_THAT_WE_ENABLE = ['SoftNavigationHeuristics'];
+
 const CHROME_FEATURES_THAT_WE_DISABLES = [
   'AutofillServerCommunication',
   'CalculateNativeWinOcclusion',
@@ -43,10 +45,36 @@ export function setupChromiumOptions(
   options,
   baseDir
 ) {
+  // Record every argument / preference / capability we apply to the browser
+  // so it can be surfaced in the result JSON for debugging — issue #1622.
+  // Stored on `options` because both Chrome and Edge call this and both end
+  // up needing it later in the engine for `result.info.browser`.
+  const recorded = {
+    args: [],
+    preferences: {},
+    mobileEmulation: undefined,
+    binaryPath: undefined,
+    extensions: 0
+  };
+  options.recordedBrowserSettings = recorded;
+
+  const addArgs = arg => {
+    seleniumOptions.addArguments(arg);
+    if (Array.isArray(arg)) {
+      recorded.args.push(...arg);
+    } else {
+      recorded.args.push(arg);
+    }
+  };
+  const setPrefs = prefs => {
+    seleniumOptions.setUserPreferences(prefs);
+    Object.assign(recorded.preferences, prefs);
+  };
+
   // Fixing save password popup, only on Desktop
 
   if (!isAndroidConfigured(options)) {
-    seleniumOptions.setUserPreferences({
+    setPrefs({
       'profile.password_manager_enable': false,
       'profile.default_content_setting_values.notifications': 2,
       credentials_enable_service: false
@@ -54,28 +82,50 @@ export function setupChromiumOptions(
   }
 
   if (options.headless) {
-    seleniumOptions.addArguments('--headless=new');
+    addArgs('--headless=new');
   }
 
   // If we run in Docker we need to always use no-sandbox
   if (options.docker) {
-    seleniumOptions.addArguments('--no-sandbox');
-    seleniumOptions.addArguments('--disable-setuid-sandbox');
+    addArgs('--no-sandbox');
+    addArgs('--disable-setuid-sandbox');
   }
 
   if (options.xvfb && (options.xvfb === true || options.xvfb === 'true')) {
-    seleniumOptions.addArguments('--disable-gpu');
+    addArgs('--disable-gpu');
   }
 
-  seleniumOptions.addArguments(
-    '--disable-features=' + CHROME_FEATURES_THAT_WE_DISABLES.join(',')
-  );
+  addArgs('--disable-features=' + CHROME_FEATURES_THAT_WE_DISABLES.join(','));
+
+  addArgs('--enable-features=' + CHROME_FEATURES_THAT_WE_ENABLE.join(','));
 
   const viewPort = getViewPort(options);
   // If viewport is defined (only on desktop) then set start args
   if (viewPort) {
-    seleniumOptions.addArguments('--window-position=0,0');
-    seleniumOptions.addArguments('--window-size=' + viewPort.replace('x', ','));
+    addArgs('--window-position=0,0');
+    addArgs('--window-size=' + viewPort.replace('x', ','));
+
+    // Desktop Chrome enforces a minimum window width (~500px) regardless of
+    // --window-size, so a request like --viewPort 360x640 silently becomes
+    // 500x640. The video and filmstrips are still cropped to the requested
+    // size, which is why they look chopped. Mobile emulation is the supported
+    // way to test smaller viewports — it tells the renderer to lay out at
+    // the requested size while the OS window can stay desktop-sized.
+    // See https://github.com/sitespeedio/browsertime/issues/1222
+    const usingEmulation =
+      browserOptions.mobileEmulation &&
+      (browserOptions.mobileEmulation.deviceName ||
+        (browserOptions.mobileEmulation.width &&
+          browserOptions.mobileEmulation.height));
+    if (!usingEmulation) {
+      const [w] = viewPort.split('x').map(Number);
+      if (w && w < 500) {
+        log.warn(
+          'Requested viewport %s — desktop Chrome enforces a minimum window width of about 500px and will silently use a wider window. The video, filmstrip and screenshots will be cropped because they are sized to the requested viewport. To test smaller viewports, use Chrome mobile emulation: --chrome.mobileEmulation.deviceName "iPhone X" (or set --chrome.mobileEmulation.width and --chrome.mobileEmulation.height).',
+          viewPort
+        );
+      }
+    }
   }
 
   // If we are recording responses and we also block on domain
@@ -92,10 +142,10 @@ export function setupChromiumOptions(
     }
     excludes += ' EXCLUDE localhost';
 
-    seleniumOptions.addArguments('--host-resolver-rules=' + excludes);
+    addArgs('--host-resolver-rules=' + excludes);
   } // If we are replaying with WebPageReplay
   else if (browserOptions.webPageReplayHostResolver) {
-    seleniumOptions.addArguments(
+    addArgs(
       `--host-resolver-rules= "MAP *:80 127.0.0.1:${browserOptions.webPageReplayHTTPPort},  MAP *:443 127.0.0.1:${browserOptions.webPageReplayHTTPSPort}, EXCLUDE localhost"`
     );
   } // If we do not use WebPageReplay but wanna block on domain
@@ -105,7 +155,7 @@ export function setupChromiumOptions(
     for (let domain of excludesDomains) {
       excludes += 'MAP * 127.0.0.1, EXCLUDE ' + domain + ',';
     }
-    seleniumOptions.addArguments('--host-resolver-rules=' + excludes);
+    addArgs('--host-resolver-rules=' + excludes);
   } else {
     // Make sure we only set this if we do not have any other host resolver rules
     const chromeCommandLineArguments = toArray(browserOptions.args);
@@ -113,7 +163,7 @@ export function setupChromiumOptions(
       argument => argument.includes('host-resolver-rules')
     );
     if (argumentsWithHostResolverRules.length === 0) {
-      seleniumOptions.addArguments(
+      addArgs(
         `--host-resolver-rules="${CHROME_AMD_EDGE_INTERNAL_PHONE_HOME.join(
           ','
         )}"`
@@ -129,51 +179,48 @@ export function setupChromiumOptions(
       seleniumOptions.addExtensions(
         readFileSync(extension, { encoding: 'base64' })
       );
+      recorded.extensions += 1;
     }
   }
 
   if (options.debug) {
-    seleniumOptions.addArguments('--auto-open-devtools-for-tabs');
+    addArgs('--auto-open-devtools-for-tabs');
   }
 
   const perfLogConfig = { enableNetwork: true, enablePage: true };
   seleniumOptions.setPerfLoggingPrefs(perfLogConfig);
 
   if (options.userAgent) {
-    seleniumOptions.addArguments('--user-agent=' + options.userAgent);
+    addArgs('--user-agent=' + options.userAgent);
   }
 
   if (browserOptions.ignoreCertificateErrors) {
-    seleniumOptions.addArguments('--ignore-certificate-errors');
+    addArgs('--ignore-certificate-errors');
   }
 
   if (browserOptions.collectNetLog) {
     const dir = isAndroidConfigured(browserOptions)
       ? '/data/local/tmp'
       : baseDir;
-    seleniumOptions.addArguments(`--log-net-log=${dir}/chromeNetlog.json`);
+    addArgs(`--log-net-log=${dir}/chromeNetlog.json`);
     const level = browserOptions.netLogCaptureMode || 'IncludeSensitive';
-    seleniumOptions.addArguments(`--net-log-capture-mode=${level}`);
+    addArgs(`--net-log-capture-mode=${level}`);
   }
 
   if (browserOptions.android) {
-    seleniumOptions.addArguments(defaultAndroidChromeOptions);
-    seleniumOptions.addArguments(
-      '--remote-debugging-port=' + options.devToolsPort
-    );
+    addArgs(defaultAndroidChromeOptions);
+    addArgs('--remote-debugging-port=' + options.devToolsPort);
   } else {
     if (browserOptions.noDefaultOptions) {
       log.info('Skip setting default options for Chrome');
     } else {
-      seleniumOptions.addArguments(defaultChromeOptions);
-      seleniumOptions.addArguments(
-        '--remote-debugging-port=' + options.devToolsPort
-      );
+      addArgs(defaultChromeOptions);
+      addArgs('--remote-debugging-port=' + options.devToolsPort);
     }
   }
 
   if (browserOptions.enableVideoAutoplay) {
-    seleniumOptions.addArguments('--autoplay-policy=no-user-gesture-required');
+    addArgs('--autoplay-policy=no-user-gesture-required');
   }
 
   // It's a new splash screen introduced in Chrome 98
@@ -186,23 +233,31 @@ export function setupChromiumOptions(
         argument.includes('disable-features') &&
         !argument.includes('ChromeWhatsNewUI')
       ) {
-        seleniumOptions.addArguments(`${argument},ChromeWhatsNewUI`);
+        addArgs(`${argument},ChromeWhatsNewUI`);
         log.debug('Set Chrome args %j', `${argument},ChromeWhatsNewUI`);
+      } else if (
+        argument.includes('enable-features') &&
+        !argument.includes('SoftNavigationHeuristics')
+      ) {
+        addArgs(`${argument},SoftNavigationHeuristics`);
+        log.debug('Set Chrome args %j', `${argument},SoftNavigationHeuristics`);
       } else {
-        seleniumOptions.addArguments(argument);
+        addArgs(argument);
         log.debug('Set Chrome args %j', argument);
       }
     }
   } else {
-    seleniumOptions.addArguments('--disable-features=ChromeWhatsNewUI');
+    addArgs('--disable-features=ChromeWhatsNewUI');
   }
 
   if (browserOptions.binaryPath) {
     seleniumOptions.setChromeBinaryPath(browserOptions.binaryPath);
+    recorded.binaryPath = browserOptions.binaryPath;
   }
 
   if (browserOptions.mobileEmulation) {
     seleniumOptions.setMobileEmulation(browserOptions.mobileEmulation);
+    recorded.mobileEmulation = browserOptions.mobileEmulation;
   }
 
   // See https://bugs.chromium.org/p/chromium/issues/detail?id=818483