juce-webview-driver: end-to-end tests for live WebView UIs (WKWebView + WebView2, no CDP)

Hi all,

I’ve been building a plugin with a fairly heavy WebView UI (React + WebGL), and kept running into the same gap: the frontend gets tested in a browser against a mocked backend, but the bugs that matter only show up in the real plugin window. A control that never reaches its parameter, a preset that loads wrong, a WebGL view that renders nothing inside WKWebView.

So I wrote juce-webview-driver: a debug-only JUCE module plus a zero-dependency Node client that drives the live WebBrowserComponent inside the running app.

Integration

Three calls in the editor that owns the WebView, all compiled out unless JUCE_DEBUG:

#include <juce_webview_driver/juce_webview_driver.h>

driver  = std::make_shared<webview_driver::WebViewDriver>();
options = webview_driver::withCapture (std::move (options), driver); // before creating the WebView
webview_driver::connect (*driver, *webView, *this);                  // once it exists
driver->start();                                                     // 127.0.0.1, per-session token
// ...and driver->stop() in the destructor, before the WebView is destroyed

It’s a regular JUCE module (submodule or FetchContent, then juce_add_module). Builds against JUCE 8 and 9.

A test

import { connect, expect } from 'juce-webview-driver';

const page = await connect();
await page.getByTestId('gain').fill(0.25);                    // the real UI
await expect.poll(() => page.backend('getGain')).toBe(0.25);  // your withNativeFunction, i.e. real C++ state
await page.getByTestId('meter').screenshot();                 // OS compositor capture, WebGL included

On top of that: Playwright-style locators and auto-waiting assertions, drag on custom knobs/sliders, console/error/network streaming (fetch, XHR, WebSocket, SSE), and native screenshots (ScreenCaptureKit on macOS 14+, Windows.Graphics.Capture on Windows 11).

Everything goes through evaluateJavascript and native functions, so there’s no CDP and no remote-debugging flag. That’s what makes it work on WKWebView, which has no CDP at all.

Try it

The repo has a minimal JUCE 9 demo plugin (one slider bound to an APVTS parameter through WebSliderRelay, one WebGL meter) with a test that drives it, so you can see it work before touching your own project.

Limits

  • Synthetic input (isTrusted === false): ordinary handlers fire, but gesture-gated browser APIs don’t.
  • Network is observe-only.
  • Linux builds and passes CI, but hasn’t been tried against a real app, and native screenshots aren’t implemented there yet.

Repo: GitHub - mateusz28011/juce-webview-driver: End-to-end tests and debugging for live JUCE WebView UIs (WKWebView/WebView2): click and fill the DOM, eval JS, inspect console/network, check native C++ state, capture WebGL/canvas screenshots. Also drivable by AI coding agents. Debug-only JUCE module + zero-dependency Node clients; no CDP. · GitHub
npm: juce-webview-driver (MIT)

1 Like