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. 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 get_diagnostics(&mut self) -> Result<Value, TestError>

Run environment diagnostics to detect potential compatibility issues.

Checks for service workers, closed shadow DOM, iframes, large DOM, and CSP status. Returns warnings and environment info.

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.

pub fn get_by_role(&self, role: &str) -> Locator

Create a Locator matching elements by ARIA role.

Equivalent to Playwright’s page.getByRole().

pub fn get_by_text(&self, text: &str) -> Locator

Create a Locator matching elements by visible text content.

Equivalent to Playwright’s page.getByText().

pub fn get_by_test_id(&self, id: &str) -> Locator

Create a Locator matching elements by data-testid attribute.

Equivalent to Playwright’s page.getByTestId().

pub fn get_by_label(&self, text: &str) -> Locator

Create a Locator matching form controls by associated label text.

Equivalent to Playwright’s page.getByLabel().

pub fn get_by_placeholder(&self, text: &str) -> Locator

Create a Locator matching elements by placeholder text.

Equivalent to Playwright’s page.getByPlaceholder().

pub fn locator(&self, css: &str) -> Locator

Create a Locator matching elements by CSS selector.

Equivalent to Playwright’s page.locator().

pub fn get_by_alt_text(&self, alt: &str) -> Locator

Create a Locator matching elements by alt text (images).

Equivalent to Playwright’s page.getByAltText().

pub fn get_by_title(&self, title: &str) -> Locator

Create a Locator matching elements by title attribute.

Equivalent to Playwright’s page.getByTitle().

pub async fn screenshot_to_file( &mut self, path: impl AsRef<Path>, ) -> Result<PathBuf, TestError>

Take a screenshot and save it to a file on disk.

Captures the default window, decodes the base64 PNG, and writes it to the given path. Returns the canonical path of the saved file.

Errors

Returns TestError::Other if the screenshot cannot be captured, decoded, or written to disk.

pub async fn screenshot_to_file_for( &mut self, label: &str, path: impl AsRef<Path>, ) -> Result<PathBuf, TestError>

Take a screenshot of a specific window and save it to a file.

Errors

Returns TestError::Other if the screenshot cannot be captured, decoded, or written to disk.

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.