feat(@wdio/utils): download Chromedriver from Electron releases

[goosewobbler]

Proposed changes

Rebuilt on v10 from the closed upstream draft webdriverio/webdriverio#15015. It addresses webdriverio/webdriverio#14986.

@wdio/utils can now download Chromedriver from Electron releases, for Electron apps and for Linux ARM64. Chrome for Testing (CfT) only ships a linux-arm64 Chromedriver from Chrome 153.0.8001.0. For older builds, @puppeteer/browsers downloads the x64 (linux64) archive, which can't run on arm64. Those builds now get the Chromedriver of an Electron release with the same Chromium major instead. This also enables a general CfT fallback whereby a matching Electron release is used if a CfT download fails.

Changes

• Electron release provider: ElectronChromedriverProvider downloads an Electron release's Chromedriver, including nightlies from electron/nightlies. getElectronVersionForChromium maps a Chrome version to the last Electron release with the same Chromium major, using electron-to-chromium; Chromedriver only checks the major.
• wdio:electronVersion: downloads that release's Chromedriver for an Electron app set as goog:chromeOptions.binary, without running the app to read its Chrome version. It only ever holds an Electron version: from fix(electron): correct how the Electron version is passed to WebdriverIO webdriverio/desktop-mobile#693 on, the Electron service sets it only for known releases.
• Linux ARM64: Chrome below 153.0.8001.0 goes straight to the matching Electron release.
• Chrome for Testing outages: when a CfT download fails, on any platform, setup falls back to the matching Electron release. If that fails too, the CfT error is reported.
• Docs: a new "Chromedriver on ARM64" guide, wdio:electronVersion in Capabilities, and where Chromedriver comes from in Driver Binaries.
• CI: test:e2e:chromedriver runs the testrunner on ubuntu-24.04-arm, macos-15 and windows-latest when the Chromedriver setup files change. It uses a Chromium 130 binary, Playwright 1.48.2's pinned build. One spec sets wdio:electronVersion 33.2.1 on every platform; on Linux ARM64, another gets Electron 33.4.11's driver through the fallback.
• Refactor: the nested ternaries in setupPuppeteerBrowser become getPuppeteerBrowser and locateInstalledBrowser.

Source selection

Scenario	Chromedriver source
x64, macOS, Windows 11 on Arm	Chrome for Testing (unchanged)
Linux ARM64, Chrome 153.0.8001.0 or later	Chrome for Testing (linux-arm64)
Linux ARM64, older Chrome	The last Electron release with the same Chromium major
Linux ARM64, older Chrome in a major no Electron release shipped (such as 145)	None: an error that links the ARM64 guide
wdio:electronVersion set	That Electron release, or Chrome for Testing with browserVersion if it can't be downloaded
wdio:electronVersion and browserVersion set, with CHROMEDRIVER_CDNURL	The mirror, as before
Chrome for Testing download fails	The last Electron release with the same Chromium major
Chrome for Testing download fails, with CHROMEDRIVER_CDNURL set	None: the mirror's error, as before

Example

{
    browserName: 'chrome',
    'wdio:electronVersion': '33.2.1',
    // a BiDi session replaces the app's window with `data:,`
    'wdio:enforceWebDriverClassic': true,
    'goog:chromeOptions': {
        binary: './out/my-app-darwin-arm64/my-app.app/Contents/MacOS/my-app'
    }
}

How you tested

• Unit tests for the touched package(s): npx vitest --config vitest.config.ts --run packages/wdio-utils and tsc --noEmit for @wdio/utils, at each commit
• Type definition tests (if the public API / command types changed): run-p test:typings:*
• Smoke or e2e (only if the testrunner, launcher, or a real browser path changed):
  • pnpm run test:e2e:chromedriver passes in CI on ubuntu-24.04-arm (both specs), macos-15 and windows-latest.
  • setupChromedriver run from source in a node:24 container, checking each installed driver with file and chromedriver --version. The results are below; "CfT blocked" points storage.googleapis.com at localhost.
  • docs:check --skip-build-checks passes.

Input (linux/arm64 unless stated)	Result
Chrome 130.0.6723.58	Electron 33.4.11's ChromeDriver 130.0.6723.191, ARM aarch64
Chrome 131.0.6778.85	Electron 34.0.0-alpha.1's ChromeDriver 131.0.6776.0
stable	CfT linux-arm64 ChromeDriver 154.0.8037.92
Chrome 145.0.7632.117	The documented error
wdio:electronVersion 34.0.0-beta.9	ChromeDriver 132.0.6834.32; a second run reused the cache
wdio:electronVersion 36.0.0-nightly.20250303	ChromeDriver 135.0.7041.2 from electron/nightlies
wdio:electronVersion 33.2.1+wvcus, Chrome 130.0.6723.137	A warning, then CfT's Chrome 130 driver
CfT blocked, stable	Electron 45.0.0-alpha.3's ChromeDriver 154.0.8029.0, ARM aarch64
CfT blocked, Chrome 152, linux/amd64	Electron 44.4.5's ChromeDriver 152.0.7977.130, x86-64

Types of changes

• Polish (an improvement for an existing feature)
• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (improvements to the project's docs)
• Specification changes (updates to WebDriver command specifications)
• Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)
• I have added proper type definitions for new commands (if appropriate)

🤖 Generated with Claude Code

[goosewobbler]

Superseded by webdriverio#15871.