tauri-test-cli

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

Manual prerequisite installation

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]" "[e-mail]"
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]" "[e-mail]"

# 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":"[e-mail]"}'
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