tauri-test-cli

CLI for testing Tauri applications with screenshot capture, DOM inspection, and user interaction simulation. Designed for use by AI agents (like Claude Code) to automate testing of Tauri desktop apps.

Quick Start

# Install globally
npm install -g tauri-test-cli

# Install tauri-driver (required)
tauri-test-cli setup

# Check dependencies
tauri-test-cli check-deps

# Start server and test your app
tauri-test-cli server --app ./target/debug/my-app &
tauri-test-cli screenshot --output /tmp/screen.png
tauri-test-cli click "button.submit"

Installation

Global Install via npm

npm install -g tauri-test-cli
# or
bun install -g tauri-test-cli
# or
pnpm install -g tauri-test-cli

# Then install tauri-test
tauri-test-cli setup

Using Pixi (Recommended for Development)

Pixi handles all system-level dependencies automatically (WebKit, GTK, Rust).

# Clone and install
git clone https://github.com/lllangWV/tauri-test-cli
cd tauri-test-cli
pixi install

# Build the CLI
pixi run build

# Run commands via pixi
pixi run dev server --app ./target/debug/my-app

Prerequisites

The CLI will check for missing dependencies and provide install instructions:

tauri-test-cli check-deps

Linux

# WebKit (required)
sudo apt install libwebkit2gtk-4.1-dev    # Debian/Ubuntu
sudo dnf install webkit2gtk4.1-devel       # Fedora
sudo pacman -S webkit2gtk-4.1              # Arch

# Rust and tauri-test
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
tauri-test-cli setup

macOS

WebKit is included in macOS. Just install tauri-driver:

tauri-test-cli setup

Windows

WebView2 is included in Windows 10/11. Just install tauri-driver:

tauri-test-cli setup

Usage

Server Mode (Recommended)

Start a persistent HTTP server - send commands anytime via HTTP.

# Start server
tauri-test-cli server --app ./target/debug/my-app &

# Send commands
curl -s http://127.0.0.1:9222 -d '{"cmd":"click","selector":"button"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"screenshot","output":"/tmp/screen.png"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"snapshot"}'

# Check status
curl -s http://127.0.0.1:9222/status

# Stop server
tauri-test-cli stop

Virtual Display Mode (Linux)

Run in a virtual display to avoid focus-related throttling:

# Using built-in --xvfb flag (recommended)
tauri-test-cli server --app ./target/debug/my-app --xvfb &

# Or manually with Xvfb
Xvfb :99 -screen 0 1920x1080x24 &
DISPLAY=:99 tauri-test-cli server --app ./target/debug/my-app &

Client Mode (CLI without --app)

Once the server is running, you can use CLI commands directly - no --app needed, no curl required:

# Start server once
tauri-test-cli server --app ./target/debug/my-app &

# Run commands - they automatically connect to the server!
tauri-test-cli click "button.submit"
tauri-test-cli type "input[name=email]" "[email protected]"
tauri-test-cli screenshot --output /tmp/screen.png
tauri-test-cli snapshot --output /tmp/dom.yaml
tauri-test-cli eval "document.title"
tauri-test-cli wait ".modal" --gone --timeout 5000

# Check server status
tauri-test-cli status

# Stop when done
tauri-test-cli stop

Use --port to connect to a different server:

tauri-test-cli click "button" --port 8080

Why Server Mode?

• No startup delay: App stays running between commands
• Simple CLI or HTTP API: Use CLI commands or curl/fetch
• Instant execution: No auto-wait delay by default

Commands

Testing Commands

| Command | Required Fields | Optional Fields | |---------|----------------|-----------------| | click | selector | timeout | | type | selector, text | timeout | | screenshot | - | output, fullPage | | snapshot | - | output | | eval | script | - | | wait | selector | timeout, gone |

Utility Commands

| Command | Description | |---------|-------------| | tauri-test-cli setup | Install tauri-driver via cargo | | tauri-test-cli status [--port] | Check if a server is running | | tauri-test-cli stop [--port] | Stop a running server | | tauri-test-cli cleanup | Kill stale WebDriver processes | | tauri-test-cli check-deps | Check system dependencies |

Examples

Using CLI (recommended):

# Click a button
tauri-test-cli click "button.submit"

# Type into an input
tauri-test-cli type "input[name=email]" "[email protected]"

# Take screenshot
tauri-test-cli screenshot --output /tmp/screen.png

# Get DOM snapshot (accessibility tree in YAML format)
tauri-test-cli snapshot --output /tmp/dom.yaml

# Execute JavaScript
tauri-test-cli eval "document.title"

# Wait for element to disappear
tauri-test-cli wait ".modal" --gone --timeout 5000

Using curl:

curl -s http://127.0.0.1:9222 -d '{"cmd":"click","selector":"button.submit"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"type","selector":"input[name=email]","text":"[email protected]"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"screenshot","output":"/tmp/screen.png"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"snapshot","output":"/tmp/dom.yaml"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"eval","script":"document.title"}'
curl -s http://127.0.0.1:9222 -d '{"cmd":"wait","selector":".modal","gone":true,"timeout":5000}'

Server Response Format

{"success": true, "result": {"path": "/tmp/screen.png", "width": 1280, "height": 720}}

On error:

{"success": false, "error": "Element not found: .missing"}

Batch Mode

For single-invocation workflows with multiple commands:

echo '[
  {"cmd":"click","selector":"button"},
  {"cmd":"screenshot","output":"/tmp/result.png"}
]' | tauri-test-cli batch --app ./target/debug/my-app --json

Single Commands

Each command starts a fresh session (slower but simpler):

tauri-test-cli screenshot --app ./target/debug/my-app --output /tmp/screen.png
tauri-test-cli click "button#submit" --app ./target/debug/my-app
tauri-test-cli snapshot --app ./target/debug/my-app

Using with Claude Code

This CLI is designed for AI agents. Add this to your project's CLAUDE.md:

## Testing Tauri Apps

Use `tauri-test-cli` for testing the Tauri application.

### Start test server
tauri-test-cli server --app ./target/debug/my-app --xvfb &

### Available commands (once server is running, no --app needed)
- Click: `tauri-test-cli click "button"`
- Type: `tauri-test-cli type "input" "hello"`
- Screenshot: `tauri-test-cli screenshot --output /tmp/screen.png`
- Snapshot: `tauri-test-cli snapshot --output /tmp/dom.yaml`
- Eval: `tauri-test-cli eval "document.title"`
- Wait: `tauri-test-cli wait ".element" --timeout 5000`

### Check server status
tauri-test-cli status

### Stop server
tauri-test-cli stop

Development

Setup

# Clone and install dependencies
git clone https://github.com/lllangWV/tauri-test-cli
cd tauri-test-cli
pixi install

# Build the CLI
pixi run build

# Build the test app (required for integration tests)
pixi run test-app-build

Running Tests

# Run all tests (builds test app automatically)
pixi run test-all

# Run only unit tests (fast, no test app needed)
pixi run test-unit

# Run only integration tests (requires test app)
pixi run test-integration

# Watch mode for development
pixi run test-watch

Test Structure

| Test File | Description | Count | |-----------|-------------|-------| | src/cli.test.ts | Arg parsing, batch command validation | 50 | | src/checks.test.ts | Dependency checking | 20 | | src/commands/utils.test.ts | Utility functions | 6 | | src/integration.test.ts | End-to-end tests against test app | 30 |

Test App

A minimal Tauri test app is included in apps/test-app/ for integration testing:

# Build the test app
pixi run test-app-build

# Run the test app manually
pixi run test-app-run

# Start tauri-test-cli server with test app
pixi run test-server

Available Pixi Tasks

pixi task list   # Show all available tasks

Key development tasks:

• pixi run build - Build the CLI
• pixi run dev - Run CLI in development mode
• pixi run typecheck - Run TypeScript type checking
• pixi run test-all - Run all tests
• pixi run test-server - Start server with test app

Benchmarks (Claude Code Headless Testing)

Run Claude Code in headless mode to test the CLI and measure performance:

# List available benchmark tasks
pixi run benchmark-list

# Run a single benchmark with visualization
pixi run benchmark -v screenshot

# Run all benchmarks
pixi run benchmark-all

# Run all benchmarks quietly (timing only)
pixi run benchmark-all-quiet

# Run with different models
pixi run benchmark-opus      # Claude Opus
pixi run benchmark-haiku     # Claude Haiku
MODEL=sonnet pixi run benchmark-all  # Explicit model

Available Benchmark Tasks

| Task | Description | |------|-------------| | screenshot | Take a screenshot | | click | Click a button and verify | | type | Type text into input | | snapshot | Get DOM snapshot | | eval | Execute JavaScript | | wait | Wait for elements | | form-fill | Fill and submit form | | full-workflow | Complete end-to-end test |

Benchmark Results

Results are saved to benchmarks/results/ with:

• Individual task JSON files with timing and token usage
• Summary JSON with all results from a run

Example output:

{
  "task": "screenshot",
  "model": "sonnet",
  "status": "passed",
  "duration_seconds": 12.5,
  "tokens": {
    "input": 1234,
    "output": 567,
    "cache_read": 890,
    "cache_create": 0
  }
}

Troubleshooting

"Maximum number of active sessions" Error

tauri-test-cli cleanup

Server won't start

tauri-test-cli stop
tauri-test-cli cleanup

Missing dependencies

tauri-test-cli check-deps
tauri-test-cli setup  # Install tauri-test

Window focus issues (slow commands)

Use the --xvfb flag to run in a virtual display:

tauri-test-cli server --app ./target/debug/my-app --xvfb &

CLI Reference

tauri-test-cli - CLI for testing Tauri applications

USAGE:
  tauri-test-cli <command> [options]

  When --app is omitted, commands connect to a running server (client mode).

COMMANDS:
  server [--port <port>] [--xvfb]   Start HTTP server for persistent sessions
  screenshot [--output <path>]      Take a screenshot
  snapshot [--output <path>]        Get DOM/accessibility tree snapshot
  click <selector>                  Click an element
  type <selector> <text>            Type text into an element
  wait <selector>                   Wait for an element
  eval <script>                     Execute JavaScript
  batch                             Execute multiple commands from stdin
  status [--port <port>]            Check if a server is running
  stop [--port <port>]              Stop a running server
  cleanup                           Kill stale WebDriver processes
  setup                             Install tauri-driver via cargo
  check-deps                        Check system dependencies

OPTIONS:
  --app <path>      Path to Tauri app binary (required for server/batch)
  --port <port>     Port for server/client mode (default: 9222)
  --xvfb            Run server in virtual display (Linux)
  --json            Output results as JSON
  --help, -h        Show help

License

MIT