Struct VictauriClient 

pub struct VictauriClient { /* private fields */ }

Typed HTTP client for the Victauri MCP server.

Manages session lifecycle (initialize → tool calls → cleanup) and provides convenient methods for common test operations.

Implementations

impl VictauriClient

pub async fn connect(port: u16) -> Result<Self, TestError>

Connect to a Victauri MCP server on the given port. Sends initialize and notifications/initialized automatically.

Errors

Returns TestError::Connection if the server is unreachable or returns a non-success status. Returns TestError::Request on HTTP transport failures.

pub async fn connect_with_token( port: u16, token: Option<&str>, ) -> Result<Self, TestError>

Connect with an optional Bearer auth token.

Retries up to 3 times with exponential backoff on 429 (rate limited).

Errors

Returns TestError::Connection if the server is unreachable or returns a non-success status. Returns TestError::Request on HTTP transport failures.

pub async fn discover() -> Result<Self, TestError>

Auto-discover a running Victauri server via temp files.

Reads <temp>/victauri.port and <temp>/victauri.token written by the plugin on startup. Falls back to VICTAURI_PORT / VICTAURI_AUTH_TOKEN env vars, then defaults (port 7373, no auth).

Errors

Returns TestError::Connection if the server is unreachable or returns a non-success status. Returns TestError::Request on HTTP transport failures.

pub async fn call_tool( &mut self, name: &str, arguments: Value, ) -> Result<Value, TestError>

Call an MCP tool by name and return the result content as JSON.

Retries up to 3 times with exponential backoff on 429 (rate limited).

Errors

Returns TestError::Connection if the request fails after retries. Returns TestError::Request on HTTP transport errors. Returns TestError::Mcp if the server returns a JSON-RPC error.

pub async fn eval_js(&mut self, code: &str) -> Result<Value, TestError>

Evaluate JavaScript in the webview and return the result.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn dom_snapshot(&mut self) -> Result<Value, TestError>

Get a DOM snapshot of the current page.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn click(&mut self, ref_id: &str) -> Result<Value, TestError>

Click an element by ref handle ID.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn fill( &mut self, ref_id: &str, value: &str, ) -> Result<Value, TestError>

Fill an input element with a value.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn type_text( &mut self, ref_id: &str, text: &str, ) -> Result<Value, TestError>

Type text into an element character by character.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn list_windows(&mut self) -> Result<Value, TestError>

List all window labels.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_window_state( &mut self, label: Option<&str>, ) -> Result<Value, TestError>

Get the state of a specific window (or all windows).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn screenshot(&mut self) -> Result<Value, TestError>

Take a screenshot and return base64-encoded PNG.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn screenshot_visual( &mut self, name: &str, options: &VisualOptions, ) -> Result<VisualDiff, TestError>

Take a screenshot and compare it against a stored baseline.

Captures the current window, extracts the base64 PNG data, and passes it to visual::compare_screenshot. On first run the screenshot is saved as the new baseline.

Errors

Returns TestError::VisualRegression if the diff exceeds the threshold, or TestError::Other if the screenshot result does not contain recognizable image data.

pub async fn invoke_command( &mut self, command: &str, args: Option<Value>, ) -> Result<Value, TestError>

Invoke a Tauri command by name with optional arguments.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_ipc_log( &mut self, limit: Option<usize>, ) -> Result<Value, TestError>

Get the IPC call log.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn verify_state( &mut self, frontend_expr: &str, backend_state: Value, ) -> Result<Value, TestError>

Verify frontend state against backend state.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn detect_ghost_commands(&mut self) -> Result<Value, TestError>

Detect ghost commands (registered but never called, or called but not registered).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn check_ipc_integrity(&mut self) -> Result<Value, TestError>

Check IPC call health (pending, stale, errored).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn assert_semantic( &mut self, expression: &str, label: &str, condition: &str, expected: Value, ) -> Result<Value, TestError>

Run a semantic assertion against a JS expression.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn audit_accessibility(&mut self) -> Result<Value, TestError>

Run an accessibility audit.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_performance_metrics(&mut self) -> Result<Value, TestError>

Get performance metrics (timing, heap, resources).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_registry(&mut self) -> Result<Value, TestError>

Get the command registry.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_memory_stats(&mut self) -> Result<Value, TestError>

Get process memory statistics.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_plugin_info(&mut self) -> Result<Value, TestError>

Read plugin info (version, uptime, tool count).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn wait_for( &mut self, condition: &str, value: Option<&str>, timeout_ms: Option<u64>, poll_ms: Option<u64>, ) -> Result<Value, TestError>

Wait for a condition to be met, polling at an interval.

Conditions: text, text_gone, selector, selector_gone, url, ipc_idle, network_idle.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn start_recording( &mut self, session_id: Option<&str>, ) -> Result<Value, TestError>

Start a time-travel recording session.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn stop_recording(&mut self) -> Result<Value, TestError>

Stop the recording and return the session.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn export_session(&mut self) -> Result<Value, TestError>

Export the current recording session as JSON.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn find_elements(&mut self, query: Value) -> Result<Value, TestError>

Search for elements by various criteria without a full snapshot.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn hover(&mut self, ref_id: &str) -> Result<Value, TestError>

Hover over an element by ref handle.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn focus(&mut self, ref_id: &str) -> Result<Value, TestError>

Focus an element by ref handle.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn press_key(&mut self, key: &str) -> Result<Value, TestError>

Press a keyboard key.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn navigate(&mut self, url: &str) -> Result<Value, TestError>

Navigate to a URL.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn logs( &mut self, action: &str, limit: Option<usize>, ) -> Result<Value, TestError>

Get logs by type (console, network, ipc, navigation, dialogs).

Errors

Returns errors from VictauriClient::call_tool.

pub async fn scroll_to(&mut self, ref_id: &str) -> Result<Value, TestError>

Scroll an element into view by ref handle.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn select_option( &mut self, ref_id: &str, values: &[&str], ) -> Result<Value, TestError>

Select option(s) in a <select> element.

Errors

Returns errors from VictauriClient::call_tool.

pub fn base_url(&self) -> &str

Get the server base URL.

pub fn session_id(&self) -> &str

Get the MCP session ID.

pub async fn get_ipc_calls( &mut self, command: &str, ) -> Result<Vec<Value>, TestError>

Get IPC calls filtered to a specific command.

Returns a Vec of all IPC log entries matching the given command name.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn ipc_checkpoint(&mut self) -> Result<usize, TestError>

Snapshot the current IPC log length, for use with ipc_calls_since.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn ipc_calls_since( &mut self, checkpoint: usize, ) -> Result<Vec<Value>, TestError>

Get IPC calls made since a previous checkpoint.

Errors

Returns errors from VictauriClient::call_tool.

pub fn verify(&mut self) -> VerifyBuilder<'_>

Start a fluent verification chain that checks multiple conditions at once.

Unlike individual assertions that panic on failure, verify() collects all results and reports them together — making test failures more informative and reducing test reruns.

Examples

let report = client.verify()
    .has_text("Welcome")
    .ipc_was_called("greet")
    .no_console_errors()
    .run()
    .await
    .unwrap();
report.assert_all_passed();

pub async fn click_by_text(&mut self, text: &str) -> Result<Value, TestError>

Click the first element whose accessible text contains the given string.

Takes a DOM snapshot, finds the element, and clicks it.

Errors

Returns TestError::ElementNotFound if no matching element is found. Returns other errors from VictauriClient::call_tool.

pub async fn click_by_id(&mut self, id: &str) -> Result<Value, TestError>

Click the element with the given HTML id attribute.

Errors

Returns TestError::ElementNotFound if no element has the given id. Returns other errors from VictauriClient::call_tool.

pub async fn fill_by_id( &mut self, id: &str, value: &str, ) -> Result<Value, TestError>

Fill an input identified by HTML id with the given value.

Errors

Returns TestError::ElementNotFound if no element has the given id. Returns other errors from VictauriClient::call_tool.

pub async fn type_by_id( &mut self, id: &str, text: &str, ) -> Result<Value, TestError>

Type text into an input identified by HTML id, character by character.

Errors

Returns TestError::ElementNotFound if no element has the given id. Returns other errors from VictauriClient::call_tool.

pub async fn expect_text(&mut self, text: &str) -> Result<(), TestError>

Wait until the page contains the given text (polls DOM snapshots).

Default timeout: 5000ms, poll interval: 200ms.

Errors

Returns TestError::Timeout if the text doesn’t appear within the timeout. Returns other errors from VictauriClient::call_tool.

pub async fn expect_text_with_timeout( &mut self, text: &str, timeout_ms: u64, ) -> Result<(), TestError>

Wait until the page contains the given text, with a custom timeout in ms.

Errors

Returns TestError::Timeout if the text doesn’t appear within the timeout. Returns other errors from VictauriClient::call_tool.

pub async fn expect_no_text(&mut self, text: &str) -> Result<(), TestError>

Wait until the page no longer contains the given text.

Default timeout: 3000ms, poll interval: 200ms.

Errors

Returns TestError::Timeout if the text is still present after the timeout. Returns other errors from VictauriClient::call_tool.

pub async fn select_by_id( &mut self, id: &str, value: &str, ) -> Result<Value, TestError>

Select an option in a <select> element identified by HTML id.

Errors

Returns TestError::ElementNotFound if no element has the given id. Returns other errors from VictauriClient::call_tool.

pub async fn text_by_id(&mut self, id: &str) -> Result<String, TestError>

Get the text content of an element identified by HTML id.

Errors

Returns TestError::ElementNotFound if no element has the given id. Returns other errors from VictauriClient::call_tool.

impl VictauriClient

pub async fn assert_eval_works(&mut self) -> Result<(), TestError>

Assert that JavaScript evaluation works (evaluates 1+1).

Errors

Returns TestError::Assertion if evaluation returns the wrong result.

pub async fn assert_dom_snapshot_valid(&mut self) -> Result<(), TestError>

Assert that DOM snapshot returns a valid tree with elements.

Errors

Returns TestError::Assertion if the snapshot is empty or malformed.

pub async fn assert_screenshot_ok(&mut self) -> Result<(), TestError>

Assert that screenshot captures window image data.

Errors

Returns TestError::Assertion if no image data in the response.

pub async fn assert_windows_exist(&mut self) -> Result<(), TestError>

Assert that at least one window exists.

Errors

Returns TestError::Assertion if no windows are found.

pub async fn assert_ipc_integrity_ok(&mut self) -> Result<(), TestError>

Assert that IPC integrity is healthy.

Errors

Returns TestError::Assertion if the IPC integrity check reports stale or errored calls.

pub async fn assert_accessible(&mut self) -> Result<(), TestError>

Assert that the accessibility audit has zero violations.

Errors

Returns TestError::Assertion if any a11y violations are found.

pub async fn assert_dom_complete_under( &mut self, max: Duration, ) -> Result<(), TestError>

Assert DOM complete time is under the given duration.

Passes silently if the browser does not expose navigation timing.

Errors

Returns TestError::Assertion if load time exceeds the budget.

pub async fn assert_heap_under_mb( &mut self, max_mb: f64, ) -> Result<(), TestError>

Assert JS heap usage is under the given megabyte limit.

Passes silently if the browser does not expose heap metrics.

Errors

Returns TestError::Assertion if heap exceeds the budget.

pub async fn assert_no_uncaught_errors(&mut self) -> Result<(), TestError>

Assert there are no uncaught errors in the console log.

Checks for entries with [uncaught] prefix (from the JS bridge’s window.onerror and unhandledrejection handlers).

Errors

Returns TestError::Assertion if uncaught errors are found.

pub async fn assert_recording_lifecycle(&mut self) -> Result<(), TestError>

Assert that the recording lifecycle works end-to-end.

Starts a recording, generates activity via eval_js, waits for the event drain loop (2 seconds), stops recording, and verifies events were captured.

Errors

Returns TestError::Assertion if recording captures zero events.

pub async fn assert_health_hardened(&mut self) -> Result<(), TestError>

Assert that /health returns only {"status":"ok"}.

Verifies the endpoint doesn’t leak internal state like uptime, memory stats, or event counts.

Errors

Returns TestError::Assertion if extra fields are present or the response shape is wrong.

pub async fn smoke_test(&mut self) -> Result<SmokeReport, TestError>

Run the built-in smoke test suite with default configuration.

Exercises all core Victauri capabilities: eval, DOM, screenshot, windows, IPC integrity, accessibility, performance budgets, recording lifecycle, and health endpoint hardening.

Individual check failures are captured in the SmokeReport — the method itself only returns Err on fatal transport errors.

Errors

Returns TestError on connection or transport failures.

pub async fn smoke_test_with_config( &mut self, config: &SmokeConfig, ) -> Result<SmokeReport, TestError>

Run the built-in smoke test suite with custom thresholds.

Errors

Returns TestError on connection or transport failures.