---
name: nomo-e2e
description: Cross-platform WebView E2E testing framework supporting CDP and WebDriver protocols. Invoke when testing Electron apps, Tauri2 apps, or any WebView-based desktop application.
allowed-tools: Bash(nomo-e2e:*)
---

# NomoE2E Testing Framework

## Core Design Principles

### 1. Session Persistence

CLI commands are independent processes. Sessions are persisted to `~/.nomo-e2e/sessions.json` and auto-reconnected:

```bash
# Create session (saved to file)
nomo-e2e open http://localhost:9222

# Commands reuse the session automatically
nomo-e2e click "#button"
nomo-e2e screenshot
```

### 2. Structured Output

All commands output JSON for LLM consumption. Avoid large data (screenshots, HTML) in output:

```bash
# Good: JSON with metadata
nomo-e2e screenshot
# Output:
# {
#   "status": "success",
#   "path": "./screenshots/screenshot.png",
#   "size_kb": 120.8
# }

# Bad: Base64 image in output
# Output: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
```

### 3. Token Efficiency

Do not force page data into LLM context. Use references and metadata:

```bash
# Capture snapshot to see elements
nomo-e2e snapshot
# Output:
# {
#   "status": "success",
#   "url": "http://localhost:9222",
#   "elements": [
#     {"ref": "e1", "tag": "button", "text": "Login"},
#     {"ref": "e2", "tag": "input", "text": "Username"}
#   ],
#   "element_count": 25
# }
```

### 4. Protocol-Aware

CDP and WebDriver protocols have different capabilities. Some commands require CDP:

| Command Type | CDP | WebDriver |
|--------------|-----|-----------|
| Basic (click, type, fill) | ✅ | ✅ |
| Storage (cookies, localStorage) | ✅ | ✅ |
| Advanced (hover, press, drag) | ✅ | ❌ |
| DevTools (console, network, pdf) | ✅ | ❌ |

## Quick Start

### Installation

```bash
# Install from source
pip install -e .

# Install Playwright browsers
playwright install chromium
```

### Basic Usage with Electron (CDP)

```bash
# Connect to Electron
nomo-e2e open http://localhost:9222

# Take snapshot to see elements
nomo-e2e snapshot

# Interact with page
nomo-e2e click "#login-button"
nomo-e2e type-text "admin"
nomo-e2e screenshot

# Disconnect
nomo-e2e close
```

### Basic Usage with Tauri2 (WebDriver)

```bash
# Connect to Tauri2
nomo-e2e open --driver webdriver http://localhost:4445

# Basic interactions work
nomo-e2e click "button.submit"
nomo-e2e eval "document.title"

# Advanced interactions (hover, drag, etc.) show friendly error
nomo-e2e hover "#dropdown"
# Error: Advanced interactions not supported by WebDriver protocol
```

## Architecture

The framework uses a protocol adapter pattern to support both CDP and WebDriver:

```
CLI Commands (open, click, snapshot, ...)
        ↓
Session Manager (persistence + auto-reconnect)
        ↓
WebViewController (unified API)
        ↓
CdpAdapter | WebDriverAdapter
        ↓
Playwright Runtime
```

## Complete Command Reference

### Connection Management

```bash
# Open WebView connection
open <url> [--driver cdp|webdriver] [--session name]

# Close current connection
close

# List all sessions
list

# Close all sessions
close-all

# Show session status
status
```

### Navigation

```bash
# Navigate to URL
goto <url>

# Get current URL
url

# Get page title
title

# Reload page
reload

# Go back
go-back

# Go forward
go-forward
```

### Element Interaction

```bash
# Click element
click <selector> [--timeout ms]

# Type text (character by character)
type-text <text> [--delay ms]

# Fill input (clear + type)
fill <selector> <text>
```

### Screenshots & Snapshots

```bash
# Take screenshot
screenshot [--filename path] [--selector element]

# Capture snapshot (element list)
snapshot [--filename path]
```

### Script Execution

```bash
# Evaluate JavaScript
eval <script>
```

### Advanced Interaction (CDP only)

```bash
# Hover over element
hover <selector>

# Double-click element
dblclick <selector> [--timeout ms]

# Press key
press <key>           # Enter, Escape, Control+a, etc.

# Key down/up
keydown <key>
keyup <key>

# Select dropdown option
select <selector> <value>

# Check/uncheck
check <selector>
uncheck <selector>

# Mouse operations
mousemove <x> <y>
mousedown [x y] [--button left|right|middle]
mouseup [--button left|right|middle]
mousewheel <dx> <dy>

# File upload
upload <selector> <file_path>

# Drag and drop
drag <source_selector> <target_selector>
```

### Cookies & Storage

```bash
# Cookie operations
cookie-get [name]
cookie-set <name> <value> [--domain domain] [--path path]
cookie-delete <name>
cookie-clear

# localStorage operations
localstorage-list
localstorage-set <key> <value>
localstorage-delete <key>
localstorage-clear

# sessionStorage operations
sessionstorage-list
sessionstorage-set <key> <value>
sessionstorage-delete <key>
sessionstorage-clear

# Route patterns
route-list
```

### DevTools (CDP only)

```bash
# Console logs
console [level]          # all, error, warning, log, info, debug

# Clear console
console-clear

# Network requests
network [--limit n] [--url-pattern pattern]

# Generate PDF
pdf [filename]
```

### Session Management

```bash
# Save session state
state-save [filename]

# Load session state
state-load <filename>
```

### Configuration

```bash
# List all config
config-list [--format json|yaml]

# Get config value
config-get <key>

# Set config value
config-set <key> <value>
```

## Complete Command List

| Command | Description | Protocol |
|---------|-------------|----------|
| open | Connect to WebView | Both |
| close | Close connection | Both |
| list | List sessions | Both |
| close-all | Close all sessions | Both |
| status | Show session status | Both |
| goto | Navigate to URL | Both |
| url | Get current URL | Both |
| title | Get page title | Both |
| reload | Reload page | Both |
| go-back | Go back | Both |
| go-forward | Go forward | Both |
| click | Click element | Both |
| type-text | Type text | Both |
| fill | Fill input | Both |
| screenshot | Take screenshot | Both |
| snapshot | Capture snapshot | Both |
| eval | Evaluate JS | Both |
| hover | Hover element | CDP |
| dblclick | Double-click | CDP |
| press | Press key | CDP |
| keydown | Key down | CDP |
| keyup | Key up | CDP |
| select | Select option | CDP |
| check | Check checkbox | CDP |
| uncheck | Uncheck checkbox | CDP |
| mousemove | Move mouse | CDP |
| mousedown | Mouse down | CDP |
| mouseup | Mouse up | CDP |
| mousewheel | Mouse wheel | CDP |
| upload | File upload | CDP |
| drag | Drag and drop | CDP |
| cookie-get | Get cookies | Both |
| cookie-set | Set cookie | Both |
| cookie-delete | Delete cookie | Both |
| cookie-clear | Clear cookies | Both |
| localstorage-list | List localStorage | Both |
| localstorage-set | Set localStorage | Both |
| localstorage-delete | Delete localStorage | Both |
| localstorage-clear | Clear localStorage | Both |
| sessionstorage-list | List sessionStorage | Both |
| sessionstorage-set | Set sessionStorage | Both |
| sessionstorage-delete | Delete sessionStorage | Both |
| sessionstorage-clear | Clear sessionStorage | Both |
| route-list | List routes | Both |
| console | Console logs | CDP |
| console-clear | Clear console | CDP |
| network | Network requests | CDP |
| pdf | Generate PDF | CDP |
| state-save | Save state | Both |
| state-load | Load state | Both |
| config-list | List config | Both |
| config-get | Get config | Both |
| config-set | Set config | Both |

**Total: 54 commands**

## Common Workflows

### Login Flow

```bash
# Connect
nomo-e2e open http://localhost:9222  

# See elements
nomo-e2e snapshot

# Fill and submit
nomo-e2e fill "#username" "admin"
nomo-e2e fill "#password" "secret"
nomo-e2e click "#submit"

# Verify
nomo-e2e snapshot
nomo-e2e screenshot --filename success.png

# Disconnect
nomo-e2e close
```

### Multi-Session Testing

```bash
# Open named sessions
nomo-e2e open -s app1 http://localhost:9222
nomo-e2e open -s app2 http://localhost:4445

# Switch and interact
nomo-e2e -s app1 click "#button1"
nomo-e2e -s app2 click "#button2"

# Close all
nomo-e2e close-all
```

### Session Persistence

```bash
# Session 1: Login and save
nomo-e2e open http://localhost:9222
nomo-e2e click "#login"
nomo-e2e fill "#username" "admin"
nomo-e2e click "#submit"
nomo-e2e state-save ./auth.json
nomo-e2e close

# Session 2: Restore state
nomo-e2e open http://localhost:9222
nomo-e2e state-load ./auth.json
# Already logged in!
```

## Configuration

### Config Options

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| browser | str | "chromium" | Browser type |
| timeout_action | int | 30000 | Action timeout (ms) |
| timeout_navigation | int | 60000 | Navigation timeout (ms) |
| output_dir | str | "./screenshots" | Output directory |
| console_level | str | "info" | Console log level |
| snapshot_format | str | "yaml" | Snapshot format |
| auto_snapshot | bool | true | Auto snapshot after actions |
| test_id_attribute | str | "data-testid" | Test ID attribute |
| reference_prefix | str | "e" | Element reference prefix |
| max_snapshot_elements | int | 50 | Max elements in snapshot |

### Config Priority

1. Command line arguments
2. Runtime config (config-set)
3. Environment variables (WEBVIEW_*)
4. Config file (.webview-cli.json)
5. Default values

## Troubleshooting

### Connection Issues

```bash
# Check if WebView is running
curl http://localhost:9222/json

# Check port
lsof -i :9222
```

### Element Not Found

```bash
# Take snapshot to see elements
nomo-e2e snapshot

# Try longer timeout
nomo-e2e click "#element" --timeout 10000
```

### Protocol Error

If you see:
```
Advanced interactions not supported by WebDriver protocol
```

This command requires CDP. Either:
1. Use `--driver cdp` for Electron/WebView2
2. Use alternative commands (click instead of hover, etc.)

## Best Practices

1. **Always disconnect after use**
   ```bash
   nomo-e2e open http://localhost:9222
   # ... do testing ...
   nomo-e2e close
   ```

2. **Use snapshot to discover elements**
   ```bash
   nomo-e2e snapshot
   # Use returned refs (e1, e2, etc.) in subsequent commands
   ```

3. **Save session state for reuse**
   ```bash
   # After login, save state
   nomo-e2e state-save ./logged-in.json

   # In new session, restore
   nomo-e2e state-load ./logged-in.json
   ```

4. **Use named sessions for parallel testing**
   ```bash
   nomo-e2e open -s test1 http://localhost:9222
   nomo-e2e open -s test2 http://localhost:9222
   ```

## Detailed References

- **CLI API** [CLI-API.md](CLI-API.md) - Complete CLI command reference
- **Getting Started** [references/getting-started.md](references/getting-started.md)
- **CDP Protocol** [references/cdp-protocol.md](references/cdp-protocol.md)
- **WebDriver Protocol** [references/webdriver-protocol.md](references/webdriver-protocol.md)
- **Session Management** [references/session-management.md](references/session-management.md)
- **Test Generation** [references/test-generation.md](references/test-generation.md)
