Testing Tauri apps today means choosing between frontend mocks that lie about your backend, WebDriver setups that take a weekend, or paying for macOS CI runners. Victauri replaces all three: it embeds a lightweight server inside your Tauri process (debug builds only) that gives your test suite, curl, and CI direct access to the DOM, IPC layer, Rust backend state, the database, and native windows — from one test, on all three platforms. No WebDriver. No browser dependency. Works on macOS, Windows, and Linux.
That same server also speaks MCP, so any AI agent — Claude Code, Cursor, Windsurf — can drive and debug your app with the exact same full-stack access. Testing is the job; the agent integration is the bonus.
Tested against real-world Tauri apps. In a one-time deep evaluation (May 2026) across 5 open-source apps (Kanri, En Croissant, Surrealist, Duckling, Lettura), 867 / 895 checks passed (96.9%) with zero Victauri bugs and zero changes to the apps. A reproducible compat harness (
scripts/compat) re-runs an app-agnostic smoke battery against the current code on demand (and weekly), pinned to three Tauri-2 apps (Kanri, En Croissant, Lettura). It is a best-effort net for upstream drift, not a release gate — third-party apps move on their own schedules and periodically need re-pinning. See the compat README for what it covers and current per-app status.
Note — browser mode removed (2026-06-09). The experimental
victauri-browserextension +@4da/victauri-browsernpm package (MCP for any website) have been removed so Victauri can focus on its strength: full-stack introspection inside Tauri apps. For browser automation, use Playwright or the Chrome DevTools Protocol. The Tauri plugin is unaffected. Details & migration: #15.
What You Get
For your test suite and CI:
- Full-stack verification — click a button, verify the IPC call, query the database to confirm the write, check the UI updated — in one test
- Direct backend access — query SQLite databases, browse app files, read config, inspect process memory — no webview proxy
- Ghost command detection — find high-confidence orphaned frontend calls (
confirmed_ghosts: invoked but only ever errored "not found"), and backend commands the frontend never calls - Cross-boundary state checking — compare DOM state against Rust backend state and catch the drift between them
- Time-travel recording — record interactions, checkpoint state, replay sequences, generate test files
- Cross-platform, no WebDriver — the same tool surface on macOS, Windows, and Linux (no CDP dependency); runs headless in CI under
xvfb. Platform limits are documented, not hidden: trusted (OS-level) input is Windows-only (other platforms fall back to synthetic events), and window screenshots need X11/XWayland on Linux (pure Wayland fails with a clear error) - Zero runtime cost in release — the server is gated behind
#[cfg(debug_assertions)], soinit()is a no-op and nothing listens in release builds. Addvictauri-pluginas a normal[dependencies]entry (the app binary cannot see[dev-dependencies]); the crate still compiles in, so to keep it out of release binaries entirely make it an optional dependency behind a Cargo feature (victauri init --optionalscaffolds it). SQLite note: the defaultbundled-sqlitefeature turns onrusqlite/bundled, and Cargo feature unification applies it to your app'srusqlitetoo, in release builds as well. If your app links a system SQLite or SQLCipher, usedefault-features = false, features = ["sqlite"]
Bonus — for AI agents: the same server speaks MCP, so Claude Code, Cursor, Windsurf, and any MCP client get this full-stack access for interactive debugging — no extra setup.
Will Victauri work on your app?
Victauri is a development-time dependency you add to your own app's source and rebuild (a normal [dependencies] entry — not [dev-dependencies], which the app binary cannot use) — not a tool you attach to an already-running or shipped app. It works when all four hold:
- Tauri 2, or a Tauri 3 pre-release (turn on
victauri-plugin'stauri-v3feature — see the plugin README). Tauri 1.x apps can't host it — theirwebkit2gtk-sys 0.18and Victauri's2.xboth link the nativeweb_kit2library, an unresolvable cargo conflict. (Tauri 2 is the current major; Tauri 1 is legacy.) - Built from source with the plugin wired in — one line in
Cargo.toml,.plugin(victauri_plugin::init()), and thevictauri:defaultpermission (a capability file, or the runtime grantvictauri init --optionalgenerates). There is no inject-into-a-foreign-binary path. - A debug build. The server is
#[cfg(debug_assertions)]-gated, soinit()is a no-op and nothing listens in release. It's a dev/test-time tool by design. - Each window grants
victauri:default. Tauri's per-window permission ACL silently blinds the bridge without it; thewindow introspectabilitytool detects and explains this.
Framework (React, Vue/Nuxt, Svelte, vanilla) and OS/webview engine (WebView2 / WKWebView / WebKitGTK) do not matter — all supported and cross-checked on Windows, macOS, and Linux.
Full details, edge cases, and a tested-apps list: Compatibility.
Quick Start
Install the CLI
cargo install victauri-cli
Set up your project
From your Tauri project root:
victauri init
This will:
- Add
victauri-pluginandvictauri-core(dev:victauri-test,tokio) to yourCargo.toml - Add
.plugin(victauri_plugin::init())to your Tauri builder when it finds one - Create
capabilities/victauri.json(grantsvictauri:default),.mcp.json, starter tests intests/, a CI workflow, a CLAUDE.md block and a Claude Code skill (.claude/skills/victauri/SKILL.md) - Print any steps it could not do itself
Wire the plugin
Skip this if init reported that it patched your builder. Otherwise add one line:
// src-tauri/src/main.rs (or lib.rs)
tauri::Builder::default()
.plugin(victauri_plugin::init())
.invoke_handler(tauri::generate_handler![/* your commands */])
.run(tauri::generate_context!())
.expect("error while running tauri application");
In release builds, init() returns a no-op plugin: the server never starts and the linker strips it, so no feature flags are needed. #[inspectable] likewise compiles none of its metadata (descriptions, intents, examples) into a release build. The plugin's dependencies are still compiled (see below).
Zero release footprint. As an ordinary dependency the crate still compiles into a release
build (inert; the linker drops the unreachable server, but the default bundled-sqlite feature
adds SQLite's C code — about +1.7 MB without LTO, ~58 KB with LTO in a fresh project — and also
switches your app's own rusqlite, if any, to bundled). victauri init --optional instead
scaffolds Victauri as an optional dependency behind a victauri Cargo feature, so release
builds contain none of it; you then start the app with the feature on
(npm run tauri dev -- --features victauri, or pnpm tauri dev --features victauri).
See Getting Started → Zero release footprint.
Run tests
Start your app, then run the smoke suite:
npm run tauri dev # start your app (or pnpm/yarn/bun tauri dev)
cd src-tauri && VICTAURI_E2E=1 cargo test --test smoke # in a second terminal (the tests live in src-tauri/tests)
On Windows the running app locks its .exe, and cargo test rebuilds it, so give the test run its own target directory: CARGO_TARGET_DIR=target-test VICTAURI_E2E=1 cargo test --test smoke.
Or use the CLI for instant validation:
victauri test # 11 built-in smoke checks
victauri check # server health + IPC diagnostics
victauri call dom_snapshot # any tool from the shell → JSON on stdout
Use with your agent
One command per client. Each writes (or merges into) that client's MCP config, pointing at
victauri bridge --app <your identifier>, plus agent instructions telling it to prefer
Victauri over CDP/Playwright, verify it reached the right app, and await async work with
wait_for:
Existing configs are merged, never overwritten (comments in JSONC files survive), re-running
changes nothing, and --dry-run shows what would change. See
how Victauri compares to other Tauri agent and test tools.
Connect an AI agent by hand
Add .mcp.json to your project root (created automatically by victauri init):
{
"mcpServers": {
"victauri": {
"command": "victauri",
"args": ["bridge"]
}
}
}
The victauri bridge stdio proxy discovers the running app's port at connect time and
re-discovers on restart, so the agent always reaches the right app — even across rebuilds, or
when several Victauri apps are running (add "--app", "<your.bundle.identifier>" to pin one).
Prefer it over a fixed "url": "http://127.0.0.1:7373/mcp", which hardcodes a port and can
bind the wrong app.
Works with Claude Code, Cursor, Windsurf, and any MCP client. Your agent gets full-stack access: DOM snapshots, IPC monitoring, command invocation, screenshot capture, accessibility auditing, and more.
With Claude Code, start your app and Claude can immediately:
- Inspect the DOM tree and click/type/fill any element
- Invoke any
#[tauri::command]and verify the response - Read app config, list files, query SQLite databases
- Take screenshots and audit accessibility
- Record interactions and replay them as tests
Writing Tests
The e2e_test! macro handles server detection and auto-connect:
use victauri_test::{e2e_test, VictauriClient};
e2e_test!(greet_flow, |client| async move {
client.fill_by_id("name-input", "World").await.unwrap();
client.click_by_id("greet-btn").await.unwrap();
client.expect_text("Hello, World!").await.unwrap();
});
Locator API
For complex queries, composable locators with auto-waiting expectations:
use victauri_test::prelude::*;
e2e_test!(settings_flow, |client| async move {
let save = Locator::role("button").and_text("Save");
let email = Locator::label("Email address");
email.fill(&mut client, "[email protected]").await.unwrap();
save.click(&mut client).await.unwrap();
Locator::test_id("toast-message")
.expect(&mut client)
.to_contain_text("Settings saved")
.await
.unwrap();
});
Locators support role, text, test_id, css, label, placeholder, alt_text, and title strategies with chainable refinement (.and_text(), .nth(), .and_tag()). See the Testing Guide for the full Locator API reference.
Direct Client Methods
Full-Stack Verification
This is what sets Victauri apart — verifying that frontend actions actually trigger the right backend logic.
UI to IPC to Database
// Click "Save" in the UI
client.click_by_id("save-btn").await?;
// Verify the IPC command was called
let log = client.get_ipc_log(None).await?;
assert_ipc_called(&log, "save_settings");
// Verify the database was actually written
let result = client.query_db(
"SELECT value FROM settings WHERE key = 'theme'",
None, None,
).await?;
assert_eq!(result["rows"][0]["value"], "dark");
Fluent Verification
Check multiple conditions at once — DOM, IPC, accessibility, errors — with a single report:
client.verify()
.has_text("Settings saved")
.ipc_was_called("save_settings")
.no_console_errors()
.no_ghost_commands()
.ipc_healthy()
.coverage_above(80.0)
.run()
.await?
.assert_all_passed();
Ghost Command Detection
Find orphaned commands — called in the frontend but missing from the backend:
let ghosts = client.detect_ghost_commands().await?;
assert!(ghosts["confirmed_ghosts"].as_array().unwrap().is_empty(),
"Found ghost commands: {ghosts}");
See the Testing Guide for IPC checkpoints, visual regression testing, IPC coverage, accessibility auditing, performance monitoring, time-travel recording, CI integration, and more.
MCP Tools
35 tools across the full stack — backend, IPC, webview, and introspection:
Backend tools (direct Rust access, no webview needed)
IPC tools
Webview tools
Compound tools (multiple actions per tool)
No MCP client needed: every tool is also a shell command — victauri call query_db query="SELECT 1"
prints the result as JSON (victauri tools <name> shows a tool's arguments) — and a REST endpoint,
POST /api/tools/{name}. See the Tools Reference.
How It Works
AI Agent / cargo test / curl
|
v
HTTP on :7373
├── /mcp (MCP protocol — for AI agents)
├── /api/tools (REST API — for scripts and CI)
└── /health (health check — for monitoring)
|
v
Victauri Plugin (inside Tauri process)
| | |
v v v
WebView IPC Backend
- DOM - log - app config
- click - args - file system
- eval - cmds - SQLite DBs
- a11y - ghost - memory
- perf - verify- env vars
Victauri runs inside the Tauri process — same thread pool, same memory space. This isn't an implementation detail; it changes what's possible:
Port selection: Victauri tries port 7373 first, then falls back through 7374-7383 if taken. The actual port is written to a temp directory for automatic client discovery.
Architecture
victauri/
├── crates/
│ ├── victauri-plugin/ # Tauri plugin + MCP server + JS bridge (the main crate)
│ ├── victauri-core/ # Shared types (events, registry, snapshots, verification)
│ ├── victauri-macros/ # #[inspectable] proc macro for command schemas
│ ├── victauri-test/ # Test client + Locator API + assertion helpers
│ ├── victauri-cli/ # CLI: init, check, test, record, watch, coverage
│ └── victauri-watchdog/ # Health-check sidecar for crash recovery
├── docs/ # mdbook documentation site
└── examples/
└── demo-app/ # Multi-window Tauri app with 21 instrumented commands
Security
Victauri is designed for development, not production:
- Debug-only: the server is
#[cfg(debug_assertions)]-gated, soinit()is a no-op and nothing listens in release builds - Localhost-only: binds to 127.0.0.1, DNS rebinding protection
- Auth on by default: auto-generated Bearer token, auto-discovered by clients (
.auth_disabled()to opt out) - Rate limited: 1000 req/sec, token-bucket algorithm
- Privacy profiles:
Observe(read-only),Test(interactions),FullControl(everything) - Output redaction: auto-scrub API keys, tokens, emails from tool responses
See the Security Guide for threat model, privacy configuration, and command filtering.
CI Integration
GitHub Actions
Use the built-in composite action to run Victauri smoke tests in CI:
- name: Build my app
run: cargo build -p my-app
- name: Start app under xvfb
run: |
xvfb-run -a ./target/debug/my-app &
sleep 3
- uses: 4DA-Systems/victauri/.github/actions/[email protected]
with:
max-load-ms: 10000
max-heap-mb: 512
The action installs victauri-cli, waits for the server to become healthy, and runs all 11 smoke checks. Available inputs:
Or use victauri init to generate a complete CI workflow file for your project:
victauri init # generates .github/workflows/victauri.yml
Documentation
- Getting Started — Setup, capabilities, first connection
- Testing Guide — Locator API, IPC verification, visual regression, CI integration
- Tools Reference — All 35 tools with parameters and examples
- Architecture — Embedded design, JS bridge, dual protocol
- Configuration — Port, auth, privacy, capacity tuning
- Security — Threat model, privacy profiles, redaction
- FAQ — Common questions and troubleshooting
- Comparison — Victauri vs other Tauri agent/test tools, where each one wins
- VS Code Extension — Live inspection from your editor
- Demo App — Reference app with 21 instrumented commands
- Agent Session — Real AI agent transcript
- Migration Guide — Upgrading between versions
- Contributing — How to contribute
- Changelog — Release history
What It Doesn't Do
- No production use — debug builds only, by design
- No remote access — localhost only, no port forwarding
- Same-origin frames only — same-origin iframes are traversed; cross-origin frames are marked and skipped
- Frontend-IPC control is fetch-transport only —
faultinjection applies to commands driven through Victauri's owninvoke_command; to change what the app's realinvokegets, arouterule mocks or delays it on Tauri's fetch transport (the desktop default), but not over postMessage (Android, or after a fallback) - Not every webview↔Rust message is in the IPC log — command calls are captured on both of Tauri's transports (custom-protocol fetch and the
postMessagefallback;get_diagnosticsreports which is in use and whether capture is complete), but Rust→JS events outsidelisten_events,Channelmessages, and isolation-pattern args are not. See Architecture → IPC Layer - Pre-1.0 — API may change (semver-checked in CI)
Development
cargo build --workspace # Build all crates
cargo test --workspace # Run all tests
cargo bench -p victauri-core # Criterion benchmarks (16)
cargo clippy --workspace --all-targets # Lint (20 enforced lints)
cargo fmt --all -- --check # Format
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps # Docs (zero warnings)
Lint policy: 20 clippy lints (pedantic + nursery) enforced at deny level — see [workspace.lints.clippy] in Cargo.toml.
Community & Contributing
Victauri is open source and built by 4DA Systems, which uses it to test its own Tauri app. We want it to become the default way to test Tauri apps full-stack — and that needs more than one company.
- Using it on a Tauri app? Tell us — open a discussion or issue. We'd love to add you to a "used by" list and learn what broke.
- Want to contribute? See CONTRIBUTING.md. Good first areas: more
victauri-testassertion helpers, framework-specific testing guides, and CI recipes. - Found a bug or a Tauri app it doesn't work on? File an issue with the app and the failing tool call — those reports are the most valuable thing you can send us.
If Victauri saves you a weekend of WebDriver setup, a ⭐ helps other Tauri developers find it.
License
Apache-2.0 — LICENSE
Built and maintained by 4DA Systems.