c-relay-pg/docs/agent_browser_testing.md

# Agent Browser Testing Guide for C-Relay-PG

This document explains how to use the `agent-browser` CLI tool to test the c-relay-pg admin web UI from an AI agent context (no physical display required).

## Prerequisites

- **agent-browser** installed globally: `npm install -g agent-browser`
- Binary location: `/home/user/.nvm/versions/node/v24.14.1/bin/agent-browser`
- The relay must be running locally (default port 8888)
- Test keys configured in `.test_keys`

## Starting the Relay for Local Testing

```bash
./make_and_restart_relay.sh -t
```

This reads `.test_keys` and starts the relay with:
- `ADMIN_PUBKEY` — the hex public key of the admin account
- `ADMIN_PRIVKEY` — the hex secret key (used for browser login, not by the relay itself)
- `SERVER_PRIVKEY` — the relay's own private key

## Key URLs

| URL | Purpose |
|-----|---------|
| `http://127.0.0.1:8888/api/index.html` | Admin web UI (the correct entry point) |
| `http://127.0.0.1:8888/` | Returns 406 without NIP-11 Accept header — **do not use for browser testing** |
| `http://127.0.0.1:8888/` with `Accept: application/nostr+json` | NIP-11 relay info JSON |

**Important:** The root URL `/` is a WebSocket/NIP-11 endpoint, not an HTML page. Always use `/api/index.html` for browser testing.

## Admin Login Credentials

The admin nsec for the current `.test_keys` configuration:

```
nsec: nsec1zkn0hlt4jvcvn9yt5p7ea4m7f82pf3ph0gj3d4rlcz4s64x5z86satv9qm
hex:  15a6fbfd759330c9948ba07d9ed77e49d414c4377a2516d47fc0ab0d54d411f5
npub: npub1tlyzk6slzt8d989f4pn3synk98fea64ea3jmrdc7dtd0kw8uxlas9a9fwr
hex pubkey: 5fc82b6a1f12ced29ca9a86718127629d39eeab9ec65b1b71e6adafb38fc37fb
```

## Complete Login Flow with agent-browser

### Step 1: Open the admin UI

```bash
agent-browser open http://127.0.0.1:8888/api/index.html
agent-browser wait --load networkidle
```

### Step 2: Take an interactive snapshot to see what is on screen

```bash
agent-browser snapshot -i
```

You will see a login modal with buttons like:
- `"Browser Extension"` — skip this
- `"Local Key"` — **use this one**
- `"Seed Phrase"` — skip
- `"Nostr Connect"` — skip
- `"Read Only"` — skip

### Step 3: Click "Local Key"

```bash
agent-browser click @e15
```

(The ref number may vary — use the ref from the snapshot output for the "Local Key" button.)

After clicking, a text input appears asking for the secret key.

### Step 4: Enter the admin nsec

```bash
agent-browser fill @e14 "nsec1zkn0hlt4jvcvn9yt5p7ea4m7f82pf3ph0gj3d4rlcz4s64x5z86satv9qm"
```

(Use the ref from the snapshot for the textbox element.)

### Step 5: Click "Import Key"

```bash
agent-browser snapshot -i
```

Check the snapshot — the "Import Key" button should now be enabled. Click it:

```bash
agent-browser click @e15
```

### Step 6: Click "Continue" on the success screen

After import, a success screen appears with "Continue" button:

```bash
agent-browser wait 800
agent-browser snapshot -i
agent-browser click @e19
```

(Use the ref from the snapshot for the "Continue" button.)

### Step 7: Wait for admin UI to load

```bash
agent-browser wait 5000
agent-browser snapshot -i
```

You should now see the admin dashboard with:
- Statistics table (Database Size, Total Events, PID, etc.)
- Navigation buttons (Statistics, Subscriptions, Configuration, Authorization, etc.)
- Admin profile area showing "admin" label

## Navigating Admin Sections

After login, use the sidebar navigation buttons:

```bash
# View configuration
agent-browser click @e8    # Configuration button ref

# View authorization rules
agent-browser click @e9    # Authorization button ref

# View statistics
agent-browser click @e6    # Statistics button ref

# Always snapshot after navigation to see results
agent-browser wait 2500
agent-browser snapshot -i
```

## Checking for Errors

```bash
# View browser console logs
agent-browser console

# View JavaScript errors
agent-browser errors

# View relay server logs
tail -n 100 relay.log
```

## Chained Command Example (Full Login in One Shot)

```bash
agent-browser open http://127.0.0.1:8888/api/index.html && \
agent-browser wait --load networkidle && \
agent-browser snapshot -i
```

Then use refs from the snapshot to complete login steps.

## Tips for AI Agents

1. **Always use `/api/index.html`** — never the root URL
2. **Use `snapshot -i`** after every action to see the current interactive elements and their refs
3. **Refs change** between snapshots — always re-snapshot before clicking
4. **Wait after clicks** — use `agent-browser wait 2000` (milliseconds) between actions that trigger async operations
5. **The login flow has 3 screens**: method selection → key input → success confirmation
6. **Console logs are cumulative** — they show all logs since page load, which is useful for debugging admin API responses
7. **The relay log** at `relay.log` shows server-side processing of admin commands
8. **Command chaining** with `&&` works — the browser daemon persists between commands

## Verifying Admin API is Working

After login, the statistics page should show populated data:
- Database Size (e.g., "4 KB")
- Process ID (the relay PID)
- WebSocket Connections count
- Memory Usage

If these show "-" or "Loading...", check:
1. `relay.log` for errors
2. `agent-browser console` for JavaScript errors
3. `agent-browser errors` for page-level errors

## Closing the Browser

```bash
agent-browser close --all
```