Skip to main content

Configuration

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

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​

driverProvider​

Type
'external' | 'embedded'
Default
'embedded'
Required
No

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

Example:

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

appBinaryPath​

Type
string
Default
Auto-detected from dioxus:options.application capability if not provided.
Required
No

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)

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

appArgs​

Type
string[]
Default
[]
Required
No

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

autoInstallDioxusDriver​

Type
boolean
Default
false
Required
No

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

Example:

autoInstallDioxusDriver: true

autoDownloadEdgeDriver​

Type
boolean
Default
true
Required
No

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

Note: Ignored on Linux and macOS. See Edge WebDriver (Windows).

dioxusDriverPort​

Type
number
Default
4444
Required
No

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

Example:

dioxusDriverPort: 4444

dioxusDriverPath​

Type
string
Default
Use wdio-dioxus-driver from PATH.
Required
No

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'

embeddedPort​

Type
number
Default
4445
Required
No

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

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

Example:

embeddedPort: 4445

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 where a healthy-but-busy server may miss the default deadline.

Example:

statusPollTimeout: 5000

Note: Only applies when driverProvider: 'embedded'.

startTimeout​

Type
number
Default
60000 for the 'embedded' provider; 30000 for 'external'.
Required
No

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

Example:

startTimeout: 60000  // 60 seconds

windowLabel​

Type
string
Default
'main'
Required
No

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

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

captureBackendLogs​

Type
boolean
Default
false
Required
No

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

Example:

captureBackendLogs: true

Note: See Log Forwarding.

captureFrontendLogs​

Type
boolean
Default
false
Required
No

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

Example:

captureFrontendLogs: true

Note: See Log Forwarding.

backendLogLevel​

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

Minimum log level to capture from the Rust 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 the frontend webview. Logs below this level are ignored.

Example:

frontendLogLevel: 'debug'

Note: Only has effect if captureFrontendLogs: true.

env​

Type
Record<string, string>
Default
{}
Required
No

Additional environment variables to pass to the Dioxus application process.

Example:

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

mode​

Type
'native' | 'browser'
Default
'native'
Required
No

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'

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

See Browser Mode for setup, mocking, and limitations.

devServerUrl​

Type
string
Default
undefined
Required
Yes 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'

Note: Only used when mode: 'browser'. Has no effect in native mode. See Browser Mode.

clearMocks​

Type
boolean
Default
false
Required
No

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

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.

resetMocks​

Type
boolean
Default
false
Required
No

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

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.

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.

Capabilities Configuration​

Configure Dioxus-specific capabilities in your capabilities array:

Basic Configuration​

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

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​

FieldTypeRequiredDescription
applicationstringYesPath to the Dioxus app binary
argsstring[]NoArguments passed to the app
webviewOptions.widthnumberNoInitial window width in pixels
webviewOptions.heightnumberNoInitial window height in pixels

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​

// 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​

Windows ('embedded' — recommended)​

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

Windows ('external')​

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

Linux (embedded only)​

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

macOS (embedded only)​

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

Finding Your Binary Path​

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)​

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​

Welcome! How can I help?

WebdriverIO AI Copilot