browser-test

Browser Test

Visually verify web UI changes by running the app in a real browser and taking screenshots.

Always launch playwright-cli with Chromium explicitly. Do not rely on the default browser selection, because Chrome may be unavailable on Tangerine VMs.

When to use

After completing work on any feature, bug fix, or change that affects the web dashboard (web/src/). Do NOT use for server-only or shared-only changes.

Prerequisites

• playwright-cli installed globally (npm install -g @playwright/cli)
• Chromium installed (npx playwright install chromium)
• Both are pre-installed on Tangerine VMs

Quick workflow

1. Derive port from worktree slot number
2. Start vite dev server on that port (background)
3. Wait for server ready
4. Open Chromium with playwright-cli
5. If auth is enabled, inject the auth token into localStorage
6. Navigate to affected pages, take screenshots
7. Check console for errors
8. Clean up (close browser, kill dev server)

Detailed steps

Step 1 — Derive a unique port

Extract the slot number from your worktree path and compute a port:

# Worktree path looks like: /workspace/<project>/worktrees/<projectId>-slot-<N>
SLOT_NUM=$(basename "$PWD" | grep -oP 'slot-\K\d+')
VITE_PORT=$((5170 + SLOT_NUM))
echo "Using port $VITE_PORT"

If you cannot determine the slot number, use port 5199 as a fallback.

Step 2 — Start the dev server

cd web && bunx vite --port $VITE_PORT > /tmp/vite-$VITE_PORT.log 2>&1 &
VITE_PID=$!
echo "Vite PID: $VITE_PID"

Step 3 — Wait for the server

# Wait up to 30 seconds for vite to be ready
for i in $(seq 1 30); do
  curl -s -o /dev/null http://localhost:$VITE_PORT && break
  sleep 1
done

Step 4 — Open browser and take screenshots

Use a named session tied to the task to avoid conflicts with other tasks:

TASK_SHORT=$(echo $TANGERINE_TASK_ID | cut -c1-8)
SESSION="task-$TASK_SHORT"

# Open Chromium explicitly (headless by default)
playwright-cli --browser chromium -s=$SESSION open http://localhost:$VITE_PORT

# Always set viewport explicitly — some environments open Chromium with a
# non-standard default size, causing screenshots at 1/4 resolution or smaller.
# Use 1920x1080 for crisp, full-HD screenshots (headless Chromium has dpr=1).
playwright-cli -s=$SESSION resize 1920 1080