c-relay-pg/docs/agent_browser_testing.md

Agent Browser Testing Guide for C-Relay

This document explains how to use the agent-browser CLI tool to test the c-relay 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

./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

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

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"

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

agent-browser fill @e14 "nsec1zkn0hlt4jvcvn9yt5p7ea4m7f82pf3ph0gj3d4rlcz4s64x5z86satv9qm"

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

Step 5: Click "Import Key"

agent-browser snapshot -i

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

agent-browser click @e15

Step 6: Click "Continue" on the success screen

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

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

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:

# 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

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

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

agent-browser close --all