Skip to content

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.md
index 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.go
new file mode 100644
index 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.md
new file mode 100644
index 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).