# CrabNebula Setup

This guide walks you through setting up CrabNebula's tauri-driver for cross-platform Tauri testing.

## Overview[​](#overview "Direct link to Overview")

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

### 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`        |

### Key Points[​](#key-points "Direct link to Key Points")

* **CN\_API\_KEY is only required for macOS** — Windows and Linux work without an API key
* **tauri-plugin-automation is only needed for macOS** — not required on Windows or Linux
* **webkit2gtk-driver is required for Linux** — same as the official driver

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

Choose CrabNebula when:

* You want a single driver configuration across all platforms (Windows, Linux, macOS)
* You already have a CrabNebula subscription
* You need macOS testing but cannot use the embedded provider (`tauri-plugin-wdio-webdriver`)

For most users, the **embedded provider** (via `tauri-plugin-wdio-webdriver`) is the recommended choice for macOS testing — it's free, native, and requires no external services.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

### All Platforms[​](#all-platforms "Direct link to All Platforms")

1. **Node.js 18+** and **Rust toolchain** installed
2. A **Tauri v2 application**

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

* **webkit2gtk-driver** installed (see [Linux Installation](#linux-installation))

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

1. **CrabNebula account** with API key (contact [CrabNebula](https://crabnebula.dev) for access)
2. **tauri-plugin-automation** installed in your Tauri app

## Installation[​](#installation "Direct link to Installation")

### Step 1: Install CrabNebula Packages[​](#step-1-install-crabnebula-packages "Direct link to Step 1: Install CrabNebula Packages")

Install the npm packages as dev dependencies:

```
# All platforms

npm install -D @crabnebula/tauri-driver



# macOS only (for local testing)

npm install -D @crabnebula/test-runner-backend
```

Or with pnpm:

```
pnpm add -D @crabnebula/tauri-driver

# macOS only:

pnpm add -D @crabnebula/test-runner-backend
```

### Step 2: Linux Installation[​](#step-2-linux-installation "Direct link to Step 2: Linux Installation")

On Linux, you need WebKitWebDriver (same as the official driver):

```
# Debian/Ubuntu

sudo apt-get update

sudo apt-get install -y webkit2gtk-driver



# Fedora

sudo dnf install -y webkit2gtk-driver



# Arch Linux

sudo pacman -S webkit2gtk-4.1
```

Verify installation:

```
which WebKitWebDriver

# Should output: /usr/bin/WebKitWebDriver
```

### Step 3: macOS Setup (Optional)[​](#step-3-macos-setup-optional "Direct link to Step 3: macOS Setup (Optional)")

For macOS testing, you need the automation plugin and API key:

#### Add Automation Plugin[​](#add-automation-plugin "Direct link to Add Automation Plugin")

1. Navigate to your Tauri source directory:

   ```
   cd src-tauri
   ```

2. Add the plugin:

   ```
   cargo add tauri-plugin-automation
   ```

3. Register the plugin in your Rust code. **Important**: Only include this in debug builds:

   ```
   // src-tauri/src/lib.rs or main.rs



   let mut builder = tauri::Builder::default();



   // Only enable automation in debug builds

   #[cfg(debug_assertions)]

   {

     builder = builder.plugin(tauri_plugin_automation::init());

   }



   builder

     .run(tauri::generate_context!())

     .expect("error while running tauri application");
   ```

   > ⚠️ **Warning**: Never include the automation plugin in release builds, as it could allow external control of your application.

#### Set API Key[​](#set-api-key "Direct link to Set API Key")

Set your CrabNebula API key as an environment variable:

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

For CI/CD, add this as a secret:

**GitHub Actions:**

```
env:

  CN_API_KEY: ${{ secrets.CN_API_KEY }}
```

### Step 4: Configure WebdriverIO[​](#step-4-configure-webdriverio "Direct link to Step 4: Configure WebdriverIO")

Update your `wdio.conf.ts` to use CrabNebula:

```
export const config = {

  services: [

    ['@wdio/tauri-service', {

      driverProvider: 'crabnebula',

      // macOS only - auto-manage the test-runner-backend (default: true)

      crabnebulaManageBackend: true,

      // macOS only - backend port (default: 3000)

      crabnebulaBackendPort: 3000,

    }]

  ],

  

  capabilities: [{

    browserName: 'tauri',

    'tauri:options': {

      // Path to your binary

      application: './src-tauri/target/release/your-app-name',

    }

  }],

  

  // ... rest of your config

};
```

### Step 5: Build and Run[​](#step-5-build-and-run "Direct link to Step 5: Build and Run")

Build your Tauri app:

```
# Debug build (required for macOS automation plugin)

npm run tauri build -- --debug



# Or with cargo directly

cd src-tauri && cargo build
```

Run your tests:

```
npm run wdio
```

## Platform-Specific Notes[​](#platform-specific-notes "Direct link to Platform-Specific Notes")

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

* No additional setup required beyond installing `@crabnebula/tauri-driver`
* Edge WebDriver is auto-managed by the service

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

* Requires `webkit2gtk-driver` (see installation above)
* For headless CI, use Xvfb:
  <!-- -->
  ```
  xvfb-run -a npm run wdio
  ```

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

* Requires `CN_API_KEY` environment variable
* Requires `tauri-plugin-automation` in debug builds
* Requires `@crabnebula/test-runner-backend` for local testing
* The service auto-starts/stops the test-runner-backend

## CI/CD Configuration[​](#cicd-configuration "Direct link to CI/CD Configuration")

### GitHub Actions Example[​](#github-actions-example "Direct link to GitHub Actions Example")

```
name: E2E Tests



on: [push, pull_request]



jobs:

  test-linux:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - uses: dtolnay/rust-toolchain@stable

      

      - name: Install WebKitWebDriver

        run: sudo apt-get install -y webkit2gtk-driver

      

      - name: Install dependencies

        run: npm install

      

      - name: Build Tauri app

        run: npm run tauri build -- --debug

      

      - name: Run E2E tests

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

        env:

          DRIVER_PROVIDER: crabnebula



  test-macos:

    runs-on: macos-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - uses: dtolnay/rust-toolchain@stable

      

      - name: Install dependencies

        run: npm install

      

      - name: Build Tauri app

        run: npm run tauri build -- --debug

      

      - name: Run E2E tests

        env:

          CN_API_KEY: ${{ secrets.CN_API_KEY }}

          DRIVER_PROVIDER: crabnebula

        run: npm run test:e2e



  test-windows:

    runs-on: windows-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - uses: dtolnay/rust-toolchain@stable

      

      - name: Install dependencies

        run: npm install

      

      - name: Build Tauri app

        run: npm run tauri build -- --debug

      

      - name: Run E2E tests

        env:

          DRIVER_PROVIDER: crabnebula

        run: npm run test:e2e
```

### Conditional Testing (No API Key)[​](#conditional-testing-no-api-key "Direct link to Conditional Testing (No API Key)")

If you don't have a CN\_API\_KEY in certain environments (e.g., PRs from forks):

```
- name: Run E2E tests (macOS)

  if: env.CN_API_KEY != ''

  env:

    CN_API_KEY: ${{ secrets.CN_API_KEY }}

  run: npm run test:e2e



- name: Skip E2E tests (no API key)

  if: env.CN_API_KEY == ''

  run: echo "Skipping macOS tests - no CN_API_KEY available"
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### "CN\_API\_KEY is not set" (macOS)[​](#cn_api_key-is-not-set-macos "Direct link to \"CN_API_KEY is not set\" (macOS)")

**Solution**: Ensure the environment variable is set:

```
echo $CN_API_KEY  # Should show your API key
```

If empty, set it:

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

### "@crabnebula/tauri-driver not found"[​](#crabnebulatauri-driver-not-found "Direct link to \"@crabnebula/tauri-driver not found\"")

**Solution**: Install the package:

```
npm install -D @crabnebula/tauri-driver
```

### "tauri-plugin-automation not found" (macOS)[​](#tauri-plugin-automation-not-found-macos "Direct link to \"tauri-plugin-automation not found\" (macOS)")

**Solution**: Add the plugin to your Tauri app:

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

Then ensure it's registered in your Rust code with the `#[cfg(debug_assertions)]` guard.

### "WebKitWebDriver not found" (Linux)[​](#webkitwebdriver-not-found-linux "Direct link to \"WebKitWebDriver not found\" (Linux)")

**Solution**: Install WebKitWebDriver:

```
# Debian/Ubuntu

sudo apt-get install -y webkit2gtk-driver



# Fedora

sudo dnf install -y webkit2gtk-driver



# Arch Linux

sudo pacman -S webkit2gtk-4.1
```

### "test-runner-backend exited with code X" (macOS)[​](#test-runner-backend-exited-with-code-x-macos "Direct link to \"test-runner-backend exited with code X\" (macOS)")

**Possible causes**:

* Invalid or expired CN\_API\_KEY
* Port 3000 already in use
* macOS security restrictions

**Solutions**:

1. Verify your API key is valid
2. Change the backend port:
   <!-- -->
   ```
   crabnebulaBackendPort: 3001
   ```
3. Check System Preferences > Security & Privacy for any blocked applications

### Tests work on Windows/Linux but not macOS[​](#tests-work-on-windowslinux-but-not-macos "Direct link to Tests work on Windows/Linux but not macOS")

**Checklist**:

* <!-- -->
  CN\_API\_KEY is set and valid
* <!-- -->
  tauri-plugin-automation is in Cargo.toml
* <!-- -->
  Plugin is registered with `#[cfg(debug_assertions)]`
* <!-- -->
  App is built in debug mode (target/debug/)
* <!-- -->
  @crabnebula/tauri-driver is installed
* <!-- -->
  @crabnebula/test-runner-backend is installed

## Advanced Configuration[​](#advanced-configuration "Direct link to Advanced Configuration")

### Custom Backend Port (macOS)[​](#custom-backend-port-macos "Direct link to Custom Backend Port (macOS)")

If port 3000 is already in use:

```
services: [['@wdio/tauri-service', {

  driverProvider: 'crabnebula',

  crabnebulaBackendPort: 3001,

}]]
```

### Manual Backend Management (macOS)[​](#manual-backend-management-macos "Direct link to Manual Backend Management (macOS)")

If you prefer to manage the backend yourself:

```
services: [['@wdio/tauri-service', {

  driverProvider: 'crabnebula',

  crabnebulaManageBackend: false,  // You'll start/stop it manually

}]]
```

Then in your test setup:

```
# Terminal 1: Start backend

npx test-runner-backend



# Terminal 2: Run tests

export REMOTE_WEBDRIVER_URL=http://127.0.0.1:3000

npm run wdio
```

### Custom Driver Path[​](#custom-driver-path "Direct link to Custom Driver Path")

If the driver is not in node\_modules/.bin:

```
services: [['@wdio/tauri-service', {

  driverProvider: 'crabnebula',

  crabnebulaDriverPath: '/custom/path/to/tauri-driver',

}]]
```

## Migration from Official Driver[​](#migration-from-official-driver "Direct link to Migration from Official Driver")

If you're already using the official tauri-driver on Windows/Linux:

1. Keep your existing configuration for Windows/Linux
2. Add CrabNebula packages as dev dependencies
3. **For macOS only**: Add the automation plugin to your Tauri app
4. **For macOS only**: Set CN\_API\_KEY in your environment
5. Update your WebdriverIO config:

```
const isMacOS = process.platform === 'darwin';



export const config = {

  services: [['@wdio/tauri-service', {

    driverProvider: 'crabnebula',  // Works on all platforms

    // On macOS, also needs CN_API_KEY and automation plugin

  }]]

};
```

Or conditionally use different providers:

```
const driverProvider = process.env.DRIVER_PROVIDER || 

  (process.platform === 'darwin' ? 'embedded' : 'official');



export const config = {

  services: [['@wdio/tauri-service', {

    driverProvider,

  }]]

};
```

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

| Feature         | `official` | `crabnebula` | `embedded` |
| --------------- | ---------- | ------------ | ---------- |
| Windows         | ✅         | ✅           | ✅         |
| Linux           | ✅         | ✅           | ✅         |
| macOS           | ❌         | ✅           | ✅         |
| External driver | Yes        | Yes          | No         |
| API key         | No         | macOS only   | No         |
| Plugin required | No         | macOS only   | Yes        |
| Cost            | Free       | Subscription | Free       |

**Recommendation**: Use `embedded` for the simplest cross-platform setup. Use `crabnebula` if you already have a subscription or need specific features.

## Getting Help[​](#getting-help "Direct link to Getting Help")

* **CrabNebula Documentation**: <https://docs.crabnebula.dev/tauri/webdriver/>
* **CrabNebula Support**: Contact via their website for API key and support
* **WebdriverIO Issues**: Report integration issues to the [desktop-mobile repository](https://github.com/webdriverio/desktop-mobile/issues)
* **Troubleshooting Guide**: See [troubleshooting.md](/docs/desktop-testing/tauri/troubleshooting.md) for common issues
