feat(electrobun): PR3 feature-complete — mocking, multiremote, deeplink, fixtures

[goosewobbler]

PR3 of the stack (Foundation → MVP → Feature-complete → E2E → Ship). Stacked on #311; GitHub retargets to the integration branch as the stack merges.

Brings @wdio/electrobun-service to the full standard surface (all real, not stubbed), validated by unit tests at the CdpBridge boundary. E2E (CI fixture build + specs) is split into the next PR so the beta-toolchain CEF-CI risk doesn't block this feature work or the eventual release.

What's in this PR

• triggerDeeplink (macOS) — fires the OS open <url> so the app's open-url handler receives it (@wdio/native-core deeplink helpers); non-macOS throws the documented-gap error.
• Multiremote — per-worker .app clone (APFS cp -Rc, cpSync fallback) + per-clone build.json port + distinct CFFIXED_USER_HOME, replacing the MVP's in-place mutation. Removes the single-instance limitation (no upstream change needed — empirically validated in the spike).
• Mocking — browser.electrobun.mock(target) + full lifecycle (mockImplementation/mockReturnValue/mockResolvedValue/mockRejectedValue/…Once/mockReturnThis/mockClear/mockReset/mockRestore) + clear/reset/restoreAllMocks + isMockFunction, over CDP. In-webview vitest-shaped recorder injected via Runtime.evaluate (never navigates), one-way update() sync — modeled on Electron's browser-mode mock; satisfies the ElectrobunMock types.
• Fixtures — fixtures/e2e-apps/electrobun (CEF all-OS, 2 windows, open-url, big-glass counter UI) + fixtures/package-tests/electrobun-app + workspace wiring.

Standard surface — now all real

execute, mocking, switchWindow/listWindows, triggerDeeplink (macOS), browser mode, standalone, multiremote. Documented gaps: emitEvent (Bun bus not CDP-reachable), mockAll/class-mock (Electron-only), Win/Linux deeplink (upstream).

Verification

• typecheck 10/10; 121 @wdio/electrobun-service + 18 @wdio/electrobun-cdp-bridge unit tests; Biome clean; no regressions (native-core, dioxus-service, native-types).
• E2E gap (by design): unit tests mock the CdpBridge boundary; the real in-webview round-trip (mock recorder, execute, multiremote clone+spawn) is proven only against a built CEF app — that lands in the E2E PR (CI fixture build + specs).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR brings @wdio/electrobun-service to feature-complete status, implementing mocking, multiremote support, triggerDeeplink, and fixture apps on top of the MVP foundation. It adds a full CDP bridge abstraction, a two-layer vitest-shaped mock system (outer spy in the WDIO worker + inner recorder injected into the CEF webview via Runtime.evaluate), per-worker bundle cloning for parallel-safe multiremote, and standalone session helpers.

• CDP Bridge & Mocking: Adds CdpBridge, Connection, and TargetRegistry in electrobun-cdp-bridge, plus innerRecorder.ts string-builders that inject a vitest-compatible spy into the CEF webview; call data is synced one-way into the outer mock via update().
• Multiremote / Parallel Safety: Per-worker bundle cloning (cp -Rc APFS fast-path → cpSync fallback) pins each worker's allocated port into build.json and gives each launch its own CFFIXED_USER_HOME.
• Fixtures & Types: Adds fixtures/e2e-apps/electrobun and fixtures/package-tests/electrobun-app, plus updated @wdio/native-types electrobun surface.

Confidence Score: 4/5

Safe to merge for single-app or multiremote setups; the parallel-workers + multi-app path silently runs the wrong binary.

The onWorkerStart resolved-app index bug means that in a parallel multi-worker run where each capability targets a different Electrobun binary, every worker clones and spawns resolvedApps[0] instead of its own resolved app. The vast majority of real setups have all workers pointing to the same binary so this goes unnoticed, but it is a correctness gap for multi-app configurations. Everything else — the CDP bridge, two-layer mock system, multiremote bundle cloning, standalone session, and the three previously flagged issues — is in good shape.

packages/electrobun-service/src/launcher.ts — the resolvedApps indexing in onWorkerStart

Important Files Changed

Filename	Overview
packages/electrobun-service/src/launcher.ts	Implements onWorkerStart for native-mode app cloning and port pinning. Has an indexing bug where multi-worker setups with distinct apps per capability always resolve resolvedApps[0] instead of the per-capability entry.
packages/electrobun-service/src/innerRecorder.ts	New file: string-builder library for the in-webview spy factory. Circular reference guard in buildReadCallDataScript addresses the previously flagged mockReturnThis issue.
packages/electrobun-service/src/mock.ts	New file: two-layer mock implementation. mockRestore correctly uses outerMockReset() (previous issue addressed). Clean lifecycle wiring.
packages/electrobun-service/src/nativeMode.ts	New file: per-worker bundle clone and process lifecycle. Temp dir leak on error is now fixed. Path rebase uses String.replace (first-occurrence only), which is safe for normal layouts but fragile.
packages/electrobun-service/src/service.ts	Worker service now attaches CdpBridge and installs the full electrobun.* surface. Bridges are closed in both after() and afterSession(); the second call is a safe no-op.
packages/electrobun-service/src/session.ts	New file: standalone session helpers. Cleanly drives launcher onPrepare/onWorkerStart manually with proper error cleanup ordering.
packages/electrobun-cdp-bridge/src/bridge.ts	New file: multi-target CDP client. Retry/discovery logic and active-target auto-advance after a window close are well-handled.
packages/electrobun-cdp-bridge/src/connection.ts	New file: single-target CDP WebSocket connection. Concurrent connect() calls resolve the second caller before the socket is OPEN; safe in the current single-caller usage.
packages/electrobun-service/src/electrobunConfig.ts	New file: bundle resolution, CEF verification, and build.json read/write. Comprehensive error messages and best-effort handling for non-macOS platforms.
packages/electrobun-service/src/commands/execute.ts	New file: browser.electrobun.execute over CDP Runtime.evaluate. jsonLiteral guards against functions/symbols/circulars with clean error propagation.

Sequence Diagram

sequenceDiagram
    participant TR as WDIO Test Runner
    participant L as ElectrobunLaunchService
    participant NM as nativeMode
    participant W as ElectrobunWorkerService
    participant CB as CdpBridge
    participant CEF as CEF Webview (CDP)

    TR->>L: onPrepare([capA, capB])
    L->>L: resolveElectrobunApp + verifyCefRenderer
    L-->>TR: resolvedApps[0..n] ready

    TR->>L: onWorkerStart(cid, [cap])
    L->>NM: cloneAppBundle(bundlePath)
    NM-->>L: clonedBundlePath, cloneParentDir
    L->>NM: writeRemoteDebuggingPort(clonedBuildJson, port)
    L->>NM: spawnElectrobunApp(...)
    NM-->>L: ElectrobunAppProcess
    L->>L: "cap.debuggerAddress = localhost:port"

    TR->>W: before(capabilities, specs, browser)
    W->>CB: new CdpBridge + connect()
    CB->>CEF: Runtime.enable
    W->>W: installApi(browser, bridge, mockStore)

    TR->>W: browser.electrobun.mock('api.fetchData')
    W->>CB: Runtime.evaluate(buildInstallScript)
    CB->>CEF: inject spy + replace window.api.fetchData
    W-->>TR: ElectrobunMock handle

    TR->>W: mock.update()
    W->>CB: Runtime.evaluate(buildReadCallDataScript)
    CEF-->>CB: JSON calls/results (circular-safe)
    W->>W: "sync into outerMock.mock.*"

    TR->>W: mock.mockRestore()
    W->>CB: Runtime.evaluate(buildRestoreScript)
    CB->>CEF: restore original window.api.fetchData
    W->>W: outerMockReset() + store.deleteMock()

    TR->>W: after() / afterSession()
    W->>CB: bridge.close()
    TR->>L: onComplete()
    L->>NM: stopElectrobunApp (SIGTERM + rmSync)

Loading

_{Reviews (5): Last reviewed commit: "fix(electrobun): preserve Error.name in ..." | Re-trigger Greptile}