Victauri

[Victauri]

Victauri

Verified Introspection & Control for Tauri Applications

Full-stack testing for Tauri apps. Click a button in the frontend, verify the Rust handler ran, confirm the database row was written — from one test.

[CI] [crates.io] [docs.rs] [License: Apache-2.0] [MSRV: 1.88+]

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-browser extension + @4da/victauri-browser npm 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)], so init() is a no-op and nothing listens in release builds. Add victauri-plugin as 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 --optional scaffolds it). SQLite note: the default bundled-sqlite feature turns on rusqlite/bundled, and Cargo feature unification applies it to your app's rusqlite too, in release builds as well. If your app links a system SQLite or SQLCipher, use default-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:

1. Tauri 2, or a Tauri 3 pre-release (turn on victauri-plugin's tauri-v3 feature — see the plugin README). Tauri 1.x apps can't host it — their webkit2gtk-sys 0.18 and Victauri's 2.x both link the native web_kit2 library, an unresolvable cargo conflict. (Tauri 2 is the current major; Tauri 1 is legacy.)
2. Built from source with the plugin wired in — one line in Cargo.toml, .plugin(victauri_plugin::init()), and the victauri:default permission (a capability file, or the runtime grant victauri init --optional generates). There is no inject-into-a-foreign-binary path.
3. A debug build. The server is #[cfg(debug_assertions)]-gated, so init() is a no-op and nothing listens in release. It's a dev/test-time tool by design.
4. Each window grants victauri:default. Tauri's per-window permission ACL silently blinds the bridge without it; the window introspectability tool detects and explains this.

Framework does not matter, because the bridge works at DOM level: it has been run on React, Vue/Nuxt and vanilla apps (what was actually run). Nor does the OS/webview engine: WebView2, WKWebView and WebKitGTK are all exercised in CI.

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-plugin and victauri-core (dev: victauri-test, tokio) to your Cargo.toml
• Add .plugin(victauri_plugin::init()) to your Tauri builder when it finds one
• Create capabilities/victauri.json (grants victauri:default), .mcp.json, starter tests in tests/, 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 -- --test-threads=1   # in a second terminal; tests share one app

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 -- --test-threads=1.

Or use the CLI for instant validation:

victauri test                                    # 11 built-in smoke checksvictauri check                                   # server health + IPC diagnosticsvictauri 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 connects for you, and skips the test (printing a skip line) unless VICTAURI_E2E is set. It does not detect a server, so set the variable where a run must count:

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 UIclient.click_by_id("save-btn").await?;
// Verify the IPC command was calledlet log = client.get_ipc_log(None).await?;assert_ipc_called(&log, "save_settings");
// Verify the database was actually writtenlet 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 25 instrumented commands

Security

Victauri is designed for development, not production:

• Debug-only: the server is #[cfg(debug_assertions)]-gated, so init() 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: opt-in (.enable_redaction(), on by default only under Observe); scrubs API keys, tokens, emails from tool responses
• Results and logs from the page are evidence against a buggy page, not a hostile one: a page can forge them. See what page script can do

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 25 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 — fault injection applies to commands driven through Victauri's own invoke_command; to change what the app's real invoke gets, a route rule 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 postMessage fallback; get_diagnostics reports which is in use and whether capture is complete), but Rust→JS events outside listen_events, Channel messages, and isolation-pattern args are not. See Architecture → IPC Layer
• Pre-1.0 — API may change (cargo semver-checks runs before each release; the CI step is informational)

Development

cargo build --workspace                               # Build all cratescargo test --workspace                                # Run all testscargo bench -p victauri-core                          # Criterion benchmarks (16)cargo clippy --workspace --all-targets                # Lint (20 enforced lints)cargo fmt --all -- --check                            # FormatRUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps  # Docs (zero warnings)

Lint policy: 20 entries enforced at deny level: clippy::all, 18 further clippy lints (pedantic + nursery), and rust's unsafe_code — see [workspace.lints] 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-test assertion 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.