# Configuration

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

## Service Configuration[​](#service-configuration "Direct link to 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[​](#service-options "Direct link to Service Options")

### `appBinaryPath`[​](#appbinarypath "Direct link to 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`[​](#appargs "Direct link to 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`[​](#autoinstalltauridriver "Direct link to 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`[​](#autodownloadedgedriver "Direct link to 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](/docs/desktop-testing/tauri/edge-webdriver-windows.md).

### `tauriDriverPort`[​](#tauridriverport "Direct link to 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`[​](#tauridriverpath "Direct link to 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`[​](#loglevel "Direct link to loglevel")

* Type

  `'trace' | 'debug' | 'info' | 'warn' | 'error'`

* Default

  `'info'`

* Required

  `No`

Log level for tauri-driver output.

**Example:**

```
logLevel: 'debug'  // More verbose
```

### `windowLabel`[​](#windowlabel "Direct link to 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`[​](#commandtimeout "Direct link to commandtimeout")

* Type

  `number`

* Default

  `30000 (30 seconds)`

* Required

  `No`

Timeout in milliseconds for individual command execution.

**Example:**

```
commandTimeout: 60000  // 60 seconds
```

### `startTimeout`[​](#starttimeout "Direct link to 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`[​](#capturebackendlogs "Direct link to 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](/docs/desktop-testing/tauri/log-forwarding.md).

### `captureFrontendLogs`[​](#capturefrontendlogs "Direct link to 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](/docs/desktop-testing/tauri/log-forwarding.md).

### `backendLogLevel`[​](#backendloglevel "Direct link to 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`[​](#frontendloglevel "Direct link to 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`[​](#logdir "Direct link to 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`[​](#statuspolltimeout "Direct link to 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`[​](#clearmocks "Direct link to 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`[​](#clearmocksprefix "Direct link to 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`[​](#resetmocks "Direct link to 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`[​](#resetmocksprefix "Direct link to 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`[​](#restoremocks "Direct link to 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`[​](#restoremocksprefix "Direct link to 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`[​](#driverprovider "Direct link to 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](/docs/desktop-testing/tauri/plugin-setup.md) for details.

### Choosing a Driver Provider[​](#choosing-a-driver-provider "Direct link to 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`[​](#embeddedport "Direct link to 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`[​](#crabnebuladriverpath "Direct link to 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`[​](#crabnebulamanagebackend "Direct link to 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`[​](#crabnebulabackendport "Direct link to crabnebulabackendport")

* Type

  `number`

* Default

  `3000`

* Required

  `No`

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

**Example:**

```
crabnebulaBackendPort: 3000
```

## Capabilities Configuration[​](#capabilities-configuration "Direct link to Capabilities Configuration")

Configure Tauri-specific capabilities in your `capabilities` array:

### Basic Configuration[​](#basic-configuration "Direct link to 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[​](#full-configuration "Direct link to 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[​](#multiremote-configuration "Direct link to 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[​](#complete-configuration-example "Direct link to 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[​](#platform-specific-configuration "Direct link to Platform-Specific Configuration")

### Windows Configuration[​](#windows-configuration "Direct link to 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[​](#linux-configuration "Direct link to Linux Configuration")

WebKitWebDriver is auto-detected:

```
services: [

  ['@wdio/tauri-service', {

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

    autoInstallTauriDriver: true,

  }]

]
```

### Headless Configuration (Linux)[​](#headless-configuration-linux "Direct link to 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[​](#finding-your-appbinarypath "Direct link to Finding Your appBinaryPath")

### Windows[​](#windows "Direct link to 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[​](#linux "Direct link to 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[​](#verify-binary-exists "Direct link to 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[​](#configuration-validation "Direct link to 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[​](#common-configuration-patterns "Direct link to Common Configuration Patterns")

### Development Configuration[​](#development-configuration "Direct link to 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[​](#cicd-configuration "Direct link to 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[​](#production-like-configuration "Direct link to 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[​](#troubleshooting-configuration-issues "Direct link to Troubleshooting Configuration Issues")

**"Cannot find appBinaryPath"**

1. Verify path exists:

   ```
   ls -la src-tauri/target/release/my-app*
   ```

2. Build the app first:

   ```
   cd src-tauri && cargo build --release
   ```

3. 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
```

## See Also[​](#see-also "Direct link to See Also")

* [Quick Start](/docs/desktop-testing/tauri/quick-start.md) for getting started
* [Plugin Setup](/docs/desktop-testing/tauri/plugin-setup.md) for Tauri plugin configuration
* [API Reference](/docs/desktop-testing/tauri/api.md) for available functions
* [Log Forwarding](/docs/desktop-testing/tauri/log-forwarding.md) for logging configuration
