Skip to content

platform-support.md

Latest commit

 

History

History
552 lines (397 loc) · 14.4 KB

platform-support.md

File metadata and controls

552 lines (397 loc) · 14.4 KB

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:

  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

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

  3. 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:

  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

  3. 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"

  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

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

  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",
    "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

  • ✅ 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

  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

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

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

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.

See Also