# Configuration

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

## Service Configuration[​](#service-configuration "Direct link to Service Configuration")

Add the Dioxus service to your `wdio.conf.ts`:

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

## Service Options[​](#service-options "Direct link to Service Options")

### `driverProvider` ('external' | 'embedded', optional)[​](#driverprovider-external--embedded-optional "Direct link to driverprovider-external--embedded-optional")

Select which driver provider to use for WebDriver communication.

* `'embedded'`: Use the embedded WebDriver server wired in via `wdio-dioxus-bridge::install()`. No external driver needed. Works on all three platforms.
* `'external'`: Use `wdio-dioxus-driver` + msedgedriver (Windows only in v1). Linux is blocked pending an upstream Dioxus PR; macOS is not supported.

**Platform × Provider matrix:**

| Platform | `'embedded'` | `'external'`     |
| -------- | ------------ | ---------------- |
| Windows  | ✅ Yes       | ✅ Yes           |
| Linux    | ✅ Yes       | ❌ Blocked in v1 |
| macOS    | ✅ Yes       | ❌ Not supported |

**Default:** `'embedded'`

**Example:**

```
driverProvider: 'embedded'   // Recommended everywhere
driverProvider: 'external'   // Windows only in v1
```

***

### `appBinaryPath` (string, optional)[​](#appbinarypath-string-optional "Direct link to appbinarypath-string-optional")

Path to the compiled Dioxus application binary.

**Example:**

```
appBinaryPath: './target/debug/my_app',    // debug build (bridge active)
appBinaryPath: './target/release/my_app',  // release build (bridge inactive)
```

**Default:** Auto-detected from `dioxus:options.application` capability if not provided.

**Note:** For testing, always use a debug build (`cargo build` without `--release`) so the bridge is compiled in.

***

### `appArgs` (string\[], optional)[​](#appargs-string-optional "Direct link to appargs-string-optional")

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

**Example:**

```
appArgs: ['--debug', '--log-level', 'debug']
appArgs: ['--window-size=1920,1080']
```

**Default:** `[]`

***

### `autoInstallDioxusDriver` (boolean, optional)[​](#autoinstalldioxusdriver-boolean-optional "Direct link to autoinstalldioxusdriver-boolean-optional")

Automatically install `wdio-dioxus-driver` if not found in PATH. Only relevant when `driverProvider: 'external'`. Requires Rust toolchain (`cargo`).

**Example:**

```
autoInstallDioxusDriver: true
```

**Default:** `false`

***

### `autoDownloadEdgeDriver` (boolean, optional)[​](#autodownloadedgedriver-boolean-optional "Direct link to autodownloadedgedriver-boolean-optional")

Automatically download MSEdgeDriver on Windows if a version mismatch is detected. Only relevant when `driverProvider: 'external'` on Windows.

**Example:**

```
autoDownloadEdgeDriver: true  // Windows + external provider only
```

**Default:** `true`

**Note:** Ignored on Linux and macOS. See [Edge WebDriver (Windows)](/docs/desktop-testing/dioxus/edge-webdriver-windows.md).

***

### `dioxusDriverPort` (number, optional)[​](#dioxusdriverport-number-optional "Direct link to dioxusdriverport-number-optional")

Port for `wdio-dioxus-driver` to listen on. Only used when `driverProvider: 'external'`.

**Example:**

```
dioxusDriverPort: 4444
```

**Default:** `4444`

***

### `dioxusDriverPath` (string, optional)[​](#dioxusdriverpath-string-optional "Direct link to dioxusdriverpath-string-optional")

Path to the `wdio-dioxus-driver` executable if not in PATH. Only used when `driverProvider: 'external'`.

**Example:**

```
dioxusDriverPath: '/usr/local/bin/wdio-dioxus-driver'
dioxusDriverPath: 'C:\\tools\\wdio-dioxus-driver.exe'
```

**Default:** Use `wdio-dioxus-driver` from PATH.

***

### `embeddedPort` (number, optional)[​](#embeddedport-number-optional "Direct link to embeddedport-number-optional")

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

Each worker instance gets a unique port (basePort + workerIndex).

**Example:**

```
embeddedPort: 4445
```

**Default:** `4445`

***

### `statusPollTimeout` (number, optional)[​](#statuspolltimeout-number-optional "Direct link to statuspolltimeout-number-optional")

Timeout in milliseconds for the `/status` endpoint poll during embedded WebDriver server startup. Increase this in slow CI environments where a healthy-but-busy server may miss the default deadline.

**Example:**

```
statusPollTimeout: 5000
```

**Default:** `2000`

**Note:** Only applies when `driverProvider: 'embedded'`.

***

### `startTimeout` (number, optional)[​](#starttimeout-number-optional "Direct link to starttimeout-number-optional")

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

**Example:**

```
startTimeout: 60000  // 60 seconds
```

**Default:** `60000` for the `'embedded'` provider; `30000` for `'external'`.

***

### `windowLabel` (string, optional)[​](#windowlabel-string-optional "Direct link to windowlabel-string-optional")

The default window label to target for Dioxus operations. Controls which webview window `browser.dioxus.execute()` and other Dioxus-specific operations target by default.

**Example:**

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

**Default:** `'main'`

**Note:** Override at runtime with `browser.dioxus.switchWindow(label)`.

***

### `captureBackendLogs` (boolean, optional)[​](#capturebackendlogs-boolean-optional "Direct link to capturebackendlogs-boolean-optional")

Capture logs from the Dioxus backend (Rust code) and forward them to WebdriverIO's logger.

**Example:**

```
captureBackendLogs: true
```

**Default:** `false`

**Note:** See [Log Forwarding](/docs/desktop-testing/dioxus/log-forwarding.md).

***

### `captureFrontendLogs` (boolean, optional)[​](#capturefrontendlogs-boolean-optional "Direct link to capturefrontendlogs-boolean-optional")

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

**Example:**

```
captureFrontendLogs: true
```

**Default:** `false`

**Note:** See [Log Forwarding](/docs/desktop-testing/dioxus/log-forwarding.md).

***

### `backendLogLevel` ('trace' | 'debug' | 'info' | 'warn' | 'error', optional)[​](#backendloglevel-trace--debug--info--warn--error-optional "Direct link to backendloglevel-trace--debug--info--warn--error-optional")

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

**Example:**

```
backendLogLevel: 'debug'  // Capture debug and above
```

**Default:** `'info'`

**Note:** Only has effect if `captureBackendLogs: true`.

***

### `frontendLogLevel` ('trace' | 'debug' | 'info' | 'warn' | 'error', optional)[​](#frontendloglevel-trace--debug--info--warn--error-optional "Direct link to frontendloglevel-trace--debug--info--warn--error-optional")

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

**Example:**

```
frontendLogLevel: 'debug'
```

**Default:** `'info'`

**Note:** Only has effect if `captureFrontendLogs: true`.

***

### `env` (Record\<string, string>, optional)[​](#env-recordstring-string-optional "Direct link to env-recordstring-string-optional")

Additional environment variables to pass to the Dioxus application process.

**Example:**

```
env: {
  RUST_LOG: 'debug',
  MY_APP_ENV: 'test',
}
```

**Default:** `{}`

***

### `mode` ('native' | 'browser', optional)[​](#mode-native--browser-optional "Direct link to mode-native--browser-optional")

Controls how the service connects to your application.

* `'native'` (default) — launches your compiled Dioxus binary via the configured driver provider.
* `'browser'` — skips all driver and binary setup; sets `browserName = 'chrome'`, navigates to `devServerUrl`, and intercepts the invoke API so Dioxus commands can be mocked without a running Rust backend.

**Example:**

```
mode: 'browser'
```

**Default:** `'native'`

> All capabilities in a session must use the same mode. Mixing `'native'` and `'browser'` across capabilities throws a `SevereServiceError` at startup.

See [Browser Mode](/docs/desktop-testing/dioxus/browser-mode.md) for setup, mocking, and limitations.

***

### `devServerUrl` (string, required in browser mode)[​](#devserverurl-string-required-in-browser-mode "Direct link to devserverurl-string-required-in-browser-mode")

URL of the dev server to navigate to when `mode: 'browser'` is set. Validated with `new URL()` at startup.

**Example:**

```
devServerUrl: 'http://localhost:8080'
```

**Default:** `undefined`

**Note:** Only used when `mode: 'browser'`. Has no effect in native mode. See [Browser Mode](/docs/desktop-testing/dioxus/browser-mode.md).

***

### `clearMocks` (boolean, optional)[​](#clearmocks-boolean-optional "Direct link to clearmocks-boolean-optional")

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

**Default:** `false`

***

### `clearMocksPrefix` (string, optional)[​](#clearmocksprefix-string-optional "Direct link to clearmocksprefix-string-optional")

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

**Default:** `undefined`

***

### `resetMocks` (boolean, optional)[​](#resetmocks-boolean-optional "Direct link to resetmocks-boolean-optional")

If `true`, all mocks are reset (implementation + history) before each test.

**Default:** `false`

***

### `resetMocksPrefix` (string, optional)[​](#resetmocksprefix-string-optional "Direct link to resetmocksprefix-string-optional")

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

**Default:** `undefined`

***

### `restoreMocks` (boolean, optional)[​](#restoremocks-boolean-optional "Direct link to restoremocks-boolean-optional")

If `true`, all mocks are restored to their original implementations before each test.

**Default:** `false`

***

### `restoreMocksPrefix` (string, optional)[​](#restoremocksprefix-string-optional "Direct link to restoremocksprefix-string-optional")

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

**Default:** `undefined`

***

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

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

### Basic Configuration[​](#basic-configuration "Direct link to Basic Configuration")

```
capabilities: [{
  browserName: 'dioxus',
  'dioxus:options': {
    application: './target/debug/my_app'
  }
}]
```

### Full Capability Configuration[​](#full-capability-configuration "Direct link to Full Capability Configuration")

```
capabilities: [{
  browserName: 'dioxus',
  'dioxus:options': {
    application: './target/debug/my_app',
    args: ['--debug'],
    webviewOptions: {
      width: 1280,
      height: 800,
    },
  },
  'wdio:dioxusServiceOptions': {
    windowLabel: 'main',
    captureBackendLogs: true,
  },
}]
```

### `dioxus:options` Fields[​](#dioxusoptions-fields "Direct link to dioxusoptions-fields")

| Field                   | Type      | Required | Description                     |
| ----------------------- | --------- | -------- | ------------------------------- |
| `application`           | string    | Yes      | Path to the Dioxus app binary   |
| `args`                  | string\[] | No       | Arguments passed to the app     |
| `webviewOptions.width`  | number    | No       | Initial window width in pixels  |
| `webviewOptions.height` | number    | No       | Initial window height in pixels |

### Multiremote Configuration[​](#multiremote-configuration "Direct link to Multiremote Configuration")

```
capabilities: {
  app1: {
    browserName: 'dioxus',
    'dioxus:options': {
      application: './target/debug/my_app'
    }
  },
  app2: {
    browserName: 'dioxus',
    'dioxus:options': {
      application: './target/debug/my_app'
    }
  }
}
```

## Complete Configuration Example[​](#complete-configuration-example "Direct link to Complete Configuration Example")

```
// wdio.conf.ts
export const config = {
  runner: 'local',
  specs: ['./test/specs/**/*.spec.ts'],
  maxInstances: 1,

  services: [
    ['@wdio/dioxus-service', {
      driverProvider: 'embedded',
      appBinaryPath: './target/debug/my_app',
      appArgs: [],
      embeddedPort: 4445,
      startTimeout: 60000,
      statusPollTimeout: 2000,
      captureBackendLogs: true,
      captureFrontendLogs: true,
      backendLogLevel: 'debug',
      frontendLogLevel: 'debug',
      windowLabel: 'main',
      clearMocks: false,
      resetMocks: false,
      restoreMocks: false,
    }]
  ],

  capabilities: [{
    browserName: 'dioxus',
    'dioxus:options': {
      application: './target/debug/my_app',
    },
  }],

  logLevel: 'info',
  bail: 0,
  waitforTimeout: 10000,
  connectionRetryTimeout: 90000,
  connectionRetryCount: 3,

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

  reporters: ['spec'],
};
```

## Platform-Specific Configuration[​](#platform-specific-configuration "Direct link to Platform-Specific Configuration")

### Windows (`'embedded'` — recommended)[​](#windows-embedded--recommended "Direct link to windows-embedded--recommended")

```
services: [
  ['@wdio/dioxus-service', {
    driverProvider: 'embedded',
    appBinaryPath: './target/debug/my_app.exe',
  }]
]
```

### Windows (`'external'`)[​](#windows-external "Direct link to windows-external")

```
services: [
  ['@wdio/dioxus-service', {
    driverProvider: 'external',
    autoInstallDioxusDriver: true,
    autoDownloadEdgeDriver: true,
    appBinaryPath: './target/debug/my_app.exe',
  }]
]
```

### Linux (embedded only)[​](#linux-embedded-only "Direct link to Linux (embedded only)")

```
services: [
  ['@wdio/dioxus-service', {
    driverProvider: 'embedded',  // Only supported option on Linux
    appBinaryPath: './target/debug/my_app',
  }]
]
```

### macOS (embedded only)[​](#macos-embedded-only "Direct link to macOS (embedded only)")

```
services: [
  ['@wdio/dioxus-service', {
    driverProvider: 'embedded',  // Only supported option on macOS
    appBinaryPath: './target/debug/my_app',
  }]
]
```

## Finding Your Binary Path[​](#finding-your-binary-path "Direct link to Finding Your Binary Path")

### Debug Build (for testing)[​](#debug-build-for-testing "Direct link to Debug Build (for testing)")

```
cargo build
```

Binary locations:

* Windows: `target\debug\my_app.exe`
* Linux/macOS: `target/debug/my_app`

### Release Build (for production — bridge compiled out)[​](#release-build-for-production--bridge-compiled-out "Direct link to Release Build (for production — bridge compiled out)")

```
cargo build --release
```

Binary locations:

* Windows: `target\release\my_app.exe`
* Linux/macOS: `target/release/my_app`

**Always use a debug build for testing** so the bridge code is present.

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

* [Quick Start](/docs/desktop-testing/dioxus/quick-start.md) for getting started
* [Bridge Setup](/docs/desktop-testing/dioxus/plugin-setup.md) for bridge configuration
* [API Reference](/docs/desktop-testing/dioxus/api.md) for available functions
* [Log Forwarding](/docs/desktop-testing/dioxus/log-forwarding.md) for logging configuration
* [Platform Support](/docs/desktop-testing/dioxus/platform-support.md) for per-platform details