Configuration

Complete guide to configuring @wdio/tauri-service in your WebdriverIO setup.

Service Configuration

Add the Tauri service to your wdio.conf.ts:

export const config = {
  services: [
    ['@wdio/tauri-service', {
      // Service options go here
      autoInstallTauriDriver: true,
      autoDownloadEdgeDriver: true,
      captureBackendLogs: true,
      captureFrontendLogs: true,
    }]
  ],
  // ... rest of config
};

Service Options

`appBinaryPath`

Type: string
Default: Auto-detected from capabilities if not provided
Required: No

Path to the compiled Tauri application binary (executable).

Example:

appBinaryPath: './src-tauri/target/release/my-app.exe',  // Windows
appBinaryPath: './src-tauri/target/release/my-app',     // Linux

Note: Path should be absolute or relative to the WebdriverIO config directory.

`appArgs`

Type: string[]
Default: []
Required: No

Command-line arguments to pass to the Tauri application when launching. Each array element is passed as a separate argument — no shell parsing is applied.

Example:

appArgs: ['--debug', '--log-level', 'debug']

// For key=value style arguments, use either form:
appArgs: ['--window-size', '1920,1080']   // Two separate elements
appArgs: ['--window-size=1920,1080']       // Single element with equals

`autoInstallTauriDriver`

Type: boolean
Default: false
Required: No

Automatically install tauri-driver if not found in PATH.

Requirements:

Rust toolchain must be installed (cargo)
First installation will take a few minutes

Example:

autoInstallTauriDriver: true

Note: Disable if you have tauri-driver installed manually or globally.

`autoDownloadEdgeDriver`

Type: boolean
Default: true
Required: No

Automatically download MSEdgeDriver on Windows if version mismatch detected.

Example:

autoDownloadEdgeDriver: true  // Windows only

Note: Windows only, ignored on Linux/macOS. See Edge WebDriver Windows.

`tauriDriverPort`

Type: number
Default: 4444
Required: No

Port for tauri-driver to listen on. Each worker process gets a unique port (port + worker index).

Example:

tauriDriverPort: 4444

Note: Increment for multiremote to avoid port conflicts.

`tauriDriverPath`

Type: string
Default: Use tauri-driver from PATH
Required: No

Path to the tauri-driver executable if not in PATH.

Example:

tauriDriverPath: '/usr/local/bin/tauri-driver'  // Linux/macOS
tauriDriverPath: 'C:\\tools\\tauri-driver.exe'  // Windows

`logLevel`

Type: 'trace' | 'debug' | 'info' | 'warn' | 'error'
Default: 'info'
Required: No

Log level for tauri-driver output.

Example:

logLevel: 'debug'  // More verbose

`windowLabel`

Type: string
Default: 'main'
Required: No

The default window label to target for Tauri operations. This controls which webview window browser.tauri.execute() and other Tauri-specific operations target by default.

Example:

windowLabel: 'settings'  // Target the settings window by default

Note:

Each browser instance (including multiremote) can have its own default windowLabel
Override at runtime with browser.tauri.switchWindow(label)
Per-call override with browser.tauri.execute(fn, withExecuteOptions({ windowLabel: 'x' })) is supported

`commandTimeout`

Type: number
Default: 30000 (30 seconds)
Required: No

Timeout in milliseconds for individual command execution.

Example:

commandTimeout: 60000  // 60 seconds

`startTimeout`

Type: number
Default: 30000 for the 'official' and 'crabnebula' providers, 60000 for the 'embedded' provider (the embedded WebDriver server takes longer to come up, especially on Windows CI).
Required: No

Timeout in milliseconds for the Tauri app to start and become ready.

Example:

startTimeout: 60000  // 60 seconds

`captureBackendLogs`

Type: boolean
Default: false
Required: No

Capture logs from the Tauri backend (Rust code).

Example:

captureBackendLogs: true

Note: When enabled, logs appear in WebdriverIO reports. See Log Forwarding.

`captureFrontendLogs`

Type: boolean
Default: false
Required: No

Capture console logs from the frontend (JavaScript/TypeScript).

Example:

captureFrontendLogs: true

Note: When enabled, console.log() calls appear in WebdriverIO reports. See Log Forwarding.

`backendLogLevel`

Type: 'trace' | 'debug' | 'info' | 'warn' | 'error'
Default: 'info'
Required: No

Minimum log level to capture from backend. Logs below this level are ignored.

Example:

backendLogLevel: 'debug'  // Capture debug and above

Note: Only has effect if captureBackendLogs: true.

`frontendLogLevel`

Type: 'trace' | 'debug' | 'info' | 'warn' | 'error'
Default: 'info'
Required: No

Minimum log level to capture from frontend. Logs below this level are ignored.

Example:

frontendLogLevel: 'debug'

Note: Only has effect if captureFrontendLogs: true.

`logDir`

Type: string
Default: Logs to stdout/stderr
Required: No

Directory to store logs from the Tauri service (for standalone mode).

Example:

logDir: './test-logs'

`statusPollTimeout`

Type: number
Default: 2000
Required: No

Timeout in milliseconds for the /status endpoint poll during embedded WebDriver server startup. Increase this in slow CI environments (e.g. containerised Windows runners) where a healthy-but-busy server may miss the default deadline and trigger a false-positive restart.

Example:

statusPollTimeout: 5000

Note: Only applies when driverProvider: 'embedded'.

`clearMocks`

Type: boolean
Default: false
Required: No

If true, all mock call history is cleared before each test. Equivalent to calling browser.tauri.clearAllMocks() in a beforeEach.

Example:

clearMocks: true

`clearMocksPrefix`

Type: string
Default: undefined
Required: No

If set, only mocks whose command name starts with this prefix are cleared. Only used when clearMocks: true.

Example:

clearMocks: true,
clearMocksPrefix: 'clipboard'  // Only clears clipboard.* mocks

`resetMocks`

Type: boolean
Default: false
Required: No

If true, all mocks are reset (implementation + history) before each test. Equivalent to browser.tauri.resetAllMocks() in a beforeEach.

Example:

resetMocks: true

`resetMocksPrefix`

Type: string
Default: undefined
Required: No

If set, only mocks whose command name starts with this prefix are reset. Only used when resetMocks: true.

`restoreMocks`

Type: boolean
Default: false
Required: No

If true, all mocks are restored to their original implementations before each test. Equivalent to browser.tauri.restoreAllMocks() in a beforeEach.

Example:

restoreMocks: true

`restoreMocksPrefix`

Type: string
Default: undefined
Required: No

If set, only mocks whose command name starts with this prefix are restored. Only used when restoreMocks: true.

`driverProvider`

Type: 'official' | 'crabnebula' | 'embedded'
Default: Auto-detected (see above). Set explicitly to override.
Required: No

Select which driver provider to use for WebDriver communication.

'embedded': Use embedded WebDriver server via tauri-plugin-wdio-webdriver (no external driver needed, works on all platforms)
'official': Use the cargo-installed tauri-driver (supports Windows/Linux)
'crabnebula': Use @crabnebula/tauri-driver from npm (supports Windows/Linux/macOS; CN_API_KEY required for macOS only)

Auto-detection (no explicit config needed):

The service automatically selects 'embedded' when either of the following signals is present:

TAURI_WEBDRIVER_PORT environment variable is set (you've configured the plugin's port)
Running on macOS (WKWebView requires the embedded approach)

If neither signal is present on Windows or Linux, the service throws an immediate error with instructions.

Example:

// Auto-detected on macOS, or when TAURI_WEBDRIVER_PORT is set — no config needed
// driverProvider: 'embedded'  (set this explicitly to be unambiguous)

// Use CrabNebula — all platforms; CN_API_KEY required for macOS
driverProvider: 'crabnebula'

// Use official tauri-driver — opt out of embedded provider
driverProvider: 'official'

Note: Install tauri-plugin-wdio-webdriver in your Tauri app to use the embedded provider. See Plugin Setup for details.

Choosing a Driver Provider

Provider	Platform Support	External driver required	Notes
`'embedded'`	Windows, Linux, macOS	No	No external deps; auto-detected on macOS or via `TAURI_WEBDRIVER_PORT`
`'official'`	Windows, Linux	Yes (tauri-driver + platform driver)	Explicit opt-in; cargo-installed
`'crabnebula'`	Windows, Linux, macOS	Yes (platform driver; CN_API_KEY for macOS)	Fork of official driver; good fit if already on CrabNebula platform

Recommendation:

'embedded' — simplest setup: no external driver installation, works on all three platforms
'crabnebula' — best if you are already using CrabNebula Cloud or want a single driver config across all platforms; macOS testing requires a CrabNebula subscription
'official' — explicit opt-in for Windows/Linux if you have tauri-driver already installed

`embeddedPort`

Type: number
Default: 4445
Required: No

Port for the embedded WebDriver server. Only used when driverProvider: 'embedded'.

The service spawns your Tauri app with this port
Each worker instance gets a unique port (basePort + workerIndex)
Can also be set via the TAURI_WEBDRIVER_PORT or WDIO_EMBEDDED_PORT environment variable. Setting either env var also serves as the auto-detection signal that opts you into the embedded provider on Windows/Linux.

Example:

embeddedPort: 4445

Note: Port must be available. The service will fail if the port is in use.

`crabnebulaDriverPath`

Type: string
Default: Auto-detected from node_modules
Required: No

Path to the @crabnebula/tauri-driver executable. Only used when driverProvider: 'crabnebula'.

Example:

crabnebulaDriverPath: './node_modules/.bin/tauri-driver'

`crabnebulaManageBackend`

Type: boolean
Default: true when using CrabNebula on macOS
Required: No

Auto-manage the test-runner-backend process (macOS only). When enabled, the service will automatically start and stop the backend.

Example:

crabnebulaManageBackend: true

`crabnebulaBackendPort`

Type: number
Default: 3000
Required: No

Port for the test-runner-backend to listen on (macOS only).

Example:

crabnebulaBackendPort: 3000

Capabilities Configuration

Configure Tauri-specific capabilities in your capabilities array:

Basic Configuration

capabilities: [{
  browserName: 'tauri',
  'tauri:options': {
    application: './src-tauri/target/release/my-app.exe'
  }
}]

browserName accepts either 'tauri' (preferred) or 'wry' (the underlying webview library). Both are treated identically by the service.

Full Configuration

capabilities: [{
  browserName: 'tauri',
  'tauri:options': {
    application: './src-tauri/target/release/my-app.exe',
    args: ['--debug']
  },
  // Optional: override service settings per capability
  // tauriDriverPort: 4445,
}]

Multiremote Configuration

Run multiple instances of the app:

capabilities: {
  app1: {
    browserName: 'tauri',
    'tauri:options': {
      application: './src-tauri/target/release/my-app.exe'
    }
  },
  app2: {
    browserName: 'tauri',
    'tauri:options': {
      application: './src-tauri/target/release/my-app.exe'
    }
  }
}

Or as array:

capabilities: [
  {
    browserName: 'tauri',
    'tauri:options': {
      application: './src-tauri/target/release/my-app.exe'
    }
  },
  {
    browserName: 'tauri',
    'tauri:options': {
      application: './src-tauri/target/release/my-app.exe'
    }
  }
]

Complete Configuration Example

// wdio.conf.ts
export const config = {
  runner: 'local',

  // Specs
  specs: ['./test/specs/**/*.spec.ts'],
  exclude: ['./test/specs/integration/**/*.spec.ts'],

  // Parallelization
  maxInstances: 1,
  maxInstancesPerCapability: 1,

  // Tauri Service
  services: [
    ['@wdio/tauri-service', {
      appBinaryPath: './src-tauri/target/release/my-app.exe',
      appArgs: ['--debug'],
      autoInstallTauriDriver: true,
      autoDownloadEdgeDriver: true,  // Windows only
      tauriDriverPort: 4444,
      logLevel: 'info',
      commandTimeout: 30000,
      startTimeout: 30000,
      captureBackendLogs: true,
      captureFrontendLogs: true,
      backendLogLevel: 'debug',
      frontendLogLevel: 'debug',
    }]
  ],

  // Capabilities
  capabilities: [{
    browserName: 'tauri',
    'tauri:options': {
      application: './src-tauri/target/release/my-app.exe',
      args: ['--debug']
    }
  }],

  // Connection settings
  logLevel: 'info',
  bail: 0,
  baseUrl: 'http://localhost:4444',
  waitforTimeout: 10000,
  connectionRetryTimeout: 90000,
  connectionRetryCount: 3,

  // Framework
  framework: 'mocha',
  mochaOpts: {
    ui: 'bdd',
    timeout: 60000
  },

  // Reporters
  reporters: ['spec'],

  // Hooks
  onPrepare: async (config, capabilities) => {
    console.log('Starting test run...');
  },

  onComplete: async (exitCode, config, capabilities, results) => {
    console.log('Test run completed');
  }
};

Platform-Specific Configuration

Windows Configuration

Enable auto Edge WebDriver management:

services: [
  ['@wdio/tauri-service', {
    appBinaryPath: './src-tauri/target/release/my-app.exe',
    autoDownloadEdgeDriver: true,  // Auto-download on version mismatch
  }]
]

Linux Configuration

WebKitWebDriver is auto-detected:

services: [
  ['@wdio/tauri-service', {
    appBinaryPath: './src-tauri/target/release/my-app',
    autoInstallTauriDriver: true,
  }]
]

Headless Configuration (Linux)

Run tests without a display server:

services: [
  ['@wdio/tauri-service', {
    appBinaryPath: './src-tauri/target/release/my-app',
    // Xvfb is auto-detected if available (WebdriverIO 9.19.1+)
  }]
]

Finding Your appBinaryPath

Windows

Build your app:

cd src-tauri
cargo build --release

Binary is at:

./src-tauri/target/release/my-app.exe

(Replace my-app with your app name from Cargo.toml)

Linux

Build your app:

cd src-tauri
cargo build --release

Binary is at:

./src-tauri/target/release/my-app

(Replace my-app with your app name)

Verify Binary Exists

# Windows
if exist "src-tauri\target\release\my-app.exe" echo "Binary found"

# Linux/macOS
ls -la src-tauri/target/release/my-app

Configuration Validation

Check your configuration with:

# Verify service can be loaded
npx wdio config

# Run with verbose logging
npx wdio run wdio.conf.ts --logLevel debug

Common Configuration Patterns

Development Configuration

export const config = {
  // ... other settings
  services: [
    ['@wdio/tauri-service', {
      appBinaryPath: './src-tauri/target/release/my-app.exe',
      autoInstallTauriDriver: true,
      autoDownloadEdgeDriver: true,
      captureBackendLogs: true,
      captureFrontendLogs: true,
      backendLogLevel: 'debug',
      frontendLogLevel: 'debug',
      logLevel: 'debug',
    }]
  ],
};

CI/CD Configuration

export const config = {
  // ... other settings
  services: [
    ['@wdio/tauri-service', {
      appBinaryPath: process.env.APP_BINARY || './src-tauri/target/release/my-app.exe',
      autoInstallTauriDriver: true,
      autoDownloadEdgeDriver: true,
      captureBackendLogs: true,
      captureFrontendLogs: true,
      logLevel: 'info',
    }]
  ],
};

Production-Like Configuration

export const config = {
  // ... other settings
  services: [
    ['@wdio/tauri-service', {
      appBinaryPath: './src-tauri/target/release/my-app.exe',
      autoInstallTauriDriver: false,  // Pre-installed
      autoDownloadEdgeDriver: false,  // Pre-downloaded
      captureBackendLogs: false,
      captureFrontendLogs: false,
      logLevel: 'warn',
    }]
  ],
};

Troubleshooting Configuration Issues

"Cannot find appBinaryPath"

Verify path exists:
```
ls -la src-tauri/target/release/my-app*
```
Build the app first:
```
cd src-tauri && cargo build --release
```

Use absolute path in config:

appBinaryPath: path.resolve('./src-tauri/target/release/my-app.exe')

"Service not found"

Ensure service is installed:

npm list @wdio/tauri-service

If missing:

npm install --save-dev @wdio/tauri-service

"Port already in use"

Change the tauri-driver port:

tauriDriverPort: 4445  // Instead of 4444

Or enable multiremote with auto-port assignment:

maxInstances: 3  // Each gets unique port

Service Configuration​

Service Options​

appBinaryPath​

appArgs​

autoInstallTauriDriver​

autoDownloadEdgeDriver​

tauriDriverPort​

tauriDriverPath​

logLevel​

windowLabel​

commandTimeout​

startTimeout​

captureBackendLogs​

captureFrontendLogs​

backendLogLevel​

frontendLogLevel​

logDir​

statusPollTimeout​

clearMocks​

clearMocksPrefix​

resetMocks​

resetMocksPrefix​

restoreMocks​

restoreMocksPrefix​

driverProvider​

Choosing a Driver Provider​

embeddedPort​

crabnebulaDriverPath​

crabnebulaManageBackend​

crabnebulaBackendPort​

Capabilities Configuration​

Basic Configuration​

Full Configuration​

Multiremote Configuration​

Complete Configuration Example​

Platform-Specific Configuration​

Windows Configuration​

Linux Configuration​

Headless Configuration (Linux)​

Finding Your appBinaryPath​

Windows​

Linux​

Verify Binary Exists​

Configuration Validation​

Common Configuration Patterns​

Development Configuration​

CI/CD Configuration​

Production-Like Configuration​

Troubleshooting Configuration Issues​

See Also​

Service Configuration

Service Options

`appBinaryPath`

`appArgs`

`autoInstallTauriDriver`

`autoDownloadEdgeDriver`

`tauriDriverPort`

`tauriDriverPath`

`logLevel`

`windowLabel`

`commandTimeout`

`startTimeout`

`captureBackendLogs`

`captureFrontendLogs`

`backendLogLevel`

`frontendLogLevel`

`logDir`

`statusPollTimeout`

`clearMocks`

`clearMocksPrefix`

`resetMocks`

`resetMocksPrefix`

`restoreMocks`

`restoreMocksPrefix`

`driverProvider`

Choosing a Driver Provider

`embeddedPort`

`crabnebulaDriverPath`

`crabnebulaManageBackend`

`crabnebulaBackendPort`

Capabilities Configuration

Basic Configuration

Full Configuration

Multiremote Configuration

Complete Configuration Example

Platform-Specific Configuration

Windows Configuration

Linux Configuration

Headless Configuration (Linux)

Finding Your appBinaryPath

Windows

Linux

Verify Binary Exists

Configuration Validation

Common Configuration Patterns

Development Configuration

CI/CD Configuration

Production-Like Configuration

Troubleshooting Configuration Issues

See Also