API Reference

Complete API reference for @wdio/tauri-service.

browser.tauri API

The following methods are available on the browser.tauri object when connected to a Tauri app.

browser.tauri.execute(script, ...args)

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.

---

browser.tauri.mock(command)

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');

---

browser.tauri.isMockFunction(fn)

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);
}

---

browser.tauri.clearAllMocks(commandPrefix?)

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');

---

browser.tauri.resetAllMocks(commandPrefix?)

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>

---

browser.tauri.restoreAllMocks(commandPrefix?)

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 again

---

browser.tauri.triggerDeeplink(url)

Trigger 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.

---

browser.tauri.switchWindow(label)

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.

---

browser.tauri.listWindows()

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']

---

Updating browser.tauri.execute with Per-Call Options

The execute method supports optional per-call options to override session defaults:

Parameters:

• script (Function | string) - JavaScript code to execute
• options (object, optional) - Per-call execution options
  • windowLabel (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'
);

---

TauriMock Interface

When you call browser.tauri.mock(command), you receive a TauriMock object with these methods:

mockImplementation(fn)

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 === 8

---

mockImplementationOnce(fn)

Set a custom implementation for the next call only.

Returns: Promise\<TauriMock>

---

mockReturnValue(value)

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' });

---

mockReturnValueOnce(value)

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 calls

---

mockResolvedValue(value)

Set the mock to return a promise that resolves to the given value.

Returns: Promise\<TauriMock>

---

mockResolvedValueOnce(value)

Set the mock to resolve to a value for the next call only.

Returns: Promise\<TauriMock>

---

mockRejectedValue(error)

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'));

---

mockRejectedValueOnce(error)

Set the mock to reject for the next call only.

Returns: Promise\<TauriMock>

---

mockClear()

Clear the call history of this mock without resetting its implementation.

Returns: Promise\<TauriMock>

---

mockReset()

Reset the mock to its initial state (clears both implementation and call history).

Returns: Promise\<TauriMock>

---

mockRestore()

Remove this mock and restore the original command implementation.

Returns: Promise\<TauriMock>

---

mockReturnThis()

Set the mock to return this when called (useful for chaining).

Returns: Promise\<TauriMock>

---

mockName(name) / getMockName()

Set or get a display name for the mock (useful for debugging).

---

getMockImplementation()

Get the current implementation function of the mock.

---

update()

Sync mock call data from the inner mock (app context) to the outer mock (test process).

Returns: Promise\<TauriMock>

---

withImplementation(implFn, callbackFn)

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 Properties

• mock.calls - Array of call arguments
• mock.results - Array of call results
• __isTauriMock - Boolean flag identifying Tauri mocks

---

Package Exports

These functions are exported from @wdio/tauri-service for use in standalone mode or custom setups.

getTauriAppInfo(appPath)

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 directory

---

getTauriBinaryPath(appPath)

Resolve 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');

---

startWdioSession(capabilities, globalOptions?)

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 options
• globalOptions? (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();

---

cleanupWdioSession(browser)

Clean up a Tauri session started with startWdioSession.

Parameters:

• browser (WebdriverIO.Browser) - Browser instance to clean up

Returns: Promise<void>

---

createTauriCapabilities(appBinaryPath, options?)

Create Tauri-specific capabilities for use in WebdriverIO config.

Parameters:

• appBinaryPath (string) - Path to the Tauri app binary
• options? (Partial<TauriServiceOptions>) - Optional Tauri service options

Returns: TauriCapabilities

Example:

import { createTauriCapabilities } from '@wdio/tauri-service';

const capabilities = createTauriCapabilities('./path/to/app.exe', {
  captureBackendLogs: true
});

---

Exported Types

TauriAppInfo

interface TauriAppInfo {
  name: string;
  version: string;
  binaryPath: string;
  configPath: string;
  targetDir: string;
}

TauriCapabilities

interface TauriCapabilities extends WebdriverIO.Capabilities {
  browserName?: 'tauri' | 'wry';
  'tauri:options'?: {
    application: string;
    args?: string[];
    webviewOptions?: {
      width?: number;
      height?: number;
    };
  };
  'wdio:tauriServiceOptions'?: 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;
  statusPollTimeout?: number;
  crabnebulaDriverPath?: string;
  crabnebulaManageBackend?: boolean;
  crabnebulaBackendPort?: number;
  windowLabel?: string;
  clearMocks?: boolean;
  clearMocksPrefix?: string;
  resetMocks?: boolean;
  resetMocksPrefix?: string;
  restoreMocks?: boolean;
  restoreMocksPrefix?: string;
  env?: Record<string, string>;
  autoInstallTauriDriver?: boolean;
  autoDownloadEdgeDriver?: boolean;
  logDir?: string;
}

TauriServiceGlobalOptions

Global options passed at the service level (not per-capability).

TauriResult<T>

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
}

TauriCommandContext

interface TauriCommandContext {
  command: string;
  args: unknown[];
  timeout?: number;
}

---

Notes

• 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 triggerDeeplink method requires the @tauri-apps/plugin-deep-link plugin in your app.
• For detailed configuration examples, see Configuration.