# Platform Support

Complete guide to platform-specific requirements, limitations, and driver setup for Dioxus testing.

## Platform Support Overview[​](#platform-support-overview "Direct link to Platform Support Overview")

| Platform    | Supported | Driver Providers           | Notes                                                                             |
| ----------- | --------- | -------------------------- | --------------------------------------------------------------------------------- |
| **Windows** | ✅ Yes    | `'embedded'`, `'external'` | `'embedded'` recommended; `'external'` requires wdio-dioxus-driver + msedgedriver |
| **Linux**   | ✅ Yes    | `'embedded'` only          | `'external'` blocked in v1 — upstream Dioxus PR pending                           |
| **macOS**   | ✅ Yes    | `'embedded'` only          | `'external'` not supported                                                        |

## Driver Providers[​](#driver-providers "Direct link to Driver Providers")

### `'embedded'` (Recommended Everywhere)[​](#embedded-recommended-everywhere "Direct link to embedded-recommended-everywhere")

The embedded WebDriver provider uses `wdio-dioxus-embedded-driver` wired into the app via `wdio_dioxus_bridge::install(config)`. No external driver process is needed.

**Works on:** Windows, Linux, macOS

**Requirements:**

* `wdio-dioxus-bridge = "1"` in `Cargo.toml`
* `wdio_dioxus_bridge::install(config)` in `main.rs` inside `#[cfg(debug_assertions)]`
* Debug build of the app (`cargo build`)

**Configuration:**

```
services: [['@wdio/dioxus-service', {
  driverProvider: 'embedded',  // Default, recommended
}]]
```

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

The external provider uses `wdio-dioxus-driver` (a fork of `tauri-driver`) + `msedgedriver.exe`.

**Works on:** Windows only in v1

**Not supported on:** Linux (blocked — see below), macOS (never supported)

**Requirements:**

* `wdio-dioxus-driver` installed via `cargo install wdio-dioxus-driver`
* `msedgedriver.exe` (auto-managed by the service with `autoDownloadEdgeDriver: true`)

**Configuration:**

```
services: [['@wdio/dioxus-service', {
  driverProvider: 'external',
  autoInstallDioxusDriver: true,
  autoDownloadEdgeDriver: true,
}]]
```

## Windows[​](#windows "Direct link to Windows")

### `'embedded'` Provider (Recommended)[​](#embedded-provider-recommended "Direct link to embedded-provider-recommended")

No external driver needed. Ensure the bridge is in your app and use a debug build.

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

### `'external'` Provider[​](#external-provider "Direct link to external-provider")

Uses `wdio-dioxus-driver` → `msedgedriver.exe` → Dioxus app via WebView2 automation.

**Setup:**

1. Build a debug binary: `cargo build`
2. Configure the service:
   <!-- -->
   ```
   services: [['@wdio/dioxus-service', {
     driverProvider: 'external',
     autoInstallDioxusDriver: true,
     autoDownloadEdgeDriver: true,
     appBinaryPath: './target/debug/my_app.exe',
   }]]
   ```

The service auto-manages `msedgedriver.exe` to match the WebView2 version in your binary.

See [Edge WebDriver (Windows)](/docs/desktop-testing/dioxus/edge-webdriver-windows.md) for detailed setup.

### Windows-Specific Features[​](#windows-specific-features "Direct link to Windows-Specific Features")

* ✅ Full Dioxus invoke API via `browser.dioxus.execute()`
* ✅ Command mocking
* ✅ Log capture (frontend and backend)
* ✅ Screenshot capture
* ✅ Multiremote testing

### Windows Requirements[​](#windows-requirements "Direct link to Windows Requirements")

* **Visual C++ Build Tools** or Visual Studio
* **Rust toolchain**
* **Node.js 18+**
* For `'external'` provider: wdio-dioxus-driver + msedgedriver (auto-managed)

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

### `'embedded'` Provider Only[​](#embedded-provider-only "Direct link to embedded-provider-only")

`'external'` is blocked in v1 due to a missing upstream Dioxus API — the automation toggle that wdio-dioxus-driver needs to pass to Wry has not yet landed in the Dioxus/Wry codebase. This is tracked and will be enabled in v1.1 once the upstream PR merges.

Attempting to set `driverProvider: 'external'` on Linux throws a `SevereServiceError` at startup with an explanatory message.

**Configuration:**

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

### Linux Build Requirements[​](#linux-build-requirements "Direct link to Linux Build Requirements")

Install WebKitGTK libraries (required to build Dioxus desktop apps):

```
# Debian/Ubuntu
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

# Fedora
sudo dnf install -y webkit2gtk4.1-devel gtk3-devel

# Arch Linux
sudo pacman -S webkit2gtk-4.1 gtk3
```

### Headless Testing on Linux[​](#headless-testing-on-linux "Direct link to Headless Testing on Linux")

To run tests without a display (CI/CD environments):

```
# With Xvfb
sudo apt-get install -y xvfb
xvfb-run -a npx wdio run wdio.conf.ts
```

### Linux-Specific Features[​](#linux-specific-features "Direct link to Linux-Specific Features")

* ✅ Full Dioxus invoke API
* ✅ Command mocking
* ✅ Log capture
* ✅ Screenshot capture
* ✅ Headless testing with Xvfb
* ✅ Multiremote testing
* ❌ `'external'` provider (v1 — v1.1 target)

### Linux Distribution Support[​](#linux-distribution-support "Direct link to Linux Distribution Support")

| Distribution           | Status                                  |
| ---------------------- | --------------------------------------- |
| Debian / Ubuntu 22.04+ | ✅ Supported                            |
| Fedora 40+             | ✅ Supported                            |
| Arch Linux             | ✅ Supported                            |
| Alpine Linux           | ❌ Not supported (musl incompatibility) |

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

### `'embedded'` Provider Only[​](#embedded-provider-only-1 "Direct link to embedded-provider-only-1")

`'external'` is not supported on macOS and never will be — it inherits the same WKWebView limitation as the upstream `tauri-driver` fork it is based on.

**Configuration:**

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

### macOS-Specific Features[​](#macos-specific-features "Direct link to macOS-Specific Features")

* ✅ Full Dioxus invoke API
* ✅ Command mocking
* ✅ Log capture
* ✅ Screenshot capture
* ✅ Multiremote testing
* ❌ `'external'` provider (not supported, no timeline)

## Cross-Platform Tips[​](#cross-platform-tips "Direct link to Cross-Platform Tips")

### Recommended CI Matrix[​](#recommended-ci-matrix "Direct link to Recommended CI Matrix")

```
# .github/workflows/e2e.yml
jobs:
  e2e:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable

      - name: Install Linux dependencies
        if: runner.os == 'Linux'
        run: sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev xvfb

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install
      - run: cargo build

      - name: Run E2E (Linux, headless)
        if: runner.os == 'Linux'
        run: xvfb-run -a npm run test:e2e

      - name: Run E2E (Windows / macOS)
        if: runner.os != 'Linux'
        run: npm run test:e2e
```

### Platform-Conditional Tests[​](#platform-conditional-tests "Direct link to Platform-Conditional Tests")

```
describe('Platform-specific features', () => {
  it('should handle Windows path format', function() {
    if (process.platform !== 'win32') {
      this.skip();
    }
    // Windows-specific test
  });

  it('should handle Linux file permissions', function() {
    if (process.platform !== 'linux') {
      this.skip();
    }
    // Linux-specific test
  });
});
```

## Summary[​](#summary "Direct link to Summary")

| Provider     | Windows | Linux     | macOS      |
| ------------ | ------- | --------- | ---------- |
| `'embedded'` | ✅      | ✅        | ✅         |
| `'external'` | ✅      | ❌ (v1.1) | ❌ (never) |

Use `'embedded'` everywhere for the simplest, most consistent setup.

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

* [Quick Start](/docs/desktop-testing/dioxus/quick-start.md) for setup instructions
* [Edge WebDriver (Windows)](/docs/desktop-testing/dioxus/edge-webdriver-windows.md) for Windows `'external'` details
* [Troubleshooting](/docs/desktop-testing/dioxus/troubleshooting.md) for common issues