tauri-playwright

Playwright E2E testing for Tauri desktop apps. Controls the real native webview (WKWebView, WebView2, WebKitGTK) with a Playwright-compatible API — auto-waiting, locator assertions, semantic selectors, network mocking, native screenshots, and video recording.

The Problem

Tauri apps use system webviews instead of Chromium. Playwright requires Chrome DevTools Protocol (CDP), but only WebView2 (Windows) supports it. Standard Playwright integration is impossible on macOS and Linux.

The Solution

Three testing modes from the same test files:

| Mode | Platform | How it works | |---|---|---| | browser | All | Headless Chromium with mocked Tauri IPC. Fast, CI-friendly. | | tauri | All | Socket bridge to the real Tauri webview. True E2E. | | cdp | Windows | Direct CDP to WebView2. Full native Playwright. |

┌──────────────────┐  socket/JSON  ┌──────────────────────────────────┐
│  Playwright       │◄────────────►│  tauri-plugin-playwright          │
│  test runner      │              │  (Rust, embedded in your app)     │
│                   │              │                                   │
│  @srsholmes/      │              │  Socket server → JS injection     │
│  tauri-playwright │              │  HTTP polling  ← JS results       │
└──────────────────┘              └──────────────────────────────────┘

Quick Start

1. Add the Rust plugin to your Tauri app

# src-tauri/Cargo.toml
[features]
e2e-testing = ["tauri-plugin-playwright"]

[dependencies]
tauri-plugin-playwright = { version = "0.1", optional = true }

// src-tauri/src/lib.rs
pub fn run() {
    let mut builder = tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![/* your commands */]);

    #[cfg(feature = "e2e-testing")]
    {
        builder = builder.plugin(tauri_plugin_playwright::init());
    }

    builder.run(tauri::generate_context!()).expect("error running app");
}

2. Install the npm package

pnpm add -D @srsholmes/tauri-playwright @playwright/test
npx playwright install chromium

3. Create test fixtures

// e2e/fixtures.ts
import { createTauriTest } from '@srsholmes/tauri-playwright';

export const { test, expect } = createTauriTest({
  devUrl: 'http://localhost:1420',
  ipcMocks: {
    greet: (args) => `Hello, ${(args as { name?: string })?.name}!`,
  },
  mcpSocket: '/tmp/tauri-playwright.sock',
});

4. Write tests

// e2e/tests/app.spec.ts
import { test, expect } from '../fixtures';

test('counter increments', async ({ tauriPage }) => {
  await tauriPage.click('[data-testid="btn-increment"]');
  await expect(tauriPage.locator('[data-testid="counter-value"]')).toContainText('1');
});

test('greets via Tauri IPC', async ({ tauriPage }) => {
  await tauriPage.fill('[data-testid="greet-input"]', 'World');
  await tauriPage.click('[data-testid="btn-greet"]');
  await expect(tauriPage.getByTestId('greet-result')).toContainText('Hello, World!');
});

5. Configure Playwright

// e2e/playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'browser-only',
      use: { ...devices['Desktop Chrome'], mode: 'browser' },
    },
    {
      name: 'tauri',
      use: { mode: 'tauri' },
    },
  ],
  webServer: {
    command: 'pnpm dev',
    port: 1420,
    reuseExistingServer: !process.env.CI,
  },
});

6. Run tests

# Browser mode (headless, no Tauri needed)
npx playwright test --project=browser-only

# Tauri mode (start the app first)
cargo tauri dev --features e2e-testing  # Terminal 1
npx playwright test --project=tauri      # Terminal 2

API Reference

Page Methods

All actions auto-wait for the element to be visible and enabled (default 5s timeout, configurable).

Interactions

await tauriPage.click(selector, { timeout? })
await tauriPage.dblclick(selector)
await tauriPage.hover(selector)
await tauriPage.fill(selector, text)
await tauriPage.type(selector, text)            // character by character
await tauriPage.press(selector, 'Enter')
await tauriPage.check(selector)
await tauriPage.uncheck(selector)
await tauriPage.selectOption(selector, value)
await tauriPage.focus(selector)
await tauriPage.blur(selector)
await tauriPage.dragAndDrop(source, target)
await tauriPage.dispatchEvent(selector, 'custom-event')

Queries (auto-wait for element)

const text = await tauriPage.textContent(selector)
const html = await tauriPage.innerHTML(selector)
const visible = await tauriPage.innerText(selector)
const value = await tauriPage.inputValue(selector)
const attr = await tauriPage.getAttribute(selector, name)
const box = await tauriPage.boundingBox(selector)
const css = await tauriPage.getComputedStyle(selector, 'color')
const all = await tauriPage.allTextContents(selector)

State Checks (instant, no waiting)

await tauriPage.isVisible(selector)     // false if not found
await tauriPage.isHidden(selector)
await tauriPage.isChecked(selector)
await tauriPage.isDisabled(selector)
await tauriPage.isEnabled(selector)
await tauriPage.isEditable(selector)
await tauriPage.isFocused(selector)
await tauriPage.count(selector)         // 0 if none found

Navigation

await tauriPage.goto(url)
await tauriPage.reload()
await tauriPage.goBack()
await tauriPage.goForward()
await tauriPage.waitForURL('/dashboard')
const title = await tauriPage.title()
const url = await tauriPage.url()
const html = await tauriPage.content()

Waiting

await tauriPage.waitForSelector(selector, timeout?)
await tauriPage.waitForFunction('document.readyState === "complete"', timeout?)
await tauriPage.waitForURL('/dashboard', { timeout: 10000 })

Evaluate

const result = await tauriPage.evaluate<number>('window.innerWidth')

Semantic Selectors

tauriPage.getByTestId('submit')
tauriPage.getByText('Hello World')
tauriPage.getByRole('button', { name: 'Submit' })
tauriPage.getByLabel('Email')
tauriPage.getByPlaceholder('Enter name')
tauriPage.getByAltText('Logo')
tauriPage.getByTitle('Close')

Locator API

const locator = tauriPage.locator('[data-testid="list"]')

// Actions
await locator.click()
await locator.fill('text')
await locator.press('Enter')
await locator.clear()
await locator.pressSequentially('hello', { delay: 50 })
await locator.dispatchEvent('input')

// Queries
await locator.textContent()
await locator.innerText()
await locator.inputValue()
await locator.getAttribute('href')
await locator.evaluate('(el) => el.dataset.custom')

// State
await locator.isVisible()
await locator.isChecked()
await locator.isFocused()

// Refinement
locator.nth(2)
locator.first()
locator.last()
locator.filter({ hasText: 'Active' })
await locator.all()            // returns array of locators

// Nesting
locator.locator('.child')
locator.getByTestId('item')
locator.getByText('Click me')

// Scrolling
await locator.scrollIntoViewIfNeeded()

Assertions

Custom expect matchers with auto-retry (default 5s timeout):

// Visibility
await expect(locator).toBeVisible()
await expect(locator).toBeHidden()
await expect(locator).not.toBeVisible()

// Content
await expect(locator).toContainText('Hello')
await expect(locator).toContainText(/hello/i)    // regex
await expect(locator).toHaveText('Hello World')  // exact match

// Form state
await expect(locator).toHaveValue('test')
await expect(locator).toBeChecked()
await expect(locator).toBeEnabled()
await expect(locator).toBeDisabled()
await expect(locator).toBeEditable()
await expect(locator).toBeFocused()
await expect(locator).toBeEmpty()

// Attributes
await expect(locator).toHaveAttribute('type', 'text')
await expect(locator).toHaveClass('active')
await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)')
await expect(locator).toHaveId('main')

// Collections
await expect(locator).toHaveCount(5)
await expect(locator).toBeAttached()

// Page-level
await expect(tauriPage).toHaveURL('/dashboard')
await expect(tauriPage).toHaveTitle('My App')

Keyboard & Mouse

// Keyboard
await tauriPage.keyboard.press('Enter')
await tauriPage.keyboard.press('Control+A')
await tauriPage.keyboard.type('hello world', { delay: 50 })
await tauriPage.keyboard.down('Shift')
await tauriPage.keyboard.up('Shift')

// Mouse
await tauriPage.mouse.click(100, 200)
await tauriPage.mouse.click(100, 200, { button: 'right' })
await tauriPage.mouse.dblclick(100, 200)
await tauriPage.mouse.move(300, 400)
await tauriPage.mouse.wheel(0, 100)

Network Mocking

// Mock an API endpoint
await tauriPage.route('/api/users', {
  status: 200,
  body: JSON.stringify({ users: ['Alice', 'Bob'] }),
  contentType: 'application/json',
});

// Click a button that fetches from the mocked endpoint
await tauriPage.click('[data-testid="fetch-btn"]');
await expect(tauriPage.getByTestId('user-0')).toContainText('Alice');

// Verify network requests were captured
const requests = await tauriPage.getNetworkRequests();
expect(requests.find(r => r.url.includes('/api/users'))).toBeTruthy();

// Clean up
await tauriPage.unroute('/api/users');
await tauriPage.clearRoutes();

Dialog Handling

await tauriPage.installDialogHandler({
  defaultConfirm: true,
  defaultPromptText: 'Claude',
});

await tauriPage.click('[data-testid="btn-confirm"]');

const dialogs = await tauriPage.getDialogs();
expect(dialogs[0].type).toBe('confirm');
expect(dialogs[0].message).toBe('Are you sure?');

File Upload

await tauriPage.setInputFiles('[data-testid="file-input"]', [
  { name: 'test.txt', mimeType: 'text/plain', buffer: Buffer.from('hello') },
]);

Screenshots & Video

// Native screenshot (CoreGraphics on macOS — captures real window with title bar)
const png = await tauriPage.screenshot();
await tauriPage.screenshot({ path: '/tmp/screenshot.png' });

// Video recording (native frame capture → ffmpeg → MP4)
await tauriPage.startRecording({ path: '/tmp/recording', fps: 15 });
// ... run test actions ...
const result = await tauriPage.stopRecording();
console.log(result.video); // '/tmp/recording/video.mp4'

The fixture automatically records video and captures screenshots on failure, attaching them to the Playwright HTML report.

IPC Mocking (Browser Mode)

Mock any Tauri invoke() command, including plugin commands:

createTauriTest({
  devUrl: 'http://localhost:1420',
  ipcMocks: {
    greet: (args) => `Hello, ${args?.name}!`,
    get_config: () => ({ theme: 'dark', lang: 'en' }),
    'plugin:fs|read': () => 'file contents',
    'plugin:dialog|open': () => '/path/to/file',
  },
});

Assert which IPC commands were called:

import { getCapturedInvokes, clearCapturedInvokes } from '@srsholmes/tauri-playwright';

const calls = await getCapturedInvokes(tauriPage);
expect(calls).toContainEqual(
  expect.objectContaining({ cmd: 'greet', args: { name: 'World' } })
);

Plugin Configuration

use tauri_plugin_playwright::PluginConfig;

// Default: Unix socket at /tmp/tauri-playwright.sock
builder = builder.plugin(tauri_plugin_playwright::init());

// Custom socket path + TCP fallback
builder = builder.plugin(tauri_plugin_playwright::init_with_config(
    PluginConfig::new()
        .socket_path("/tmp/my-app-pw.sock")
        .tcp_port(6274)
));

CDP Mode (Windows)

On Windows, WebView2 supports Chrome DevTools Protocol for full native Playwright:

# Launch with CDP enabled
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS="--remote-debugging-port=9222" cargo tauri dev

// Playwright config
{
  name: 'cdp',
  use: { mode: 'cdp' },
}

// Fixture config
createTauriTest({
  cdpEndpoint: 'http://localhost:9222',
  // ...
});

Example App

See examples/hello-world/ for a complete working example with:

• React frontend with counter, greet (Tauri IPC), todo list, modal, file upload, dialogs, drag & drop, API fetch
• Rust backend with greet command + playwright plugin
• 67 E2E tests across 10 spec files covering every API method
• 127 unit tests for the TypeScript library
• Playwright config with browser-only and Tauri projects

Requirements

• Tauri 2.0 with "withGlobalTauri": true in tauri.conf.json
• Node.js 18+
• Rust toolchain (for Tauri mode)
• ffmpeg (optional, for video stitching)
• Screen recording permission on macOS (for native screenshots)

CI/CD

GitHub Actions workflow included (.github/workflows/e2e.yml):

# Browser-only tests run on ubuntu (fast, headless)
npx playwright test --project=browser-only

# Tauri tests run on macOS (real app, native screenshots)
npx playwright test --project=tauri

Test results, HTML reports, and videos are uploaded as artifacts.

License

MIT