# Getting Started with nomo-e2e

Complete guide to set up and run your first WebView E2E test.

## Prerequisites

- Python 3.8+
- Node.js 18+ (for Electron development)
- Rust 1.70+ (for Tauri2 development)
- Playwright installed

## Installation

### Option 1: Using uv (Recommended)

```bash
# Install as a global CLI tool (like npm i -g)
uv tool install -e .

# Or install from PyPI (when published)
uv tool install nomo-e2e

# Verify installation
nomo-e2e --help
```

### Option 2: Using pip

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

# Or install from PyPI (when published)
pip install nomo-e2e
```

### Option 3: Install Playwright Browsers

```bash
# Required for CDP/WebDriver connection
playwright install chromium
```

## Quick Start by Platform

### 1. Electron App (CDP Protocol)

**Step 1: Enable CDP in your Electron app**

```javascript
// main.js
const { app, BrowserWindow } = require('electron');

app.whenReady().then(() => {
  const win = new BrowserWindow({
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true
    }
  });

  // Enable remote debugging
  win.loadURL('http://localhost:3000');

  // Add CDP debugging port
  app.commandLine.appendSwitch('remote-debugging-port', '9222');
});
```

**Step 2: Start your Electron app**

```bash
# In your Electron project directory
npm start
# or
electron .
```

**Step 3: Run E2E test**

```bash
# Connect to Electron (auto-detects CDP for localhost:9222)
nomo-e2e open http://localhost:9222

# Take a snapshot to see elements
nomo-e2e snapshot

# Interact with elements
nomo-e2e click "#login"
nomo-e2e type-text "admin"
nomo-e2e fill "#password" "secret123"
nomo-e2e click "#submit"

# Take screenshot
nomo-e2e screenshot --filename login-success.png

# Disconnect
nomo-e2e close
```

### 2. Tauri2 App (WebDriver Protocol)

**Step 1: Add WebDriver capability**

```bash
# In your Tauri2 project
cargo tauri add webdriver
```

**Step 2: Configure capabilities**

```json
// src-tauri/capabilities/default.json
{
  "identifier": "default",
  "description": "Default capability",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "webdriver:default"
  ]
}
```

**Step 3: Start Tauri in dev mode**

```bash
# Tauri2 starts WebDriver on port 4445 by default
cargo tauri dev
```

**Step 4: Run E2E test**

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

# Basic interactions work
nomo-e2e click "button.submit"
nomo-e2e fill "input[name=email]" "user@example.com"
nomo-e2e screenshot

# Note: Advanced interactions (hover, drag, etc.) show friendly error for WebDriver

# Disconnect
nomo-e2e close
```

### 3. Edge Browser (CDP Protocol)

Edge supports CDP like Chrome:

```bash
# Start Edge with remote debugging
microsoft-edge --remote-debugging-port=9222

# Connect (auto-detects CDP)
nomo-e2e open http://localhost:9222
```

## Programmatic Usage

### Python API

```python
from nomo_e2e import WebViewController

# Auto-detect protocol (CDP for localhost:9222, WebDriver otherwise)
controller = WebViewController.connect("http://localhost:9222/json")

# Or specify protocol
controller = WebViewController.connect(
    "http://localhost:9222/json",
    driver="cdp"  # or "webdriver"
)

# Click element
controller.click("#login-button")

# Type text
controller.type_text("#username", "admin")

# Wait for element
controller.wait_for_selector("#dashboard", timeout_ms=5000)

# Take screenshot
controller.screenshot("./result.png")

# Execute JavaScript
title = controller.execute_script("return document.title")

# Disconnect
controller.disconnect()
```

### Context Manager

```python
from nomo_e2e import WebViewController

# Automatic cleanup
with WebViewController.connect("http://localhost:9222/json") as controller:
    controller.click("#login")
    controller.type_text("#username", "admin")
    controller.screenshot("./login.png")
# Automatically disconnected
```

### Test Integration

```python
import pytest
from nomo_e2e import WebViewController

def test_login_flow():
    controller = WebViewController.connect("http://localhost:9222/json")

    try:
        # Perform login
        controller.type_text("#username", "admin")
        controller.type_text("#password", "secret")
        controller.click("#submit")

        # Verify success
        controller.wait_for_selector("#dashboard")
        assert "dashboard" in controller.get_url()

    finally:
        controller.disconnect()
```

## Common Workflows

### Form Submission

```bash
# Connect and see elements
nomo-e2e open http://localhost:9222
nomo-e2e snapshot

# Fill form
nomo-e2e fill "#email" "user@example.com"
nomo-e2e fill "#password" "password123"
nomo-e2e fill "#confirm" "password123"

# Submit
nomo-e2e click "button[type=submit]"

# Verify
nomo-e2e screenshot --filename form-submitted.png

nomo-e2e close
```

### Session Persistence

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

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

### Advanced Interaction (CDP only)

```bash
# Connect with CDP (auto-detected)
nomo-e2e open http://localhost:9222
nomo-e2e snapshot

# Advanced interactions (CDP only)
nomo-e2e hover "#dropdown-menu"
nomo-e2e select "select#country" "US"
nomo-e2e check "#agree-terms"
nomo-e2e press Enter
nomo-e2e drag "#source" "#target"

# Take screenshot
nomo-e2e screenshot --filename advanced.png

nomo-e2e close
```

### DevTools (CDP only)

```bash
# Connect with CDP (auto-detected)
nomo-e2e open http://localhost:9222

# Get console logs
nomo-e2e console
nomo-e2e console error

# Clear console
nomo-e2e console-clear

# Get network requests
nomo-e2e network
nomo-e2e network --url-pattern "api/*"

# Generate PDF
nomo-e2e pdf --filename report.pdf

nomo-e2e close
```

## Troubleshooting

### Connection Refused

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

# For Electron, ensure remote debugging is enabled
# app.commandLine.appendSwitch('remote-debugging-port', '9222')

# For Tauri2, ensure webdriver plugin is installed
# cargo tauri add webdriver
```

### Protocol Mismatch

```bash
# If you see 404 errors:
# - CDP endpoints (localhost:9222) auto-detected as CDP
# - WebDriver endpoints need --driver webdriver flag

# Force CDP
nomo-e2e open --driver cdp http://localhost:9222

# Force WebDriver
nomo-e2e open --driver webdriver http://localhost:4445
```

### Session Persistence

```bash
# Sessions are saved to ~/.nomo-e2e/sessions.json

# List all sessions
nomo-e2e list

# Switch session
nomo-e2e open -s my-session http://localhost:9222

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

## See Also

- [CDP Protocol Reference](references/cdp-protocol.md)
- [WebDriver Protocol Reference](references/webdriver-protocol.md)
- [Session Management](references/session-management.md)
- [Test Generation](references/test-generation.md)
