High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
refactor: reorganize tests - automated integration & manual testing
Mario754fc5be53e4
diff --git a/TESTING.md b/TESTING.mdindex 0d977abf..e1a025a6 100644--- a/TESTING.md+++ b/TESTING.md@@ -2,6 +2,27 @@This guide provides manual and automated tests for the complete multi-instance architecture.+## Test Organization++- **Automated Integration Tests**: `tests/integration/orchestrator_test.go` (Go)+ - Instance creation and lifecycle+ - Hash-based ID generation+ - Port allocation and reuse+ - Instance isolation+ - Orchestrator proxy routing+ - Run with: `go test -tags integration ./tests/integration -run Orchestrator -timeout 120s`++- **Manual Tests**: `tests/manual/orchestrator.md`+ - Visual verification (headed/headless windows)+ - Real-time monitoring (memory, CPU)+ - Port management verification+ - Chrome initialization verification+ - Dashboard UI testing+ - Error conditions and edge cases+ - Integration with existing features++- **Quick Validation**: Follow the step-by-step tests below for immediate feedback+## Prerequisites- Pinchtab built: `go build -o pinchtab ./cmd/pinchtab`diff --git a/tests/integration/orchestrator_test.go b/tests/integration/orchestrator_test.gonew file mode 100644index 00000000..84c6fff4--- /dev/null+++ b/tests/integration/orchestrator_test.go@@ -0,0 +1,475 @@+//go:build integration++package integration++import (+ "encoding/json"+ "fmt"+ "strings"+ "testing"+ "time"+)++// TestOrchestrator_HealthCheck verifies dashboard orchestrator is running+func TestOrchestrator_HealthCheck(t *testing.T) {+ status, body := httpGet(t, "/health")+ if status != 200 {+ t.Fatalf("expected 200, got %d", status)+ }++ mode := jsonField(t, body, "mode")+ if mode != "dashboard" {+ t.Fatalf("expected mode=dashboard, got %s", mode)+ }+}++// TestOrchestrator_InstanceCreation verifies instance launch with auto-port allocation+func TestOrchestrator_InstanceCreation(t *testing.T) {+ payload := map[string]any{+ "name": fmt.Sprintf("test-inst-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("expected 201, got %d: %s", status, string(body))+ }++ instID := jsonField(t, body, "id")+ if !strings.HasPrefix(instID, "inst_") {+ t.Fatalf("expected inst_XXXXX format, got %s", instID)+ }++ profileID := jsonField(t, body, "profileId")+ if !strings.HasPrefix(profileID, "prof_") {+ t.Fatalf("expected prof_XXXXX format, got %s", profileID)+ }++ instPort := jsonField(t, body, "port")+ if instPort == "" {+ t.Fatalf("expected port, got empty")+ }++ // Verify instance appears in list+ status, body = httpGet(t, "/instances")+ if status != 200 {+ t.Fatalf("expected 200, got %d", status)+ }++ // Check body is array+ var instances []map[string]any+ if err := json.Unmarshal(body, &instances); err != nil {+ t.Fatalf("failed to parse instances: %v", err)+ }++ found := false+ for _, inst := range instances {+ if id, ok := inst["id"].(string); ok && id == instID {+ found = true+ break+ }+ }+ if !found {+ t.Fatalf("created instance not found in list")+ }++ // Cleanup+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+}++// TestOrchestrator_HashBasedIDs verifies all ID formats (prof_, inst_, tab_)+func TestOrchestrator_HashBasedIDs(t *testing.T) {+ // Create instance+ payload := map[string]any{+ "name": fmt.Sprintf("test-ids-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance creation failed: %d", status)+ }++ instID := jsonField(t, body, "id")+ profileID := jsonField(t, body, "profileId")+ instPort := jsonField(t, body, "port")++ // Verify ID formats+ if !strings.HasPrefix(instID, "inst_") || len(instID) != 13 {+ t.Fatalf("invalid instance ID format: %s", instID)+ }+ if !strings.HasPrefix(profileID, "prof_") || len(profileID) != 13 {+ t.Fatalf("invalid profile ID format: %s", profileID)+ }+ if instPort == "" {+ t.Fatalf("instance port is empty")+ }++ // Wait for instance to be healthy+ time.Sleep(2 * time.Second)++ // Navigate to create tab+ navPayload := map[string]any{+ "url": "https://example.com",+ }++ navStatus, navBody := httpPost(t, fmt.Sprintf("/instances/%s/navigate", instID), navPayload)+ if navStatus != 200 {+ t.Fatalf("navigate failed: %d: %s", navStatus, string(navBody))+ }++ tabID := jsonField(t, navBody, "tabId")+ if !strings.HasPrefix(tabID, "tab_") || len(tabID) != 12 {+ t.Fatalf("invalid tab ID format: %s", tabID)+ }++ // Cleanup+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+}++// TestOrchestrator_PortAllocation verifies sequential port allocation+func TestOrchestrator_PortAllocation(t *testing.T) {+ var instIDs []string+ var ports []string++ defer func() {+ // Cleanup+ for _, instID := range instIDs {+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+ }+ }()++ // Create 3 instances and verify they get different ports+ for i := 0; i < 3; i++ {+ payload := map[string]any{+ "name": fmt.Sprintf("port-test-%d-%d", time.Now().Unix(), i),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance %d creation failed: %d", i, status)+ }++ instID := jsonField(t, body, "id")+ port := jsonField(t, body, "port")++ instIDs = append(instIDs, instID)+ ports = append(ports, port)+ }++ // Verify all ports are different+ for i := 0; i < len(ports); i++ {+ for j := i + 1; j < len(ports); j++ {+ if ports[i] == ports[j] {+ t.Fatalf("instances have same port: %s", ports[i])+ }+ }+ }++ // Verify ports are sequential+ if ports[0] == "" || ports[1] == "" || ports[2] == "" {+ t.Fatalf("some ports are empty")+ }+}++// TestOrchestrator_PortReuse verifies ports are released and can be reused+func TestOrchestrator_PortReuse(t *testing.T) {+ // Create instance 1+ payload1 := map[string]any{+ "name": fmt.Sprintf("reuse-test-1-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload1)+ if status != 201 {+ t.Fatalf("instance 1 creation failed: %d", status)+ }++ instID1 := jsonField(t, body, "id")+ port1 := jsonField(t, body, "port")++ // Stop instance 1+ status, _ = httpPost(t, fmt.Sprintf("/instances/%s/stop", instID1), nil)+ if status != 200 {+ t.Fatalf("stop instance 1 failed: %d", status)+ }++ time.Sleep(500 * time.Millisecond)++ // Create instance 2+ payload2 := map[string]any{+ "name": fmt.Sprintf("reuse-test-2-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body = httpPost(t, "/instances/launch", payload2)+ if status != 201 {+ t.Fatalf("instance 2 creation failed: %d", status)+ }++ instID2 := jsonField(t, body, "id")+ port2 := jsonField(t, body, "port")++ // Verify port2 == port1 (reused)+ if port1 != port2 {+ t.Fatalf("port not reused: old=%s, new=%s", port1, port2)+ }++ // Cleanup+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID2), nil)+}++// TestOrchestrator_InstanceIsolation verifies instances have separate tabs+func TestOrchestrator_InstanceIsolation(t *testing.T) {+ var instIDs []string++ defer func() {+ for _, instID := range instIDs {+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+ }+ }()++ // Create 2 instances+ for i := 0; i < 2; i++ {+ payload := map[string]any{+ "name": fmt.Sprintf("isolation-test-%d-%d", time.Now().Unix(), i),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance %d creation failed", i)+ }++ instID := jsonField(t, body, "id")+ instIDs = append(instIDs, instID)+ }++ // Wait for Chrome init+ time.Sleep(2 * time.Second)++ // Navigate on instance 1+ nav1Payload := map[string]any{"url": "https://example.com"}+ status, body := httpPost(t, fmt.Sprintf("/instances/%s/navigate", instIDs[0]), nav1Payload)+ if status != 200 {+ t.Fatalf("navigate instance 1 failed: %d", status)+ }+ tabID1 := jsonField(t, body, "tabId")++ // Navigate on instance 2+ nav2Payload := map[string]any{"url": "https://github.com"}+ status, body = httpPost(t, fmt.Sprintf("/instances/%s/navigate", instIDs[1]), nav2Payload)+ if status != 200 {+ t.Fatalf("navigate instance 2 failed: %d", status)+ }+ tabID2 := jsonField(t, body, "tabId")++ // Verify tab IDs are different (isolation)+ if tabID1 == tabID2 {+ t.Fatalf("instances share tab IDs (not isolated): %s", tabID1)+ }+}++// TestOrchestrator_ListInstances verifies GET /instances returns all instances+func TestOrchestrator_ListInstances(t *testing.T) {+ // Get initial count+ status, body := httpGet(t, "/instances")+ if status != 200 {+ t.Fatalf("list instances failed: %d", status)+ }++ var instances []map[string]any+ if err := json.Unmarshal(body, &instances); err != nil {+ t.Fatalf("parse instances failed: %v", err)+ }++ initialCount := len(instances)++ // Create an instance+ payload := map[string]any{+ "name": fmt.Sprintf("list-test-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body = httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance creation failed")+ }++ instID := jsonField(t, body, "id")++ // Verify count increased+ status, body = httpGet(t, "/instances")+ if status != 200 {+ t.Fatalf("list instances failed")+ }++ if err := json.Unmarshal(body, &instances); err != nil {+ t.Fatalf("parse instances failed")+ }++ if len(instances) != initialCount+1 {+ t.Fatalf("expected %d instances, got %d", initialCount+1, len(instances))+ }++ // Cleanup+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+}++// TestOrchestrator_ProxyRouting verifies orchestrator forwards requests to instance+func TestOrchestrator_ProxyRouting(t *testing.T) {+ // Create instance+ payload := map[string]any{+ "name": fmt.Sprintf("proxy-test-%d", time.Now().Unix()),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance creation failed")+ }++ instID := jsonField(t, body, "id")++ defer func() {+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+ }()++ // Wait for Chrome init+ time.Sleep(2 * time.Second)++ // Test navigation via orchestrator proxy+ navPayload := map[string]any{"url": "https://example.com"}+ status, body = httpPost(t, fmt.Sprintf("/instances/%s/navigate", instID), navPayload)+ if status != 200 {+ t.Fatalf("proxy navigate failed: %d: %s", status, string(body))+ }++ tabID := jsonField(t, body, "tabId")+ if !strings.HasPrefix(tabID, "tab_") {+ t.Fatalf("invalid tab ID from proxy: %s", tabID)+ }++ // Test snapshot via orchestrator proxy+ status, body = httpGet(t, fmt.Sprintf("/instances/%s/snapshot", instID))+ if status != 200 {+ t.Fatalf("proxy snapshot failed: %d", status)+ }++ // Verify it's valid JSON with nodes+ var snapshot map[string]any+ if err := json.Unmarshal(body, &snapshot); err != nil {+ t.Fatalf("parse snapshot failed: %v", err)+ }+}++// TestOrchestrator_AggregateTabsEndpoint verifies GET /instances/tabs returns all tabs+func TestOrchestrator_AggregateTabsEndpoint(t *testing.T) {+ var instIDs []string++ defer func() {+ for _, instID := range instIDs {+ httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+ }+ }()++ // Create 2 instances and navigate on each+ for i := 0; i < 2; i++ {+ payload := map[string]any{+ "name": fmt.Sprintf("tabs-agg-%d-%d", time.Now().Unix(), i),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance %d creation failed", i)+ }++ instID := jsonField(t, body, "id")+ instIDs = append(instIDs, instID)+ }++ // Wait for Chrome init+ time.Sleep(2 * time.Second)++ // Navigate on each instance+ for _, instID := range instIDs {+ navPayload := map[string]any{"url": "https://example.com"}+ httpPost(t, fmt.Sprintf("/instances/%s/navigate", instID), navPayload)+ }++ // Get aggregate tabs+ status, body := httpGet(t, "/instances/tabs")+ if status != 200 {+ t.Fatalf("aggregate tabs failed: %d", status)+ }++ var tabs []map[string]any+ if err := json.Unmarshal(body, &tabs); err != nil {+ t.Fatalf("parse tabs failed: %v", err)+ }++ if len(tabs) < 2 {+ t.Fatalf("expected at least 2 tabs, got %d", len(tabs))+ }+}++// TestOrchestrator_StopNonexistent verifies error handling for stopping non-existent instance+func TestOrchestrator_StopNonexistent(t *testing.T) {+ status, _ := httpPost(t, "/instances/nonexistent/stop", nil)+ if status != 404 {+ t.Fatalf("expected 404 for nonexistent instance, got %d", status)+ }+}++// TestOrchestrator_InstanceCleanup verifies all instances properly stop+func TestOrchestrator_InstanceCleanup(t *testing.T) {+ var instIDs []string++ // Create 3 instances+ for i := 0; i < 3; i++ {+ payload := map[string]any{+ "name": fmt.Sprintf("cleanup-test-%d-%d", time.Now().Unix(), i),+ "headless": true,+ }++ status, body := httpPost(t, "/instances/launch", payload)+ if status != 201 {+ t.Fatalf("instance %d creation failed", i)+ }++ instID := jsonField(t, body, "id")+ instIDs = append(instIDs, instID)+ }++ // Stop all+ for _, instID := range instIDs {+ status, _ := httpPost(t, fmt.Sprintf("/instances/%s/stop", instID), nil)+ if status != 200 {+ t.Fatalf("stop instance %s failed: %d", instID, status)+ }+ }++ // Verify all stopped+ status, body := httpGet(t, "/instances")+ if status != 200 {+ t.Fatalf("list instances failed")+ }++ var instances []map[string]any+ if err := json.Unmarshal(body, &instances); err != nil {+ t.Fatalf("parse instances failed")+ }++ // Should be empty or not contain our test instances+ for _, inst := range instances {+ if id, ok := inst["id"].(string); ok {+ for _, testID := range instIDs {+ if id == testID {+ t.Fatalf("instance %s still running after stop", testID)+ }+ }+ }+ }+}diff --git a/tests/manual/orchestrator.md b/tests/manual/orchestrator.mdnew file mode 100644index 00000000..095ec590--- /dev/null+++ b/tests/manual/orchestrator.md@@ -0,0 +1,530 @@+# Pinchtab Orchestrator & Multi-Instance Manual Testing++**Purpose:** Verify aspects of the multi-instance orchestrator that cannot be easily automated (visual UI, real-time monitoring, resource inspection).++**Note:** Automated tests for instance creation, isolation, port allocation, proxy routing, and ID formats are in `tests/integration/orchestrator_test.go`. This document covers _manual_ validation only.++---++## 1. Visual Verification: Headed Instances++### MH1: Headed Instance Shows Chrome Window++**Goal:** Verify that instances created with `headless=false` open a visible Chrome window.++**Steps:**+1. Start dashboard: `go build -o pinchtab ./cmd/pinchtab && ./pinchtab`+2. In another terminal, create a headed instance:+ ```bash+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"test-headed","headless":false}'+ ```+ Note the returned `id` and `port`.++3. Within 5 seconds, a Chrome window should appear on screen.+4. Navigate the instance:+ ```bash+ curl -X POST http://localhost:9867/instances/{id}/navigate \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}'+ ```+ The Chrome window should load and display example.com.++5. Stop the instance:+ ```bash+ curl -X POST http://localhost:9867/instances/{id}/stop+ ```+ The Chrome window should close.++**Expected:** Chrome window visible, responsive to navigation, closes cleanly.++**Criteria:** ✓ Chrome appears within 5s | ✓ Window responsive | ✓ Window closes on stop++---++### MH2: Headless Instance Does NOT Show Chrome Window++**Goal:** Verify that headless instances run in background without visible window.++**Steps:**+1. Create a headless instance:+ ```bash+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"test-headless","headless":true}'+ ```++2. Wait 5 seconds — NO Chrome window should appear.++3. Verify instance is working:+ ```bash+ curl http://localhost:{port}/health+ # Should return {"status":"ok"}+ ```++4. Verify navigation works:+ ```bash+ curl -X POST http://localhost:{port}/navigate \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}'+ ```++5. Stop the instance.++**Expected:** No visible window, but instance fully functional.++**Criteria:** ✓ No window appears | ✓ Health check works | ✓ Navigation works++---++## 2. Real-Time Monitoring++### MM1: Monitor Instance Memory Growth++**Goal:** Verify instance memory stays reasonable under navigation load.++**Setup:**+- Start dashboard+- Create a headless instance and get its port++**Steps:**+1. On Linux/macOS, monitor memory of the instance process:+ ```bash+ # Get instance PID (starts pinchtab as subprocess on port 9868, etc.)+ PID=$(lsof -i :9868 | grep pinchtab | awk '{print $2}')++ # Monitor RSS (resident set size) every 2 seconds+ while true; do+ ps -p $PID -o pid,rss,vsz,comm+ sleep 2+ done+ ```++2. Run navigation loop in another terminal:+ ```bash+ for i in {1..20}; do+ curl -X POST http://localhost:9868/navigate \+ -H "Content-Type: application/json" \+ -d "{\"url\":\"https://example.com/$i\"}" > /dev/null+ sleep 0.5+ done+ ```++3. Observe memory output (RSS column, in KB).++**Expected Values:**+- Idle: ~150-200 MB (150000-200000 KB)+- After 20 navigations: ~200-250 MB+- No sustained growth after navigations stop++**Criteria:** ✓ Starts < 200 MB | ✓ Grows < 100 MB per 20 navigations | ✓ Stable after load++---++### MM2: Monitor CPU Usage During Navigation++**Goal:** Verify CPU usage is reasonable (spikes during nav, drops after).++**Setup:**+- Same as MM1++**Steps:**+1. Start continuous CPU monitoring:+ ```bash+ PID=$(lsof -i :9868 | grep pinchtab | awk '{print $2}')+ top -p $PID -b -n 100 | grep "pinchtab"+ ```++2. Run navigation load in another terminal:+ ```bash+ for i in {1..10}; do+ curl -X POST http://localhost:9868/navigate \+ -H "Content-Type: application/json" \+ -d "{\"url\":\"https://example.com/$i\"}" > /dev/null+ done+ ```++3. Observe CPU % in `top` output.++**Expected Behavior:**+- CPU idle: 0-1%+- During navigation: 20-50% (single core usage on multi-core system)+- After navigation: back to 0-1% within 2-3 seconds++**Criteria:** ✓ Idle CPU low | ✓ Navigation uses moderate CPU | ✓ Returns to idle quickly++---++## 3. Port Management Verification++### MP1: Verify Port Allocation Range++**Goal:** Verify instances are allocated ports in the configured range.++**Setup:**+- Default range: 9868-9968 (100 instances max)+- Check config: `INSTANCE_PORT_START` / `INSTANCE_PORT_END` env vars++**Steps:**+1. Create 5 instances:+ ```bash+ for i in {1..5}; do+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d "{\"name\":\"test-$i\",\"headless\":true}" | jq '.port'+ done+ ```++2. Verify all returned ports are in range 9868-9968.++3. Check which ports are actually listening:+ ```bash+ lsof -i :9868-9968 | grep LISTEN+ ```++**Criteria:** ✓ All ports in range | ✓ All advertised ports actually listening | ✓ No duplicates++---++### MP2: Verify Port Cleanup and Reuse++**Goal:** Verify ports are released when instances stop, enabling reuse.++**Steps:**+1. Create instance, note port:+ ```bash+ INST1=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"reuse-1","headless":true}' | jq -r '.id,.port')+ # Extract ID and port+ PORT1=$(echo $INST1 | awk '{print $2}')+ ```++2. Verify port is listening:+ ```bash+ lsof -i :$PORT1 | grep LISTEN+ ```++3. Stop instance:+ ```bash+ curl -X POST http://localhost:9867/instances/{id}/stop+ ```++4. Wait 2 seconds and verify port is no longer listening:+ ```bash+ lsof -i :$PORT1 | grep -c LISTEN || echo "Port freed"+ ```++5. Create new instance:+ ```bash+ INST2=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"reuse-2","headless":true}' | jq -r '.port')+ ```++6. Verify new instance reused the port:+ ```bash+ [ "$PORT1" = "$INST2" ] && echo "Port reused!" || echo "Different port"+ ```++**Criteria:** ✓ Port freed within 2s | ✓ New instance reuses freed port | ✓ No hanging processes++---++## 4. Chrome Initialization Verification++### MC1: Verify Lazy Chrome Initialization++**Goal:** Verify Chrome starts on first request, not at instance creation.++**Steps:**+1. Create instance and time how long until Chrome is ready:+ ```bash+ START=$(date +%s%N)++ INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"lazy-test","headless":true}')++ ID=$(echo $INST | jq -r '.id')++ # Poll health until OK+ while true; do+ STATUS=$(curl -s http://localhost:9867/instances/$ID/health 2>/dev/null | jq -r '.status')+ if [ "$STATUS" = "ok" ]; then break; fi+ sleep 0.1+ done++ END=$(date +%s%N)+ ELAPSED=$(( (END - START) / 1000000 ))+ echo "Chrome ready in ${ELAPSED}ms"+ ```++**Expected:** Chrome should be ready within 5-10 seconds (longer for headed instances due to window rendering).++**Criteria:** ✓ Chrome ready in reasonable time | ✓ No hanging processes++---++### MC2: Verify Headed Instance Window Opens Quickly++**Goal:** Verify headed Chrome windows appear without delay.++**Steps:**+1. Create a headed instance and start stopwatch:+ ```bash+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"window-test","headless":false}'+ ```++2. Start timing when curl returns (should be < 1s).++3. Watch for Chrome window to appear (should be < 5s from curl return).++4. Window should display immediately upon appearance (not blank/loading).++**Criteria:** ✓ Window appears < 5s | ✓ Window displays properly | ✓ Responsive to further navigation++---++## 5. Dashboard UI Verification++### MU1: Instance List in Dashboard UI++**Goal:** Verify dashboard shows created instances with status.++**Steps:**+1. Create 3 instances via API:+ ```bash+ for i in {1..3}; do+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d "{\"name\":\"ui-test-$i\",\"headless\":true}" > /dev/null+ done+ ```++2. Open dashboard: http://localhost:9867/dashboard++3. Click on "Instances" tab.++4. Verify:+ - All 3 instances listed+ - Each shows: ID, port, profile name, status (running/initializing/stopped)+ - No 404 errors in browser console++**Criteria:** ✓ All instances visible | ✓ Status accurate | ✓ No JS errors++---++### MU2: Instance Creation from Dashboard++**Goal:** Verify dashboard UI can create new instances.++**Steps:**+1. Open dashboard: http://localhost:9867/dashboard++2. Navigate to "Instances" tab.++3. Click "Create Instance" or similar button.++4. Enter profile name (e.g., "dashboard-test").++5. Select headless/headed.++6. Submit.++7. Verify instance appears in list and reaches "running" status.++8. Verify port is allocated and instance responds to `/health`.++**Criteria:** ✓ Instance created | ✓ Appears in list | ✓ Responds to requests | ✓ Port valid++---++### MU3: Instance Deletion from Dashboard++**Goal:** Verify dashboard UI can stop instances.++**Steps:**+1. Open dashboard with running instances.++2. Click "Stop" or "Terminate" on an instance.++3. Verify:+ - Instance disappears from list (or shows "stopped" status)+ - Port becomes available (check with `lsof`)+ - Chrome process exits (check with `ps`)++**Criteria:** ✓ Instance stops | ✓ Port freed | ✓ Process exits | ✓ No orphaned processes++---++## 6. Error Conditions & Edge Cases++### ME1: Create Instance with Invalid Profile Name++**Goal:** Verify error handling for bad profile names.++**Steps:**+1. Try to create instance with empty name:+ ```bash+ curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"","headless":true}'+ ```++2. Verify error response (400 or 422).++3. Try with special characters or very long name.++**Criteria:** ✓ Error response (not 500 crash) | ✓ Clear error message++---++### ME2: Exceed Port Range++**Goal:** Verify behavior when port range exhausted.++**Setup:**+- Set `INSTANCE_PORT_START=19000 INSTANCE_PORT_END=19005` (6 ports only)+- Start dashboard with these limits++**Steps:**+1. Create 7 instances.++2. Verify:+ - First 6 succeed with ports 19000-19005+ - 7th fails with clear error (not a crash or hang)++3. Stop instance 1, which frees port 19000.++4. Create instance 8 — verify it reuses port 19000.++**Criteria:** ✓ First 6 succeed | ✓ 7th fails gracefully | ✓ Reuse works | ✓ No 500 errors++---++### ME3: Concurrent Instance Creation++**Goal:** Verify thread-safety of port allocation under concurrent requests.++**Steps:**+1. Send 10 concurrent instance creation requests:+ ```bash+ for i in {1..10}; do+ (curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d "{\"name\":\"concurrent-$i\",\"headless\":true}" | jq '.port') &+ done+ wait+ ```++2. Collect all returned ports.++3. Verify:+ - All 10 creation requests succeed+ - All ports unique (no duplicates)+ - All ports in valid range++**Criteria:** ✓ All succeed | ✓ No duplicate ports | ✓ All unique++---++## 7. Integration with Existing Features++### MI1: Proxy Routing Works with Multiple Instances++**Goal:** Verify proxy routes forward to correct instance.++**Steps:**+1. Create 3 instances:+ ```bash+ IDS=()+ for i in {1..3}; do+ ID=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d "{\"name\":\"proxy-$i\",\"headless\":true}" | jq -r '.id')+ IDS+=($ID)+ done+ ```++2. Navigate on each via orchestrator proxy:+ ```bash+ for i in 0 1 2; do+ curl -X POST http://localhost:9867/instances/${IDS[$i]}/navigate \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}' | jq '.tabId'+ done+ ```++3. Verify:+ - All navigation requests succeed+ - Each returns a valid tab ID+ - No cross-instance interference++**Criteria:** ✓ All navigate succeed | ✓ Correct tab IDs | ✓ No 404 errors++---++### MI2: Snapshot & Screenshot Work on Instance Proxy++**Goal:** Verify proxy routes work for snapshot/screenshot.++**Steps:**+1. Create instance and navigate:+ ```bash+ ID=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"name":"snap-test","headless":true}' | jq -r '.id')++ curl -X POST http://localhost:9867/instances/$ID/navigate \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}' > /dev/null+ ```++2. Request snapshot via orchestrator:+ ```bash+ curl http://localhost:9867/instances/$ID/snapshot | jq '.nodes | length'+ ```++3. Request screenshot via orchestrator:+ ```bash+ curl http://localhost:9867/instances/$ID/screenshot > /tmp/test.png+ file /tmp/test.png+ ```++4. Verify both succeed and return expected formats.++**Criteria:** ✓ Snapshot JSON valid | ✓ Screenshot is PNG | ✓ Both proxied correctly++---++## Checklist for Manual Testing++- [ ] **MH1:** Headed instance shows Chrome window+- [ ] **MH2:** Headless instance doesn't show window+- [ ] **MM1:** Memory stays reasonable (< 250 MB idle)+- [ ] **MM2:** CPU usage spikes during nav, returns to idle+- [ ] **MP1:** Ports allocated in correct range+- [ ] **MP2:** Ports released and reused+- [ ] **MC1:** Chrome initializes lazily within 10s+- [ ] **MC2:** Headed window appears < 5s+- [ ] **MU1:** Dashboard displays instances correctly+- [ ] **MU2:** Dashboard can create instances+- [ ] **MU3:** Dashboard can stop instances+- [ ] **ME1:** Bad profile names handled gracefully+- [ ] **ME2:** Port exhaustion handled gracefully+- [ ] **ME3:** Concurrent creation thread-safe+- [ ] **MI1:** Proxy routing works for navigation+- [ ] **MI2:** Proxy routing works for snapshot/screenshot++---++## Notes++- Tests should run on the same machine as the dashboard (needed for window verification and process monitoring).+- Some tests (MM1, MM2, MP1) require Linux/macOS tools (`lsof`, `ps`, `top`).+- All tests should clean up instances via API after completing (stop them).+- If running in CI/headless environment, skip visual tests (MH1, MH2, MU1, MU2) and window tests (MC2).