Complete API reference for @wdio/tauri-service.
The following methods are available on the browser.tauri object when connected to a Tauri app.
Execute JavaScript code in the Tauri frontend context with access to Tauri APIs. Requires tauri-plugin-wdio to be installed and configured.
Parameters:
script(Function | string) - JavaScript code to execute. If a function, receives Tauri APIs as the first parameter...args(any[]) - Additional arguments passed to the script
Returns: Promise<ReturnValue>
Example:
// Execute with destructured Tauri APIs
const result = await browser.tauri.execute(({ core }) => {
return core.invoke('get_platform_info');
});
// Execute with full Tauri APIs object
const version = await browser.tauri.execute(async (tauri) => {
return tauri.app?.getVersion();
});
// Execute with arguments
const result = await browser.tauri.execute(
(tauri, name) => tauri.core.invoke('greet', { name }),
'World'
);
// Execute string of code
const result = await browser.tauri.execute('window.location.href');Note: Requires tauri-plugin-wdio to be installed. See Plugin Setup.
Mock a specific Tauri backend command. Returns a TauriMock object for configuring the mock behavior.
Parameters:
command(string) - Name of the Tauri command to mock
Returns: Promise<TauriMock>
Example:
const mock = await browser.tauri.mock('read_file');
await mock.mockReturnValue('mocked file content');
// Now calling invoke('read_file', ...) returns 'mocked file content'
const content = await browser.tauri.execute(({ core }) => core.invoke('read_file'));
expect(content).toBe('mocked file content');Check if a value is a Tauri mock function. This is a TypeScript type guard.
Parameters:
fn(unknown) - Value to check
Returns: boolean (type narrows to TauriMockInstance when true)
Example:
const mock = await browser.tauri.mock('clipboard_read');
if (browser.tauri.isMockFunction(mock)) {
// TypeScript knows mock is TauriMockInstance here
expect(mock.mock.calls).toHaveLength(1);
}Clear all mock call history and reset results, but keep the mock implementations in place.
Parameters:
commandPrefix(string, optional) - If provided, only mocks with command names starting with this prefix will be cleared
Returns: Promise<void>
Example:
// Clear all mocks
await browser.tauri.clearAllMocks();
// Clear only clipboard-related mocks
await browser.tauri.clearAllMocks('clipboard');Reset all mocks to their initial state (clears implementations and call history).
Parameters:
commandPrefix(string, optional) - If provided, only mocks with matching prefix are reset
Returns: Promise<void>
Remove all mocks and restore original command implementations.
Parameters:
commandPrefix(string, optional) - If provided, only mocks with matching prefix are restored
Returns: Promise<void>
Example:
await browser.tauri.restoreAllMocks();
// Commands now call the real Tauri backend againTrigger a deeplink to the Tauri application for testing protocol handlers. Uses platform-specific commands (open on macOS, xdg-open on Linux, cmd /c start on Windows).
Parameters:
url(string) - The deeplink URL to trigger (e.g.,'myapp://open?file=test.txt')
Returns: Promise<void>
Example:
await browser.tauri.triggerDeeplink('myapp://open?file=test.txt');
await browser.waitUntil(async () => {
const openedFile = await browser.tauri.execute(() => {
return globalThis.lastOpenedFile;
});
return openedFile === 'test.txt';
});See Deeplink Testing for full usage guide.
Switch the active Tauri window for subsequent operations. Changes the window that browser.tauri.execute() and other Tauri-specific operations target.
Parameters:
label(string) - The window label to switch to (e.g.,'main','settings')
Returns: Promise<void>
Example:
// Switch to the settings window
await browser.tauri.switchWindow('settings');
// Now executes in the settings window context
const data = await browser.tauri.execute(({ core }) => core.invoke('get_settings'));
// Switch back to main window
await browser.tauri.switchWindow('main');Note: The window label must exist in your Tauri app. Use browser.tauri.listWindows() to get available labels.
Get a list of all available Tauri window labels in the application.
Returns: Promise<string[]>
Example:
const windows = await browser.tauri.listWindows();
console.log(windows); // ['main', 'settings', 'dialog']The execute method supports optional per-call options to override session defaults:
Parameters:
script(Function | string) - JavaScript code to executeoptions(object, optional) - Per-call execution optionswindowLabel(string) - Override the default window for this call only
...args(any[]) - Additional arguments passed to the script
Example:
import { withExecuteOptions } from '@wdio/tauri-service';
// Execute in a specific window without changing session default
const result = await browser.tauri.execute(
(tauri) => tauri.core.invoke('get_data'),
withExecuteOptions({ windowLabel: 'popup' })
);
// Can also pass arguments after options
const greeting = await browser.tauri.execute(
(tauri, name) => tauri.core.invoke('greet', { name }),
withExecuteOptions({ windowLabel: 'settings' }),
'Alice'
);When you call browser.tauri.mock(command), you receive a TauriMock object with these methods:
Set a custom implementation function for the mock.
Returns: Promise<TauriMock>
Example:
const mock = await browser.tauri.mock('calculate');
await mock.mockImplementation(async (args) => args.x + args.y);
const result = await browser.tauri.execute(({ core }) => core.invoke('calculate', { x: 5, y: 3 }));
// result === 8Set a custom implementation for the next call only.
Returns: Promise<TauriMock>
Set the mock to always return a specific value.
Returns: Promise<TauriMock>
Example:
const mock = await browser.tauri.mock('get_user');
await mock.mockReturnValue({ id: 1, name: 'John' });Set the mock to return a specific value for the next call only.
Returns: Promise<TauriMock>
Example:
const mock = await browser.tauri.mock('counter');
await mock.mockReturnValueOnce(1);
await mock.mockReturnValueOnce(2);
await mock.mockReturnValue(3); // default for subsequent callsSet the mock to return a promise that resolves to the given value.
Returns: Promise<TauriMock>
Set the mock to resolve to a value for the next call only.
Returns: Promise<TauriMock>
Set the mock to return a promise that rejects with an error.
Returns: Promise<TauriMock>
Example:
const mock = await browser.tauri.mock('risky_operation');
await mock.mockRejectedValue(new Error('Operation failed'));Set the mock to reject for the next call only.
Returns: Promise<TauriMock>
Clear the call history of this mock without resetting its implementation.
Returns: Promise<TauriMock>
Reset the mock to its initial state (clears both implementation and call history).
Returns: Promise<TauriMock>
Remove this mock and restore the original command implementation.
Returns: Promise<TauriMock>
Set the mock to return this when called (useful for chaining).
Returns: Promise<unknown>
Set or get a display name for the mock (useful for debugging).
Get the current implementation function of the mock.
Sync mock call data from the inner mock (app context) to the outer mock (test process).
Returns: Promise<TauriMock>
Temporarily use a different implementation for the duration of a callback.
Example:
const mock = await browser.tauri.mock('my_command');
await mock.mockReturnValue('default');
await mock.withImplementation(
() => 'temporary',
async () => {
const result = await browser.tauri.execute(({ core }) => core.invoke('my_command'));
console.log(result); // 'temporary'
}
);
const result = await browser.tauri.execute(({ core }) => core.invoke('my_command'));
console.log(result); // 'default'mock.calls- Array of call argumentsmock.results- Array of call results__isTauriMock- Boolean flag identifying Tauri mocks
These functions are exported from @wdio/tauri-service for use in standalone mode or custom setups.
Get information about a Tauri application from its tauri.conf.json.
Parameters:
appPath(string) - Path to the Tauri app directory
Returns: Promise<TauriAppInfo>
Example:
import { getTauriAppInfo } from '@wdio/tauri-service';
const appInfo = await getTauriAppInfo('./fixtures/e2e-apps/tauri');
console.log(appInfo.name); // e.g., "my-app"
console.log(appInfo.version); // e.g., "0.1.0"
console.log(appInfo.binaryPath); // resolved path to binary
console.log(appInfo.configPath); // path to tauri.conf.json
console.log(appInfo.targetDir); // path to target directoryResolve the path to the Tauri application binary. Handles platform-specific paths (.exe on Windows, .app on macOS, etc.).
Parameters:
appPath(string) - Path to the Tauri app directory
Returns: Promise<string>
Example:
import { getTauriBinaryPath } from '@wdio/tauri-service';
const binaryPath = await getTauriBinaryPath('./fixtures/e2e-apps/tauri');Initialize the Tauri service in standalone mode. Use this when you want to manage the session manually outside of WebdriverIO's lifecycle.
Parameters:
capabilities(Capabilities) - WebdriverIO capabilities with Tauri optionsglobalOptions?(TauriServiceGlobalOptions) - Global service options
Returns: Promise<Browser>
Example:
import { startWdioSession } from '@wdio/tauri-service';
const browser = await startWdioSession({
browserName: 'tauri',
'tauri:options': {
application: './path/to/app.exe'
}
});
// Use browser...
await browser.deleteSession();Clean up a Tauri session started with startWdioSession.
Parameters:
browser(WebdriverIO.Browser) - Browser instance to clean up
Returns: Promise<void>
Create Tauri-specific capabilities for use in WebdriverIO config.
Parameters:
appBinaryPath(string) - Path to the Tauri app binaryoptions?(Partial) - Optional Tauri service options
Returns: TauriCapabilities
Example:
import { createTauriCapabilities } from '@wdio/tauri-service';
const capabilities = createTauriCapabilities('./path/to/app.exe', {
captureBackendLogs: true
});interface TauriAppInfo {
name: string;
version: string;
binaryPath: string;
configPath: string;
targetDir: string;
}interface TauriCapabilities extends WebdriverIO.Capabilities {
browserName?: 'tauri' | 'wry';
'tauri:options'?: {
application: string;
args?: string[];
webviewOptions?: {
width?: number;
height?: number;
};
};
'wdio:tauriServiceOptions'?: TauriServiceOptions;
}interface TauriServiceOptions {
appBinaryPath?: string;
appArgs?: string[];
tauriDriverPort?: number;
tauriDriverPath?: string;
logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
commandTimeout?: number;
startTimeout?: number;
captureBackendLogs?: boolean;
captureFrontendLogs?: boolean;
backendLogLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
frontendLogLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
driverProvider?: 'official' | 'crabnebula' | 'embedded';
embeddedPort?: number;
crabnebulaDriverPath?: string;
crabnebulaManageBackend?: boolean;
crabnebulaBackendPort?: number;
env?: Record<string, string>;
autoInstallTauriDriver?: boolean;
autoDownloadEdgeDriver?: boolean;
logDir?: string;
}Global options passed at the service level (not per-capability).
Uses the standard Result pattern:
type TauriResult<T = unknown> = { ok: true; value: T } | { ok: false; error: string };
// Usage
if (result.ok) {
console.log(result.value); // Success case
} else {
console.error(result.error); // Error case
}interface TauriCommandContext {
command: string;
args: unknown[];
timeout?: number;
}- All
browser.tauri.*methods require tauri-plugin-wdio to be installed. See Plugin Setup. - Mocking requires tauri-plugin-wdio for invoke interception to work.
- The
triggerDeeplinkmethod requires the@tauri-apps/plugin-deep-linkplugin in your app. - For detailed configuration examples, see Configuration.