Skip to content

karloscodes/fusionaly-oss / .claude/skills/qa

Use after code changes, before releases, or when testing features - runs the right level of QA based on what changed

QA Testing

What did you change? Start here.

ChangeTest levelCommand
Bug fix, refactor, small featureUnitmake test
Feature, UI, big changeUnit + E2Emake test then make test-e2e
Visual / UI verificationAgent-browsermake dev + agent-browser
Install script, matcha, infraVM installmultipass VM
ReleaseAll of the aboveSee 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

PageHow to reachWhat to check
Admin home/adminWebsite list loads
DashboardClick arrow (→) on a websiteCharts, stats, time range
Browsers tabScroll to Device Analytics, click "Browsers"Browser names (Brave, Edge, etc.)
SettingsClick "Settings" in navForms save, flash messages
EventsClick "Events" tab on dashboardEvent 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

IssueCauseFix
E2E fails "Setup already complete"Dev server running (wrong DB)lsof -ti :3000 | xargs kill -9
agent-browser login doesn't workVite not runningUse make dev, not make watch-go
Dashboard shows JSON errorNavigated directly after forced POSTStart fresh browser, click through UI
/_demo events not appearingProcessing job hasn't run yetWait ~10 seconds, check ingested_events table
VM can't reach appDocker internal networkUse SSH tunnel to 172.18.0.2:8080
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall