WayDriver: Playwright-style functional testing for Wayland apps

2026-04-26T00:00:00+00:00

Playwright made web testing pleasant. You get a real browser, real input events, screenshots, video recording, an activity log, and an API that auto-waits on the things that need waiting on. Writing a functional test stops being a chore.</p>

There is no equivalent for Wayland desktop apps. Each compositor has its own headless mode, its own input-injection protocol, its own way of exposing a screencast, and none of them speak directly to a test runner. On X11 you reach for xvfb</code> — old, simple, reliable. On Wayland you improvise.</p>

WayDriver</strong></a> is a Rust library that tries to close that gap. Every test session boots its own Mutter in headless mode, its own PipeWire daemon, its own private D-Bus, and launches your app inside that bubble. You drive the app through two complementary channels: the AT-SPI accessibility tree (for finding widgets and invoking actions) and real Wayland input events (for pixel-accurate screenshots and hover states).</p>

A test, end to end</h2>
let mut</span> compositor</span> =</span> MutterCompositor</span>::</span>new</span>();</span></span>
compositor</span>.</span>start</span>(</span>None</span>)</span>.</span>await</span>?</span>;</span></span>
let</span> state</span> =</span> compositor</span>.</span>state</span>()</span>.</span>expect</span>(</span>"…after start"</span>);</span></span>
</span>
let</span> session</span> =</span> Session</span>::</span>start</span>(</span></span>
    Box</span>::</span>new</span>(</span>compositor</span>),</span></span>
    Box</span>::</span>new</span>(</span>MutterInput</span>::</span>new</span>(</span>state</span>.</span>clone</span>())),</span></span>
    Box</span>::</span>new</span>(</span>MutterCapture</span>::</span>new</span>(</span>state</span>)),</span></span>
    SessionConfig</span> {</span></span>
        command</span>:</span> "my-gtk-app"</span>.</span>into</span>(),</span></span>
        app_name</span>:</span> "my-gtk-app"</span>.</span>into</span>(),</span></span>
        video_output</span>:</span> Some</span>(</span>"/tmp/run.webm"</span>.</span>into</span>()),</span></span>
        ..</span>Default</span>::</span>default</span>()</span></span>
    },</span></span>
)</span>.</span>await</span>?</span>;</span></span>
</span>
session</span>.</span>locate</span>(</span>"//Button[@name='Sign in']"</span>)</span>.</span>click</span>()</span>.</span>await</span>?</span>;</span></span>
session</span>.</span>locate</span>(</span>"//Text[@name='username']"</span>)</span>.</span>fill</span>(</span>"alice"</span>)</span>.</span>await</span>?</span>;</span></span>
session</span>.</span>press_chord</span>(</span>"Ctrl+S"</span>)</span>.</span>await</span>?</span>;</span></span>
session</span>.</span>locate</span>(</span>"//Label[@name='status']"</span>)</span></span>
    .</span>wait_for_text</span>(</span>|</span>t</span>|</span> t</span> ==</span> "saved"</span>)</span></span>
    .</span>await</span>?</span>;</span></span></code></pre>
AT-SPI exposes every widget as a node with a role and properties, so XPath picks them out the way you'd query a DOM. The locator is lazy — each method re-snapshots the tree and re-runs the XPath, so there are no stale handles when GTK rebuilds a list view under your feet. Single-target actions return AmbiguousSelector</code> if your XPath matches more than one element, rather than silently picking the first.</p>
Each session produces a self-contained index.html</code> viewer with the WebM recording embedded and an event log, so when a test fails in CI you have something to look at.</p>

  
    Your browser does not support embedded video. The clip shows a WayDriver test session driving GNOME Calculator: typing 2 + 3</code>, pressing equals, and observing the result 5</code>.
  </video>
  A WayDriver session recording: GNOME Calculator is launched inside the headless Mutter bubble, then driven through AT-SPI to compute 2 + 3 = 5</code>.</figcaption>
</figure>
The architecture</h2>
┌─────────────────────────────────────────────────────┐</span></span>
│             Test or MCP process                     │</span></span>
│  Session                                            │</span></span>
│   ├─ Box<dyn CompositorRuntime>                     │</span></span>
│   ├─ Box<dyn InputBackend>                          │</span></span>
│   ├─ Box<dyn CaptureBackend>                        │</span></span>
│   ├─ keepalive PipeWireStream                       │</span></span>
│   └─ AppHandle                                      │</span></span>
└─────────────────────────────────────────────────────┘</span></span>
       │                                       ▲</span></span>
       ▼ private D-Bus              host bus   │ AT-SPI</span></span>
┌──────────────────────────────┐               │</span></span>
│ Per-session XDG_RUNTIME_DIR  │               │</span></span>
│   ├─ dbus-daemon (private)   │               │</span></span>
│   ├─ mutter --headless       │               │</span></span>
│   ├─ pipewire                │               │</span></span>
│   └─ wireplumber             │               │</span></span>
└──────────────────────────────┘               │</span></span>
                                               │</span></span>
                         target app  ──────────┘</span></span></code></pre>
The library is backend-agnostic. Three traits — CompositorRuntime</code>, InputBackend</code>, CaptureBackend</code> — define the contract; concrete implementations live in sibling crates. Mutter is wired up today. KWin and sway are reachable from the same trait surface.</p>
The MCP server</h2>
WayDriver started as a tool to let an AI coding assistant see and click around in a GTK app under development, so there is also waydriver-mcp</code> — a separate binary that exposes the same primitives over the Model Context Protocol</a>. Any MCP-aware agent can use it. Drop it in your .mcp.json</code>:</p>
{</span></span>
  "</span>mcpServers</span>": {</span></span>
    "</span>waydriver-mcp</span>": {</span></span>
      "</span>command</span>":</span> "sh"</span>,</span></span>
      "</span>args</span>": [</span>"-c"</span>,</span> "docker run --rm -i --network none \</span></span>
        -v </span>\"</span>$PWD:/workspace:ro</span>\"</span> \</span></span>
        -v /tmp/waydriver:/tmp/waydriver \</span></span>
        ghcr.io/bohdantkachenko/waydriver-mcp:latest"</span>]</span></span>
    }</span></span>
  }</span></span>
}</span></span></code></pre>
…and the agent gets tools for start_session</code>, dump_tree</code>, query</code>, click</code>, fill</code>, press_key</code>, hover</code>, drag_to</code>, take_screenshot</code>, and the rest. The --network none</code> is intentional: the MCP server spawns processes, talks to them over D-Bus, and captures their screen, so it runs in a container with a read-only $PWD</code> mount and no network access. Real test code, being reviewed and trusted, doesn't need the container.</p>
The MCP path is useful for exploration and for letting an agent manually verify a feature. The library path is useful for actual test suites, which is what most people will probably want.</p>
A note on how this was built</h2>
WayDriver was built with heavy use of Claude — about 15M tokens worth, in evenings after work. The architecture, crate separation, and trait-based backend split came out of design pushback against the AI's natural tendency to under-engineer. Mentioning this seems fair given what the project is for.</p>
Open-source desktops have always had passion behind them and rarely enough hands. That ratio is shifting. A small library like this, which would have been a multi-month side project a few years ago, fit into spare evenings between video games. There are a lot of GTK and Qt apps that could exist if writing them got cheaper, and the testing story is part of writing them.</p>
Try it</h2>

crates.io: waydriver</code></a></li>
Docker/Podman: bohdantkachenko/waydriver-mcp:latest</code></li>
</ul>
License is Apache-2.0.</p>
What would help most right now is people actually using it on real projects — finding the rough edges, filing issues, telling me what's missing. KWin and sway backends are doable from the existing trait surface; if there's interest, they'll happen.</p>

t7o.com

WayDriver: Playwright-style functional testing for Wayland apps