Skip to content

crabnebula-setup.md

Latest commit

 

History

History
471 lines (342 loc) · 11.2 KB

crabnebula-setup.md

File metadata and controls

471 lines (342 loc) · 11.2 KB

CrabNebula Setup Guide

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

Overview

CrabNebula'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 Supported Requirements
Windows ✅ Yes @crabnebula/tauri-driver
Linux ✅ Yes @crabnebula/tauri-driver + webkit2gtk-driver
macOS ✅ Yes @crabnebula/tauri-driver + CN_API_KEY

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

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

All Platforms

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

Linux Only

macOS Only

  1. CrabNebula account with API key (contact CrabNebula for access)
  2. tauri-plugin-automation installed in your Tauri app

Installation

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

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)

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

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

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

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

Windows

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

Linux

  • Requires webkit2gtk-driver (see installation above)
  • For headless CI, use Xvfb: 
    xvfb-run -a npm run wdio

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

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)

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

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

Solution: Install the package:

npm install -D @crabnebula/tauri-driver

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

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)

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

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

Custom Backend Port (macOS)

If port 3000 is already in use:

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

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

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

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

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