CrabNebula Tauri Driver

End-to-end testing for Tauri apps via Webdriver.

@crabnebula/tauri-driver acts as a bridge between the Webdriver client defining the integration tests and the target platform's Webdriver implementation.

Currently supported platforms:

• macOS via CrabNebula Webdriver for Tauri
• Linux via webkit2gtk-driver or the CrabNebula Webdriver
• Windows via msedgedriver or the CrabNebula Webdriver

Prerequisites

• macOS: Your Tauri app must have the tauri-plugin-automation plugin installed in order to run integration tests on macOS
• Linux: webkit2gtk-driver must be installed in your system and available in the PATH
• Windows: msedgedriver.exe must be installed in your system and available in the PATH

Alternatively for Linux and Windows you can also use tauri-plugin-automation and configure your test to execute the test runner backend.

Installation

Install with your favorite package manager:

npm install --save-dev @crabnebula/tauri-driver
yarn install -D @crabnebula/tauri-driver
pnpm install -D @crabnebula/tauri-driver

Additionally you should install @crabnebula/test-runner-backend if you wish to run macOS tests locally, and @crabnebula/webdriverio-cloud-reporter to upload test results to CrabNebula Cloud.

Usage

WebdriverIO

Let's define a WebdriverIO configuration that starts tauri-driver so it can run your integration tests.

1. Import packages

import path from"path";
import { spawn, spawnSync } from "child_process";
import { CrabNebulaCloudReporter } from "@crabnebula/webdriverio-cloud-reporter";
import { waitTauriDriverReady } from "@crabnebula/tauri-driver";
import { waitTestRunnerBackendReady } from "@crabnebula/test-runner-backend";

2. Set your application path

For macOS you can optionally use the .app bundle instead of just your app executable.

const applicationPath = process.platform === "darwin"
  ? "path/to/src-tauri/target/debug/bundle/macos/<app-name>.app"
  : process.platform === "win32"
  ? "path/to/src-tauri/target/debug/<app-name>.exe"
  : "path/to/src-tauri/target/debug/<app-name>"

Note that you must use the proper target folder path relative to your WebdriverIO configuration file and replace <app-name> with the correct values.

3. Create global variables

// keep track of the `tauri-driver` child process
let tauriDriver;
let killedTauriDriver = false;
// keep track of the `test-runner-backend` child process
let testRunnerBackend;
let killedTestRunnerBackend = false;

4. Define the WebdriverIO configuration

Note that this example assumes you are using pnpm, please adjust the scripts if you are using a different package manager.

exports.config = {
  host: "127.0.0.1",
  port: 4444,
  specs: ["./test/specs/**/*.js"],
  maxInstances: 1,

  capabilities: [
    {
      maxInstances: 1,
      "tauri:options": {
        application: applicationPath,
      },
    },
  ],
  reporters: [CrabNebulaCloudReporter],
  framework: "mocha",
  mochaOpts: {
    ui: "bdd",
    timeout: 60000,
  },
  connectionRetryCount: 0,

  onPrepare: async () => {
    // ensure the Tauri app is built since we expect this binary to exist for the webdriver sessions
    spawnSync("pnpm", ["tauri", "build", "--debug"], {
      cwd: path.resolve(__dirname, "path/to/src-tauri"), // TODO: use actual path to the Tauri app directory
      stdio: "inherit",
      shell: true,
    });

    // skip this if condition to use the CrabNebula Webdriver on all platforms
    if (process.platform === "darwin") {
      // CN_API_KEY is required to run macOS tests via CrabNebula Webdriver for Tauri
      if (!process.env.CN_API_KEY) {
        console.error(
          "CN_API_KEY is not set, required for CrabNebula Webdriver"
        );
        process.exit(1);
      }

      testRunnerBackend = spawn("pnpm", ["test-runner-backend"], {
        stdio: "inherit",
        shell: true,
      });

      testRunnerBackend.on("error", (error) => {
        console.error("test-runner-backend error:", error);
        process.exit(1);
      });
      testRunnerBackend.on("exit", (code) => {
        if (!killedTestRunnerBackend) {
          console.error("test-runner-backend exited with code:", code);
          process.exit(1);
        }
      });

      await waitTestRunnerBackendReady();

      // instruct tauri-driver to connect to the test-runner-backend
      process.env.REMOTE_WEBDRIVER_URL = `http://127.0.0.1:3000`;
    }
  },

  // ensure we are running `tauri-driver` before the session starts so that we can proxy the webdriver requests
  beforeSession: async () => {
    tauriDriver = spawn("pnpm", ["tauri-driver"], {
      stdio: [null, process.stdout, process.stderr],
      shell: true,
    });
    tauriDriver.on("error", (error) => {
      console.error("tauri-driver error:", error);
      process.exit(1);
    });
    tauriDriver.on("exit", (code) => {
      if (!killedTauriDriver) {
        console.error("tauri-driver exited with code:", code);
        process.exit(1);
      }
    });

    // wait for tauri-driver to initialize its proxy server
    await waitTauriDriverReady();
  },

  // clean up the `tauri-driver` process we spawned at the start of the session
  afterSession: () => {
    closeTauriDriver();
  },

  onComplete: () => {
    killedTestRunnerBackend = true;
    testRunnerBackend?.kill();
  },
};

function closeTauriDriver() {
  killedTauriDriver = true;
  tauriDriver?.kill();
  killedTestRunnerBackend = true;
  testRunnerBackend?.kill();
}

export function onShutdown(fn) {
  const cleanup = () => {
    try {
      fn();
    } finally {
      process.exit();
    }
  };

  process.on("exit", cleanup);
  process.on("SIGINT", cleanup);
  process.on("SIGTERM", cleanup);
  process.on("SIGHUP", cleanup);
  process.on("SIGBREAK", cleanup);
}

onShutdown(closeTauriDriver);