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.

Discovery priority:

1. VICTAURI_PORT / VICTAURI_AUTH_TOKEN env vars (explicit override)
2. Per-process discovery directory: <temp>/victauri/<pid>/port
3. Legacy single-file: <temp>/victauri.port (v0.1.x compat)
4. Default: 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 is_alive(&self) -> bool

Check whether the server is still reachable.

Sends a GET to /health and returns true if the response is 200 OK.

pub async fn reconnect(&self, max_wait: Duration) -> Result<Self, TestError>

Re-establish an MCP session after the app restarts.

Polls /health up to max_wait and then re-runs the initialize/initialized handshake. The returned client has a fresh session ID; the old client should be dropped.

Errors

Returns TestError::Connection if the server doesn’t come back within max_wait.

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 dom_snapshot_for( &mut self, label: &str, ) -> Result<Value, TestError>

Get a DOM snapshot of a specific webview by label.

Errors

Returns errors from VictauriClient::call_tool.

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

Capture a screenshot of a specific webview by label.

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 double_click(&mut self, ref_id: &str) -> Result<Value, TestError>

Double-click an element by ref handle ID.

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 host(&self) -> &str

Get the host the client is connected to.

pub fn port(&self) -> u16

Get the port the client is connected to.

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>

👎Deprecated since 0.2.0:

renamed to get_ipc_calls_for

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_calls_since( &mut self, checkpoint: usize, ) -> Result<Vec<Value>, TestError>

👎Deprecated since 0.2.0:

renamed to get_ipc_calls_since

Get IPC calls made since a previous checkpoint.

Errors

Returns errors from VictauriClient::call_tool.

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

Filter the IPC log for calls to a specific command.

Errors

Returns errors from VictauriClient::call_tool.

pub async fn get_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 wait(&mut self, condition: &str) -> WaitForBuilder<'_>

Start a builder-style wait for a condition.

This is a fluent alternative to VictauriClient::wait_for that avoids positional Option arguments.

Examples

client.wait("text")
    .value("Welcome")
    .timeout_ms(5000)
    .run()
    .await
    .unwrap();

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

👎Deprecated since 0.2.0:

renamed to create_ipc_checkpoint

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

Prefer VictauriClient::create_ipc_checkpoint — this alias exists for backwards compatibility.

Errors

Returns errors from VictauriClient::call_tool.

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

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

Returns the number of IPC calls recorded so far. Pass this value to VictauriClient::ipc_calls_since to get only the calls that occurred after the checkpoint.

Errors

Returns errors from VictauriClient::call_tool.

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

Read plugin info as a typed PluginInfo struct.

This is a typed alternative to VictauriClient::get_plugin_info which returns raw JSON.

Errors

Returns TestError::Other if the response cannot be deserialized. Returns other errors from VictauriClient::call_tool.

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

Read process memory statistics as a typed MemoryStats struct.

This is a typed alternative to VictauriClient::get_memory_stats which returns raw JSON.

Errors

Returns TestError::Other if the response cannot be deserialized. Returns other 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 double_click_by_text( &mut self, text: &str, ) -> Result<Value, TestError>

Double-click the first element whose accessible text contains the given string.

Errors

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

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

Double-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 double_click_by_selector( &mut self, selector: &str, ) -> Result<Value, TestError>

Double-click the first element matching a CSS selector.

Resolves the selector via find_elements, then double-clicks the first match.

Errors

Returns TestError::ElementNotFound if no element matches the selector. Returns other errors from VictauriClient::call_tool.

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

Click the first element matching a CSS selector.

Resolves the selector via find_elements, then clicks the first match.

Errors

Returns TestError::ElementNotFound if no element matches the selector. 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 fill_by_text( &mut self, text: &str, value: &str, ) -> Result<Value, TestError>

Fill an input whose accessible text contains the given string.

Errors

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

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

Fill an input matching a CSS selector with the given value.

Resolves the selector via find_elements, then fills the first match.

Errors

Returns TestError::ElementNotFound if no element matches the selector. 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 select_option_by_id( &mut self, id: &str, values: &[&str], ) -> Result<Value, TestError>

Select option(s) in a <select> element identified by HTML id.

Accepts multiple values for multi-select elements.

Errors

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

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

Select option(s) in a <select> element whose accessible text contains the given string.

Errors

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

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

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

Resolves the selector via find_elements, then selects in the first match.

Errors

Returns TestError::ElementNotFound if no element matches the selector. Returns other errors from VictauriClient::call_tool.

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

Scroll an element matching a CSS selector into view.

Resolves the selector via find_elements, then scrolls the first match.

Errors

Returns TestError::ElementNotFound if no element matches the selector. Returns other errors from VictauriClient::call_tool.

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

Scroll an element with the given HTML id into view.

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.