Platform Support

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

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

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)

The service automatically:

Detects the WebView2 version in your Tauri binary
Downloads the matching MSEdgeDriver if missing
Handles version mismatches

Configuration:

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

Manual Setup

If auto-management fails:

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)
Download matching MSEdgeDriver
- Visit Microsoft Edge WebDriver
- Download the version matching your WebView2
- Extract to PATH or specify in config

Configure WebdriverIO

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

Troubleshooting Windows Issues

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

Version mismatch between driver and WebView2. Solutions:

Enable auto-download (default):
```
autoDownloadEdgeDriver: true
```
Or manually match versions:
- Check WebView2 version in your binary
- Download corresponding MSEdgeDriver
- Update PATH or config

"msedgedriver.exe not found"

Check if installed:
```
where msedgedriver.exe
```
Install or download from Microsoft Edge WebDriver
Add to PATH or disable auto-download and specify manually

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

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

Requirements

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

Linux

WebDriver: WebKitWebDriver

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

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

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

"webkit2gtk-driver not found"

Verify installation:
```
which webkit2gtk-driver
```
If not found, install for your distribution (see above)
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:

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

Or use Docker with X11 forwarding

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

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

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

✅ 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

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

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)

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

Requirements

Install tauri-plugin-wdio-webdriver in your Tauri app:

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

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");
}

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

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

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

✅ 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 for detailed setup instructions.

CrabNebula

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

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

Requirements

@crabnebula/tauri-driver npm package (all platforms)
@crabnebula/test-runner-backend npm package (macOS only, for local testing)
CN_API_KEY environment variable (macOS only)
tauri-plugin-automation in your Tauri app (macOS only)
webkit2gtk-driver (Linux only — see Linux section for installation)

Setup

Install CrabNebula packages:

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

For macOS only — add the automation plugin to your Tauri app:
```
cd src-tauri && cargo add tauri-plugin-automation
```

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());
}

For macOS only — set your API key:
```
export CN_API_KEY="your-api-key"
```

Configure WebdriverIO:

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

See the CrabNebula Setup Guide for detailed instructions.

Alternatives for macOS

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

Cross-Platform Testing
- Develop on macOS, run automated tests on Linux/Windows
- Perform manual QA on macOS
Web Version
- Deploy a web version of your app
- Test with traditional WebdriverIO setup

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

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

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

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

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.