# Platform Support

Complete guide to platform-specific requirements, limitations, and WebDriver setup for Tauri testing.

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

| Platform    | Supported | WebDriver                | Driver Provider                      | Setup                     |
| ----------- | --------- | ------------------------ | ------------------------------------ | ------------------------- |
| **Windows** | ✅ Yes    | Microsoft Edge WebDriver | All (official, crabnebula, embedded) | Auto-managed              |
| **Linux**   | ✅ Yes    | WebKitWebDriver          | All (official, crabnebula, embedded) | Manual install            |
| **macOS**   | ✅ Yes    | Built-in                 | `'embedded'`, `'crabnebula'`         | No external driver needed |

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

### WebDriver: Microsoft Edge WebDriver[​](#webdriver-microsoft-edge-webdriver "Direct link to WebDriver: Microsoft Edge WebDriver")

Windows uses the **Microsoft Edge WebDriver** (msedgedriver.exe) which communicates with the WebView2 runtime embedded in your Tauri app.

#### Auto-Management (Recommended)[​](#auto-management-recommended "Direct link to Auto-Management (Recommended)")

The service automatically:

1. Detects the WebView2 version in your Tauri binary
2. Downloads the matching MSEdgeDriver if missing
3. Handles version mismatches

**Configuration:**

```
services: [['@wdio/tauri-service', {
  autoDownloadEdgeDriver: true,  // Default: true
}]],
```

#### Manual Setup[​](#manual-setup "Direct link to Manual Setup")

If auto-management fails:

1. **Detect your WebView2 version**

   * Build your app: `cargo build --release`
   * Right-click the .exe → Properties → Details
   * Note the "File version" (e.g., 143.0.3650.139)

2. **Download matching MSEdgeDriver**

   * Visit [Microsoft Edge WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/)
   * Download the version matching your WebView2
   * Extract to PATH or specify in config

3. **Configure WebdriverIO**

   ```
   services: [['@wdio/tauri-service', {
     autoDownloadEdgeDriver: false,
     tauriDriverPort: 4444,
   }]],
   ```

#### Troubleshooting Windows Issues[​](#troubleshooting-windows-issues "Direct link to Troubleshooting Windows Issues")

**"This version of Microsoft Edge WebDriver only supports Microsoft Edge version X"**

Version mismatch between driver and WebView2. Solutions:

1. Enable auto-download (default):

   ```
   autoDownloadEdgeDriver: true
   ```

2. Or manually match versions:

   * Check WebView2 version in your binary
   * Download corresponding MSEdgeDriver
   * Update PATH or config

**"msedgedriver.exe not found"**

1. Check if installed:

   ```
   where msedgedriver.exe
   ```

2. Install or download from [Microsoft Edge WebDriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/)

3. Add to PATH or disable auto-download and specify manually

### Alternative Driver Providers on Windows[​](#alternative-driver-providers-on-windows "Direct link to Alternative Driver Providers on Windows")

The default Windows setup uses `tauri-driver` + MSEdgeDriver (the `'official'` provider), but both other providers also work on Windows:

| Provider       | Notes                                                                  |
| -------------- | ---------------------------------------------------------------------- |
| `'official'`   | Default — uses tauri-driver + MSEdgeDriver, auto-managed               |
| `'embedded'`   | Requires `tauri-plugin-wdio-webdriver` in your app; no external driver |
| `'crabnebula'` | Requires a paid CrabNebula API key; cross-platform alternative         |

Use `'embedded'` if you want a consistent setup across Windows, Linux, and macOS without managing external drivers. Use `'crabnebula'` if you already have a CrabNebula subscription.

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

* ✅ Full Tauri API support
* ✅ Command execution
* ✅ Mocking with tauri-plugin-wdio
* ✅ Log capture (frontend and backend)
* ✅ Screenshot capture
* ✅ File operations
* ✅ Multiremote testing

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

* **Visual C++ Build Tools** or Visual Studio
* **Rust toolchain** (for building Tauri apps)
* **Node.js 18+**

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

### WebDriver: WebKitWebDriver[​](#webdriver-webkitwebdriver "Direct link to WebDriver: WebKitWebDriver")

Linux uses **WebKitWebDriver** (WebKitGTK) which communicates with the Tauri app's WebKit runtime.

#### Installation by Distribution[​](#installation-by-distribution "Direct link to Installation by Distribution")

**Debian/Ubuntu (✅ Supported)**

```
sudo apt-get update
sudo apt-get install -y webkit2gtk-driver

# Verify installation
which webkit2gtk-driver
```

**Fedora 40+ (✅ Supported)**

```
sudo dnf install -y webkit2gtk-driver

# Verify installation
which webkit2gtk-driver
```

**Arch Linux (✅ Supported)**

WebKitWebDriver is provided by webkit2gtk:

```
sudo pacman -S webkit2gtk-4.1

# Verify installation
which webkit2gtk-driver
```

**Void Linux (✅ Supported)**

```
sudo xbps-install -y webkit2gtk-devel

# Verify installation
which webkit2gtk-driver
```

**Alpine Linux (❌ Not Supported)**

Alpine uses musl C library which is incompatible with Tauri app building. Alpine can only be used as a **runtime container**, not for building Tauri apps.

**CentOS Stream / RHEL (❌ Not Supported)**

* **Stream 9 / RHEL 9**: glib 2.68 is too old (requires 2.70+)
* **Stream 10 / RHEL 10**: WebKitGTK intentionally removed due to security vulnerabilities

**Recommendation:** Use **Fedora 40+** for RHEL-based distributions.

**openSUSE / SUSE (❌ Not Supported)**

No official WebKitWebDriver package. Building from source is complex and not recommended.

**Other Distributions**

Check if webkit2gtk is available:

```
# Debian-based
apt search webkit2gtk-driver

# RedHat-based
dnf search webkit2gtk-driver

# Pacman-based
pacman -Ss webkit2gtk
```

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

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

**With Xvfb (X Virtual Framebuffer)**

Install Xvfb:

```
sudo apt-get install -y xvfb  # Debian/Ubuntu
sudo dnf install -y xvfb      # Fedora
```

Run tests:

```
xvfb-run -a npm run test:e2e
```

Or automatically via WebdriverIO (requires wdio 9.19.1+):

```
services: [['@wdio/tauri-service', {
  // Xvfb is auto-detected and used if available
}]],
```

**With Wayland**

If you're on a Wayland desktop:

```
# Set XWayland if needed
export GDK_BACKEND=x11
npm run test:e2e
```

#### Troubleshooting Linux Issues[​](#troubleshooting-linux-issues "Direct link to Troubleshooting Linux Issues")

**"webkit2gtk-driver not found"**

1. Verify installation:

   ```
   which webkit2gtk-driver
   ```

2. If not found, install for your distribution (see above)

3. Add to PATH if in non-standard location:

   ```
   export PATH="/path/to/driver:$PATH"
   ```

**"X11 connection refused" or "Cannot open display"**

Your system doesn't have a display server. Solutions:

1. **Use Xvfb**

   ```
   xvfb-run -a npm run test:e2e
   ```

2. **Or use Docker with X11 forwarding**

   ```
   docker run -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix my-image
   ```

3. **Or enable headless mode** (if supported):

   ```
   export WAYLAND_DISPLAY=""
   npm run test:e2e
   ```

**"glib version too old"**

CentOS Stream / RHEL issue. Use **Fedora 40+** instead.

**"Permission denied" when installing webkit2gtk**

Use `sudo` for package installation:

```
sudo apt-get install webkit2gtk-driver
```

### Alternative Driver Providers on Linux[​](#alternative-driver-providers-on-linux "Direct link to Alternative Driver Providers on Linux")

The default Linux setup uses `tauri-driver` + WebKitWebDriver (the `'official'` provider), but both other providers also work on Linux:

| Provider       | Notes                                                                  |
| -------------- | ---------------------------------------------------------------------- |
| `'official'`   | Default — uses tauri-driver + WebKitWebDriver, requires manual install |
| `'embedded'`   | Requires `tauri-plugin-wdio-webdriver` in your app; no external driver |
| `'crabnebula'` | Requires a paid CrabNebula API key; cross-platform alternative         |

Use `'embedded'` if you want a consistent setup across Windows, Linux, and macOS without managing external drivers. Use `'crabnebula'` if you already have a CrabNebula subscription.

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

* ✅ Full Tauri API support
* ✅ Command execution
* ✅ Mocking with tauri-plugin-wdio
* ✅ Log capture (frontend and backend)
* ✅ Screenshot capture
* ✅ File operations
* ✅ Headless testing with Xvfb
* ✅ Multiremote testing

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

* **WebKitGTK development libraries** (webkit2gtk-driver) — only needed for `'official'` provider
* **Xvfb** (optional, for headless testing)
* **Rust toolchain** (for building Tauri apps)
* **Node.js 18+**

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

> **Note:** macOS testing is supported natively via the embedded WebDriver provider. On macOS the service **auto-detects** the embedded provider — no explicit `driverProvider` configuration is needed.

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

The embedded WebDriver provider uses `tauri-plugin-wdio-webdriver` to provide native macOS support without requiring CrabNebula.

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

1. Install `tauri-plugin-wdio-webdriver` in your Tauri app:

   ```
   cd src-tauri && cargo add tauri-plugin-wdio-webdriver
   ```

2. Register the plugin in your Rust code (debug builds only):

   ```
   fn main() {
       let builder = tauri::Builder::default();

       #[cfg(debug_assertions)]
       let builder = builder.plugin(tauri_plugin_wdio_webdriver::init());

       builder
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }
   ```

3. Add permissions in `src-tauri/capabilities/default.json`:

   ```
   {
     "permissions": [
       "core:default",
       "core:window:default",
       "wdio-webdriver:default"
     ]
   }
   ```

4. Configure WebdriverIO — no explicit `driverProvider` needed on macOS:

   ```
   services: [['@wdio/tauri-service', {
     // driverProvider auto-detected as 'embedded' on macOS
   }]]
   ```

   You can also set it explicitly if you prefer:

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

#### Advantages[​](#advantages "Direct link to Advantages")

* ✅ No external driver needed (no CrabNebula subscription)
* ✅ Works natively on macOS — auto-detected, zero config
* ✅ Same plugin setup works on Windows and Linux too
* ✅ Simpler CI/CD configuration

See [Plugin Setup](/docs/desktop-testing/tauri/plugin-setup.md) for detailed setup instructions.

***

### CrabNebula[​](#crabnebula "Direct link to CrabNebula")

[CrabNebula](https://crabnebula.dev)'s `@crabnebula/tauri-driver` is a cross-platform alternative that works on Windows, Linux, and macOS. It's a fork of the official tauri-driver with added macOS support via a proprietary WebDriver implementation.

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

| Platform    | Supported | Requirements                                     |
| ----------- | --------- | ------------------------------------------------ |
| **Windows** | ✅ Yes    | `@crabnebula/tauri-driver`                       |
| **Linux**   | ✅ Yes    | `@crabnebula/tauri-driver` + `webkit2gtk-driver` |
| **macOS**   | ✅ Yes    | `@crabnebula/tauri-driver` + `CN_API_KEY`        |

> **Note:** `CN_API_KEY` is only required for macOS. Windows and Linux work without an API key.

#### When to Use CrabNebula[​](#when-to-use-crabnebula "Direct link to When to Use CrabNebula")

* You already have a CrabNebula subscription
* You want a single driver configuration across all platforms
* You need macOS testing without the embedded provider

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

1. **@crabnebula/tauri-driver** npm package (all platforms)
2. **@crabnebula/test-runner-backend** npm package (macOS only, for local testing)
3. **CN\_API\_KEY** environment variable (macOS only)
4. **tauri-plugin-automation** in your Tauri app (macOS only)
5. **webkit2gtk-driver** (Linux only — see Linux section for installation)

#### Setup[​](#setup "Direct link to Setup")

1. Install CrabNebula packages:

   ```
   npm install -D @crabnebula/tauri-driver
   # For macOS, also install:
   npm install -D @crabnebula/test-runner-backend
   ```

2. **For macOS only** — add the automation plugin to your Tauri app:

   ```
   cd src-tauri && cargo add tauri-plugin-automation
   ```

3. **For macOS only** — register the plugin (debug builds only):

   ```
   let mut builder = tauri::Builder::default();
   #[cfg(debug_assertions)]
   {
     builder = builder.plugin(tauri_plugin_automation::init());
   }
   ```

4. **For macOS only** — set your API key:

   ```
   export CN_API_KEY="your-api-key"
   ```

5. Configure WebdriverIO:

   ```
   services: [['@wdio/tauri-service', {
     driverProvider: 'crabnebula',
   }]]
   ```

See the [CrabNebula Setup Guide](/docs/desktop-testing/tauri/crabnebula-setup.md) for detailed instructions.

### Alternatives for macOS[​](#alternatives-for-macos "Direct link to Alternatives for macOS")

If you cannot use the embedded provider or CrabNebula, consider:

1. **Cross-Platform Testing**

   * Develop on macOS, run automated tests on Linux/Windows
   * Perform manual QA on macOS

2. **Web Version**

   * Deploy a web version of your app
   * Test with traditional WebdriverIO setup

### Building on macOS[​](#building-on-macos "Direct link to Building on macOS")

Build and test Tauri apps on macOS:

```
npm install
npm run tauri build
npx wdio run wdio.conf.ts
```

The service auto-detects the embedded provider on macOS. Make sure `tauri-plugin-wdio-webdriver` is installed and registered in your app.

### Example CI Configuration[​](#example-ci-configuration "Direct link to Example CI Configuration")

If you're developing on macOS but testing on Linux:

```
# .github/workflows/test.yml
jobs:
  test-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - uses: dtolnay/rust-toolchain@stable
      - run: npm install
      - run: npm run tauri build
      - run: npm run test:e2e

  build-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - uses: dtolnay/rust-toolchain@stable
      - run: npm install
      - run: npm run tauri build
      # No test step - just build verification
```

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

### CI/CD Matrix[​](#cicd-matrix "Direct link to CI/CD Matrix")

Test on multiple platforms:

```
// wdio.conf.ts - Example for matrix testing
export const config = {
  onPrepare: async (config, specs) => {
    const platform = process.platform;
    const arch = process.arch;

    console.log(`Testing on ${platform}-${arch}`);

    if (platform === 'win32') {
      config.services = [['@wdio/tauri-service', {
        autoDownloadEdgeDriver: true,
      }]];
    } else if (platform === 'linux') {
      config.services = [['@wdio/tauri-service', {
        // WebKitWebDriver auto-detected
      }]];
    } else if (platform === 'darwin') {
      config.services = [['@wdio/tauri-service', {
        // embedded provider auto-detected on macOS
      }]];
    }
  },
};
```

### Platform-Specific Tests[​](#platform-specific-tests "Direct link to Platform-Specific Tests")

Skip tests on unsupported platforms:

```
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")

* **Windows** - Fully supported with auto-managed Edge WebDriver ✅
* **Linux** - Fully supported with manual WebKitWebDriver setup ✅
* **macOS** - Fully supported via embedded WebDriver (no external drivers needed) ✅

Choose any platform for automated testing. Use `'embedded'` driver provider for the simplest setup.

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

* [Quick Start](/docs/desktop-testing/tauri/quick-start.md) for setup instructions
* [Edge WebDriver Windows](/docs/desktop-testing/tauri/edge-webdriver-windows.md) for Windows-specific details
* [Troubleshooting](/docs/desktop-testing/tauri/troubleshooting.md) for common issues
* [Tauri Platform-Specific Docs](https://v2.tauri.app/guides/develop/development-cycle/)