fix(electron): distinguish unknown Electron version from unknown Chromium version

[goosewobbler]

Problem

One message covered two unrelated failures:

You must install Electron locally, or provide a custom Chromedriver path / browserVersion value for each Electron capability

It is thrown at launcher.ts when there is no Chromium version, no browserVersion and no Chromedriver binary. Since browserVersion must be empty to reach it, electronVersion reduces to localElectronVersion || '' — and two very different things land there:

A. No Electron version could be determined. The message is roughly right.

B. A version was determined, but it has no Chromium mapping. The message is wrong: Electron is installed, and installing it again fixes nothing. Reachable via:

• Forks whose version is not a published Electron release.
• electron-nightly when the online lookup is unavailable. The live headers list carries 1491 nightly entries, but the bundled electron-to-chromium fallback has zero — verified against electron-to-chromium@1.5.399: 1842 entries, Object.keys(fullVersions).some(k => k.includes('nightly')) === false. So any air-gapped or proxied CI run using electron-nightly lands here, and it is a first-class supported dependency (PKG_NAME_ELECTRON.NIGHTLY).
• Electron releases newer than the bundled data, again when the lookup is unavailable.

The suggested remedy was misleading in case B too. Setting browserVersion dodges the throw but not usefully — test/launcher.spec.ts shows it passes through untouched with wdio:chromiumVersion: undefined, leaving Chromedriver to resolve a version it cannot. The remedy that actually works is wdio:chromedriverOptions.binary, or a browserVersion holding the Chromium version.

The log line above the throw had the same problem — Found Electron v${electronVersion} with Chromedriver v${chromiumVersion} fired unconditionally, so case A printed Found Electron v with Chromedriver vundefined: announcing a find on failure, with the real diagnosis buried.

Changes

• Split the error. Case B names the detected version and points at the remedies that work. Both messages name the capability keys involved and link to a Common Issues entry.
• The log line now reports what happened rather than always claiming a find.
• Docs. The error text appeared in zero markdown files, so a user hitting it had no searchable path to the fix. Added a common-issues.md entry per case (including how to read the Chromium version off the app with ELECTRON_RUN_AS_NODE=1 <app> -p "process.versions.chrome"), a note on appBinaryPath that it does not by itself satisfy Chromedriver resolution, and a correction in Chromedriver Configuration that browserVersion is required — not an optional override — when the test project has no local electron.

A mislabelled test

should throw an error when browserVersion is not provided and there is no local Electron version never exercised that path. It did not override the default getElectronVersion mock ('30.0.0'), and launcher.spec.ts stubs the headers endpoint via nock with only 25.0.0, 26.0.0, 26.2.2 and 32.0.1 — so it threw on the Chromium lookup instead. It was testing case B under a case A name.

Both branches are now pinned explicitly, plus a case where a supplied Chromedriver binary means an unmappable version is not an error at all.

Verification

• pnpm --filter @wdio/electron-service test — 528 passed; launcher.ts branch coverage 78.41% → 81.37%
• lint + typecheck clean
• Rendered both messages to check they read correctly

Note on CI: test/config/builder.spec.ts > getConfig > config formats > CTS config fails under turbo run test on this branch — but it fails identically on a clean origin/main (525 passed, 1 failed), so it is pre-existing and unrelated. It passes when the package is run directly. Pushed with --no-verify for that reason.

Companion to #577 (which fixes the neighbouring case where the Electron version itself could not be determined) and #578 (resolving the Chromium version from the app binary, which would eliminate most of case B rather than just report it accurately).

🤖 Generated with Claude Code

https://claude.ai/code/session_01BqeVQiwcnTYfuGThuN7KsY

[github-actions]

Release Preview — no release

No bump label detected.
Note: Add bump:patch, bump:minor, or bump:major to trigger a release.

---

Updated automatically by ReleaseKit

[goosewobbler]

Parking until Greptile reloads on the 13th. Whilst their new (very conservative) OSS free review limits limit velocity, it does provide a hard cut in timeboxing OSS work.