# Session Management

Manage multiple WebView sessions and state persistence.

## Session Basics

### Create Session

```bash
# Create default session (auto-detects CDP for localhost:9222)
nomo-e2e open http://localhost:9222

# Create named session
nomo-e2e open -s myapp http://localhost:9222

# Sessions are automatically persisted
```

### List Sessions

```bash
# List all sessions
nomo-e2e list

# Output:
# {
#   "status": "success",
#   "sessions": [
#     {"name": "myapp", "endpoint": "http://localhost:9222", "driver": "cdp", "is_active": true}
#   ],
#   "count": 1
# }
```

### Switch Sessions

```bash
# Switch to different session
nomo-e2e open -s other-app http://localhost:9222

# Now commands operate on 'other-app' session
nomo-e2e click "#button"
```

### Close Session

```bash
# Close specific session
nomo-e2e close

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

### Session Status

```bash
# Check current session status
nomo-e2e status

# Output:
# {
#   "status": "success",
#   "session": {
#     "name": "myapp",
#     "endpoint": "http://localhost:9222",
#     "driver": "cdp",
#     "connected": true,
#     "url": "http://localhost:3000",
#     "title": "My App"
#   }
# }
```

## Session Persistence

Sessions are automatically saved to `~/.nomo-e2e/sessions.json` and auto-reconnected.

### State Save/Load

```bash
# Save session state (cookies, localStorage, sessionStorage)
nomo-e2e state-save

# Save with custom filename
nomo-e2e state-save ./my-state.json

# Load session state
nomo-e2e state-load ./my-state.json
```

### State Save Example

```bash
# Login once
nomo-e2e open http://localhost:9222
nomo-e2e fill "#username" "admin"
nomo-e2e fill "#password" "secret"
nomo-e2e click "#login"

# Save state
nomo-e2e state-save ./logged-in.json
nomo-e2e close

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

## Multi-Session Workflows

### Parallel Testing

```bash
#!/bin/bash

# Start multiple sessions
nomo-e2e open -s app1 http://localhost:9222 &
nomo-e2e open -s app2 http://localhost:4445 &
wait

# Run tests
nomo-e2e -s app1 click "#feature-a"
nomo-e2e -s app2 click "#feature-b"

# Capture results
nomo-e2e -s app1 screenshot --filename app1.png
nomo-e2e -s app2 screenshot --filename app2.png

# Cleanup
nomo-e2e close-all
```

### Session Isolation

Each session maintains independent:

- Cookies
- localStorage / sessionStorage
- Cache
- Browsing history
- DOM state

```bash
# Session 1: Set cookie
nomo-e2e open -s app1 http://localhost:9222
nomo-e2e cookie-set "theme" "dark"

# Session 2: No cookie (isolated)
nomo-e2e open -s app2 http://localhost:9222
nomo-e2e cookie-get "theme"
# Returns: {"cookies": [], "count": 0}
```

## Configuration

### Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--session` | `-s` | Session name |
| `--config` | | Config file path |
| `--driver` | | Driver: auto, cdp, webdriver |
| `--browser` | | Browser: chromium, firefox, webkit |
| `--output-dir` | | Output directory |

### Config Commands

```bash
# List configuration
nomo-e2e config-list

# Get specific value
nomo-e2e config-get browser

# Set value
nomo-e2e config-set browser firefox
```

### 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 |

## Session Lifecycle

```
open → Connected → Active → close → Disconnected
                        ↓
                     Error → Retry/Abort
```

### Auto-reconnect

Sessions automatically reconnect when:

1. New CLI command is issued
2. Session file exists in `~/.nomo-e2e/sessions.json`

## Best Practices

### 1. Use Named Sessions

```bash
# Good: Clear naming
nomo-e2e open -s github-auth http://localhost:9222
nomo-e2e open -s docs-scrape http://localhost:9222

# Avoid: Generic names
nomo-e2e open -s s1 http://localhost:9222
```

### 2. Always Clean Up

```bash
# Always disconnect when done
nomo-e2e close

# Or close all
nomo-e2e close-all
```

### 3. Save Expensive State

```bash
# Login once, save state
nomo-e2e open http://localhost:9222
# ... perform login ...
nomo-e2e state-save ./auth.json

# Reuse for multiple tests
nomo-e2e state-load ./auth.json
```

## Troubleshooting

### Session Not Found

```bash
# List sessions
nomo-e2e list

# Check if session exists
```

### State Load Failed

```bash
# Check file exists
ls -la ./state.json

# Check file format
cat ./state.json | jq .
```

### Connection Issues

```bash
# CDP endpoints (localhost:9222) auto-detected
# WebDriver endpoints need --driver webdriver

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

# Check session persistence location
# Sessions are saved to ~/.nomo-e2e/sessions.json
```

## See Also

- [Getting Started](getting-started.md)
- [CDP Protocol](cdp-protocol.md)
- [WebDriver Protocol](webdriver-protocol.md)
