testing-sandbox-ui

name	testing-sandbox-ui
description	Use when testing UI features, service panels, or visual behavior in the PizzaPi sandbox using a headless browser. Use when verifying new UI components work end-to-end before merging.

Testing Sandbox UI with Playwright

Overview

The PizzaPi sandbox (packages/server/tests/harness/sandbox.ts) spins up a full server with mock sessions, runners, and services. Combined with playwright-cli, you can drive a real browser against it to verify UI features work end-to-end — login, navigation, service panels, iframes, etc.

When to Use

• Verifying new UI components render correctly in the full app
• Testing service panel iframe loading through the tunnel proxy
• Checking auth flows (login, session management)
• Visual regression checks before merging UI branches
• Any time you need to confirm "does this actually work in a browser?"

Quick Reference

Step	Command
Start sandbox	screen -dmS sandbox bash -c 'cd packages/server && exec bun tests/harness/sandbox.ts --headless --redis=memory > /tmp/sandbox-out.log 2>&1'
Wait for ready	grep "Sandbox ready" /tmp/sandbox-out.log
Extract UI URL	grep "UI (HMR)" /tmp/sandbox-out.log
Open browser	playwright-cli open <URL>
Get element refs	playwright-cli snapshot then read the .yml file
Interact	playwright-cli fill <ref> "text" / playwright-cli click <ref>
Screenshot	playwright-cli screenshot then read the .png file
Clean up	playwright-cli close && screen -S sandbox -X quit

Starting the Sandbox

Critical: Use screen on macOS. Background processes started with nohup & get killed when the parent bash command times out. screen detaches the process from the shell entirely.

# Start in a detached screen session
screen -dmS sandbox bash -c \
  'cd packages/server && exec bun tests/harness/sandbox.ts --headless --redis=memory > /tmp/sandbox-out.log 2>&1'

# Wait for startup (typically 4-6 seconds)
sleep 6

# Verify it's running
pgrep -f "sandbox.ts" && echo "alive" || echo "dead"

# Extract URLs from the log
grep "UI (HMR)" /tmp/sandbox-out.log   # → http://127.0.0.1:<port>
grep "Server:"  /tmp/sandbox-out.log   # → http://127.0.0.1:<port>
grep "API:"     /tmp/sandbox-out.log   # → http://127.0.0.1:<port>

The sandbox starts three things on random ports:

• Vite dev server (UI with HMR) — this is where you point the browser
• API server (WebSocket + REST) — the Vite proxy forwards to this
• Sandbox API (HTTP control surface) — for programmatic session control

Logging In

The sandbox creates a test user automatically:

Field	Value
Email	[e-mail]
Password	HarnessPass123

playwright-cli open http://127.0.0.1:<vite-port>
playwright-cli snapshot                              # find email/password input refs
playwright-cli fill <email-ref> "[e-mail]"
playwright-cli fill <password-ref> "HarnessPass123"
playwright-cli snapshot                              # find sign-in button ref (not disabled)
playwright-cli click <button-ref>
playwright-cli screenshot                            # verify logged in

Testing Service Panels

After logging in, select a session from the sidebar. Service panel buttons appear in the session toolbar header. Look for buttons like "Toggle System Monitor" in the snapshot.

playwright-cli snapshot
# grep for "monitor\|panel\|service\|tunnel" in the .yml file
playwright-cli click <panel-button-ref>
sleep 2                                              # wait for iframe to load
playwright-cli screenshot                            # verify panel renders

The panel loads via iframe → tunnel proxy → mock HTTP server. The sandbox starts a mock system monitor server on a random port and announces it through the mock runner's service_announce event.

Cleanup

Always clean up both browser and sandbox:

playwright-cli close                    # close browser
screen -S sandbox -X quit              # kill sandbox screen session
pkill -f "sandbox.ts" 2>/dev/null      # belt-and-suspenders

Common Problems

Problem	Cause	Fix
"Invalid origin" on login	Vite dev server port not in trustedOrigins	Fixed in 49116fc8 — addTrustedOrigin() called after Vite starts
Sandbox dies immediately	Shell timeout kills background process	Use screen -dmS instead of nohup &
"net::ERR_CONNECTION_REFUSED"	Sandbox process died or hasn't started yet	Check pgrep -f sandbox.ts and /tmp/sandbox-out.log
Stale element refs	DOM changed since last snapshot	Re-run playwright-cli snapshot to get fresh refs
Panel iframe blank	Tunnel proxy can't reach mock server	Check sandbox log for "Mock system monitor panel on port X"
"Server running in degraded mode" banner	Redis in-memory mode (expected)	Harmless — real-time updates work, it's just a warning

Mock Runner Capabilities

The sandbox mock runner (mock-runner.ts) supports:

• panels option — ServicePanelInfo[] included in service_announce
• tunnel_request handling — proxies HTTP to registered panel ports
• announceServices(serviceIds, panels?) — re-announce at runtime

To add a new mock service panel, start a Bun.serve({ port: 0 }) before creating the runner and pass the port in the panels array.

Sandbox Credentials & URLs

All ports are ephemeral (random). Always extract from /tmp/sandbox-out.log:

# One-liner to extract all three URLs
grep -E "(UI|Server|API):" /tmp/sandbox-out.log

API key is also in the log if you need direct API access.