QA Testing

What did you change? Start here.

Change	Test level	Command
Bug fix, refactor, small feature	Unit	make test
Feature, UI, big change	Unit + E2E	make test then make test-e2e
Visual / UI verification	Agent-browser	make dev + agent-browser
Install script, matcha, infra	VM install	multipass VM
Release	All of the above	See release checklist

---

Level 1: Unit Tests (~3 seconds)

make test

Run after every change. No excuses.

---

Level 2: E2E Tests (~5 minutes)

# CRITICAL: Kill any running dev server first — E2E uses its own database
lsof -ti :3000 | xargs kill -9 2>/dev/null
make test-e2e

Playwright tests that run onboarding, create websites, check dashboards, ingest events. Run after features or big changes.

---

Level 3: Visual QA with agent-browser

For verifying UI rendering, checking that data displays correctly, or testing flows that E2E doesn't cover.

Setup (one-time)

npm i -g agent-browser
agent-browser install

Start dev server

make dev    # MUST use make dev (Go + Vite together)

Dev credentials

• Email: admin@example.com
• Password: password
• Created by make db-seed

Login

agent-browser open "http://localhost:3000/login"
agent-browser snapshot -i
agent-browser fill @e1 "admin@example.com"
agent-browser fill @e3 "password"
agent-browser click @e4

Navigate and verify

agent-browser snapshot -i           # list interactive elements with refs
agent-browser click @e11            # click element by ref
agent-browser scroll down 1000      # scroll to find sections
agent-browser screenshot            # capture page as PNG
agent-browser get url               # check current URL

Generate real browser events

# The /_demo page includes the tracking script — fires real pageviews
agent-browser open "http://localhost:3000/_demo"

# Wait for event processing (~10s), then check dashboard

Key pages to verify

Page	How to reach	What to check
Admin home	/admin	Website list loads
Dashboard	Click arrow (→) on a website	Charts, stats, time range
Browsers tab	Scroll to Device Analytics, click "Browsers"	Browser names (Brave, Edge, etc.)
Settings	Click "Settings" in nav	Forms save, flash messages
Events	Click "Events" tab on dashboard	Event list, sessions view

Important

• Always make dev — make watch-go alone won't render Inertia pages
• Click through the UI — don't force navigation with open after login (breaks Inertia state)
• /_demo for real events — sends actual Sec-CH-UA headers from the browser
• Dev database: storage/fusionaly-development.db

---

Level 4: VM Install Test

Only needed when changing: install script, matcha, Docker setup, or release infrastructure.

Create fresh VM

multipass delete fusionaly-test --purge 2>/dev/null || true
multipass launch 24.04 --name fusionaly-test --cpus 2 --memory 2G --disk 10G

Run install

multipass exec fusionaly-test -- bash -c '
sudo apt-get update -qq && sudo apt-get install -y -qq expect

cat > /tmp/run_install.exp << '\''EXPECTSCRIPT'\''
#!/usr/bin/expect -f
set timeout 300
spawn sudo bash -c "curl -fsSL https://fusionaly.com/install | bash"
expect "Enter your domain name"
send "test.local\r"
expect "Proceed with this configuration"
send "Y\r"
expect eof
EXPECTSCRIPT

expect /tmp/run_install.exp
'

Verify

multipass exec fusionaly-test -- bash -c '
echo "=== Containers ===" && sudo docker ps
echo "=== Version ===" && fusionaly version
echo "=== Health ===" && curl -s http://172.18.0.2:8080/_health
'

Browser test via tunnel

VM_IP=$(multipass info fusionaly-test | grep IPv4 | awk '{print $2}')
ssh -L 8080:172.18.0.2:8080 ubuntu@$VM_IP
# Open http://localhost:8080/setup

Cleanup

multipass delete fusionaly-test --purge

---

Release Checklist

Before tagging a release:

• make test passes
• make test-e2e passes (kill dev server first!)
• Visual QA: dashboard loads, browser stats correct, events ingesting
• VM install test (if install/infra changed)
• Pro: update OSS submodule, build, test

---

Common Issues

Issue	Cause	Fix
E2E fails "Setup already complete"	Dev server running (wrong DB)	lsof -ti :3000 | xargs kill -9
agent-browser login doesn't work	Vite not running	Use make dev, not make watch-go
Dashboard shows JSON error	Navigated directly after forced POST	Start fresh browser, click through UI
/_demo events not appearing	Processing job hasn't run yet	Wait ~10 seconds, check ingested_events table
VM can't reach app	Docker internal network	Use SSH tunnel to 172.18.0.2:8080