feat: @wdio/electrobun-service — Electrobun desktop testing support

[goosewobbler]

Aggregate / integration PR for the new @wdio/electrobun-service (ROADMAP Phase 5) — the combined 5-PR stack on feat/electrobun-service, held for final review before merging to main.

Electrobun is a CDP-attach service (like Electron): the launcher spawns the CEF-rendered app and the worker drives it over the Chrome DevTools Protocol via Chromedriver debuggerAddress, with @wdio/electrobun-cdp-bridge as a multi-target side-channel. The Phase 0 spike validated the approach on macOS (agent-os/specs/20260528-electrobun-service/RESEARCH_FINDINGS.md).

Status

All five phases are merged into this feature branch (the stack is complete). A couple of small post-merge tweaks landed directly on the branch (Node engines → >=22.12.0, a skill docs correction). CI is being verified on the feature branch; this PR is held for final review — it is not auto-merged to main.

⚠️ Ships pre-1.0 (0.1.0), macOS-only

Driving the E2Es on CI (PR4) surfaced a hard upstream CEF constraint: BrowserWindow forces every window onto a persist:default partition, which CEF's chrome-runtime can't create (root_cache_path is hard-fixed, no override), so CEF falls back to a global browser context. macOS recovers (still serves /json → Chromedriver attaches); Linux/Windows do not (the fallback serves no /json; Linux additionally has remote_debugging_port commented out). This lives in electrobun's prebuilt native lib — not fixable from the service.

So the service ships 0.1.0 (pre-1.0), macOS-only. 0.x because upstream blocks a large part of the convergent surface; 1.0 is reserved for full parity once the gaps fill (minor bumps as each lands).

Phased stack

Phase	PR	Status
1 — Foundation (skeletons + native-types wiring)	#310	✅ merged
2 — MVP (multi-target CDP bridge, native launcher, execute)	#311	✅ merged
3 — Feature-complete (mocking, deeplink, browser mode, fixtures)	#312	✅ merged
4 — E2E (CEF fixture CI build + specs + wdio conf + headless)	#316	✅ merged
5 — Ship (0.1.0, macOS guard, docs, package-test CI, release pipeline)	#318	✅ merged

What ships in 0.1.0 (macOS)

execute, mocking (mock + clear/reset/restoreAllMocks + isMockFunction), frontend + backend log capture, browser mode, standalone/session mode, headless — all validated by unit tests, package-install smoke, 3-OS unit/build-tooling, and the macOS single-window E2E (standard suite). A runtime SevereServiceError fails fast on Linux/Windows native mode (framed around the CEF renderer; browser mode still works cross-platform).

Known limitations (upstream-blocked — the "Framework gaps")

Area	Status	Cause
Linux / Windows (any feature)	blocked (guarded)	CEF serves no /json there (failed-profile fallback; Linux port commented out)
multiremote / parallel workers	blocked	CEF can't isolate ≥2 instances per root_cache_path
switchWindow/listWindows (multi-window)	API complete, unreliable even on macOS	2-window global-context race
triggerDeeplink (macOS)	unreliable	no open-url routing to the spawned/cloned instance
emitEvent	deferred	Bun event bus isn't CDP-reachable (RPC-routable but complex)
mockAll / class-mock	N/A	Electron-additive; no enumerable main-process API

The blocked/unreliable specs are retained with NOT-RUN-IN-CI notes (runnable locally via TEST_TYPE=…). The macOS standard e2e gate is intermittently flaky from the same upstream CEF race ("Timeout of new browser info" / unpainted #app-title); mitigated with a staggered 2-window fixture + specFileRetries: 3. Occasional re-runs expected until the upstream fix lands.

Follow-ups

• Non-CEF (native-renderer) support — Electrobun: support non-CEF (native-renderer) apps to fill the Linux/Windows gaps #317: fill the Linux/Windows gaps via WebView2 (CDP, likely service-side) / WebKitGTK (W3C WebDriver, needs upstream). macOS stays CEF. Part of the road to 1.0.
• Upstream CEF umbrella issue — filed post-ship against blackboardsh/electrobun, linking the upstream's existing issues to the automation goal: profile isolation macOS CEF persistent partitions using custom request-context cache paths for cookies blackboardsh/electrobun#380 / CEF persistent partitions fail on macOS because profile path is nested under Partitions/ blackboardsh/electrobun#278 (closed) / CEF not work under linux blackboardsh/electrobun#448; remote-debugging opt-in Make CEF remote debugging opt-in blackboardsh/electrobun#445; prior E2E request Feature Request: E2E testing blackboardsh/electrobun#122 (closed); multi-window Tabs render blank after switching and crash on close in Multitab template (Wayland/CEF) | GLXBadWindow / Signal 11 blackboardsh/electrobun#281 / Multi-tab browser: only first URL load works, subsequent navigation and new tabs unresponsive blackboardsh/electrobun#253 / Feature request: Event or callback when <electrobun-webview> tag creates a BrowserView (for multi-tab RPC) blackboardsh/electrobun#155. (Fully-qualified cross-repo refs — these link to the electrobun repo, not this one.)

Notes for reviewers

• Review the individual phase PRs for focused diffs; this is the integration view.
• The recurring electron-forge no-binary / Windows-teardown CI reds are known-flaky and unrelated to this work (re-run clears them).

🤖 Generated with Claude Code

[github-actions]

Release Preview — no release

No bump label detected.
Reason: No release labels found (need bump:* or channel:stable)
Note: Add bump:patch, bump:minor, or bump:major to trigger a release.

---

Updated automatically by ReleaseKit

[greptile-apps]

Greptile Summary

This PR lands @wdio/electrobun-service (v0.1.0, macOS-only) and its companion @wdio/electrobun-cdp-bridge package into the monorepo — a CDP-attach WDIO service for testing Electrobun desktop apps over CEF's Chrome DevTools Protocol. It is the integration view of a 5-phase stack (phases 1–4 merged) that introduces the launcher, worker service, multi-target CDP bridge, mock layer, deeplink support, E2E fixtures, and CI workflows.

• CDP bridge (@wdio/electrobun-cdp-bridge): multi-target WebSocket client with per-target Connection, TargetRegistry for stable window labels, and retry-backed discovery
• Service layer (@wdio/electrobun-service): per-worker bundle cloning with APFS clonefile fast-path, build.json port-pinning, Runtime.evaluate-based execute/mock, syncWebDriverWindow alignment, and a standalone session API (init/cleanup)
• E2E & CI: macOS-only standard suite validated in CI with a CEF fixture app; Linux/Windows blocked by upstream CEF constraints and guarded accordingly

Confidence Score: 4/5

The service is well-structured and the core attach/teardown flow is sound; all findings are non-blocking improvements.

The implementation is thorough: bundle cloning with APFS fast-path, retry-backed CDP discovery, idempotent mock install, and proper per-worker cleanup. The findings are localised style and documentation issues plus a minor window-state edge case in the best-effort sync helper. Nothing here would cause silent data corruption or a broken run on the happy path.

packages/electrobun-service/src/service.ts (syncWebDriverWindow window-state edge case), packages/electrobun-service/src/mock.ts (Error stack asymmetry), packages/electrobun-service/src/electrobunConfig.ts (stale docstring)

Important Files Changed

Filename	Overview
packages/electrobun-service/src/launcher.ts	Launcher correctly clones the bundle per-worker, pins the CDP port into build.json, and waits for the CEF /json endpoint before setting debuggerAddress. The spawnApp seam, APFS fast-path fallback, and per-cid cleanup are well handled.
packages/electrobun-service/src/nativeMode.ts	Process management is sound: clone cleanup on pin failure, SIGTERM→SIGKILL grace window, and log handler teardown. The deliberate omission of --user-data-dir is well-documented inline. waitForCdpReady always resolves (with a warning on timeout).
packages/electrobun-service/src/service.ts	Worker service attaches the CDP bridge and installs browser.electrobun.*. syncWebDriverWindow is best-effort but can leave the browser on the last-tried handle when no match is found — could confuse test debugging in multi-window scenarios.
packages/electrobun-cdp-bridge/src/connection.ts	WebSocket lifecycle handling is correct: CONNECT_PROMISE_ID at 0, command IDs starting at 1, per-send timeouts, and double-close safety. The async on the message handler is unnecessary since #messageHandler is synchronous, but harmless.
packages/electrobun-cdp-bridge/src/bridge.ts	Multi-target bridge is well-structured: per-field ?? defaults fix the previously-undefined-timeout bug, #discover retry loop is bounded, and active-target auto-advance on window close is correctly handled.
packages/electrobun-service/src/mock.ts	Mock implementation is solid: idempotent install, one-way sync of call history, and proper clear/reset/restore delegation. Error serialization for mockRejectedValue does not include stack trace unlike the read-back path.
packages/electrobun-service/src/innerRecorder.ts	In-page spy factory and script builders are well-implemented with valid-target guard, pathLiteral escaping, and circular-reference protection in the read-back serializer.
packages/electrobun-service/src/electrobunConfig.ts	Bundle resolution and port-pinning are well-guarded. The writeRemoteDebuggingPort docstring describes a user-data-dir use case that conflicts with the explicit design decision in nativeMode.ts to never inject one.
packages/electrobun-service/src/session.ts	Standalone session init/cleanup is correctly sequenced — launcher tracked before service.before, cleaned up on both service.before failure and remote session failure.
packages/electrobun-cdp-bridge/src/targetRegistry.ts	URL-sorted label assignment and stable reconcile logic are correct. labelOrder returns NaN for unexpected label formats but labels are always 'main' or 'window-N' so this is unreachable in practice.

Sequence Diagram

sequenceDiagram
    participant LCI as CI Runner
    participant L as ElectrobunLaunchService (main)
    participant NM as nativeMode (cloneBundle / spawn)
    participant CEF as Electrobun App (CEF)
    participant W as ElectrobunWorkerService (worker)
    participant B as CdpBridge
    participant T as Test

    LCI->>L: onPrepare(caps)
    L->>L: resolveElectrobunApp + verifyCefRenderer
    L->>L: force browserName:'chrome'

    LCI->>L: onWorkerStart(cid, caps)
    L->>NM: spawnElectrobunApp(cloneBundle, pinPort)
    NM->>NM: cp -Rc bundle to tmp clone
    NM->>NM: writeRemoteDebuggingPort into build.json
    NM->>CEF: spawn clonedBinary
    NM-->>L: ElectrobunAppProcess
    L->>CEF: waitForCdpReady (poll /json)
    CEF-->>L: page target ready
    L->>L: set goog:chromeOptions.debuggerAddress

    LCI->>W: service.before(caps, browser)
    W->>B: new CdpBridge(host, port)
    B->>CEF: WebSocket connect
    B->>CEF: Runtime.enable
    W->>W: installApi + syncWebDriverWindow

    T->>W: browser.electrobun.execute(fn)
    W->>B: bridge.send(Runtime.evaluate)
    B->>CEF: CDP evaluate
    CEF-->>W: result

    T->>W: browser.electrobun.mock(target)
    W->>CEF: buildInstallScript via Runtime.evaluate
    W-->>T: ElectrobunMock

    LCI->>L: onWorkerEnd(cid)
    L->>NM: stopElectrobunApp SIGTERM/SIGKILL
    NM->>NM: rmSync cloneParentDir

    LCI->>W: service.after()
    W->>B: bridge.close()

Loading

_{Reviews (1): Last reviewed commit: "feat(electrobun): E2E suite + CI build/t..." | Re-trigger Greptile}