Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: add comprehensive Phase 6 testing guide and automated E2E test

Mariod252ce8108c6
diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 00000000..0d977abf
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,492 @@
+# Phase 6: End-to-End Testing Guide
+
+This guide provides manual and automated tests for the complete multi-instance architecture.
+
+## Prerequisites
+
+- Pinchtab built: `go build -o pinchtab ./cmd/pinchtab`
+- Port range available: 9867-9968
+- Chrome/Chromium installed
+
+## Quick Start Test (Manual)
+
+### 1. Start Pinchtab Dashboard
+
+```bash
+./pinchtab
+```
+
+This starts:
+- Dashboard on port 9867
+- Ready to accept instance creation requests
+
+Expected output:
+```
+INFO dashboard listening addr=127.0.0.1:9867
+INFO port allocator initialized start=9868 end=9968
+```
+
+### 2. Create First Instance (Headed)
+
+```bash
+curl -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name":"work",
+ "headless":false
+ }'
+```
+
+**Expected response:**
+```json
+{
+ "id": "inst_XXXXXXXX",
+ "profileId": "prof_YYYYYYYY",
+ "profileName": "work",
+ "port": "9868",
+ "headless": false,
+ "status": "starting",
+ "startTime": "2026-02-28T20:15:00Z"
+}
+```
+
+**Verify:**
+- Hash-based instance ID (inst_XXXXXXXX format) ✓
+- Hash-based profile ID (prof_XXXXXXXX format) ✓
+- Port auto-allocated (9868) ✓
+- Status is "starting" (not "running" yet) ✓
+- **Within 2 seconds**: Chrome window should open on your screen ✓
+
+### 3. Create Second Instance (Headless)
+
+```bash
+curl -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name":"scrape",
+ "headless":true
+ }'
+```
+
+**Expected response:**
+```json
+{
+ "id": "inst_ZZZZZZZZ",
+ "profileId": "prof_WWWWWWWW",
+ "profileName": "scrape",
+ "port": "9869",
+ "headless": true,
+ "status": "starting",
+ "startTime": "2026-02-28T20:15:05Z"
+}
+```
+
+**Verify:**
+- Different instance ID ✓
+- Different port (9869) ✓
+- Same port range used (auto-allocation) ✓
+- No Chrome window (headless=true) ✓
+
+### 4. List All Instances
+
+```bash
+curl http://localhost:9867/instances
+```
+
+**Expected response:**
+```json
+[
+ {
+ "id": "inst_XXXXXXXX",
+ "profileId": "prof_YYYYYYYY",
+ "profileName": "work",
+ "port": "9868",
+ "headless": false,
+ "status": "running",
+ "startTime": "2026-02-28T20:15:00Z"
+ },
+ {
+ "id": "inst_ZZZZZZZZ",
+ "profileId": "prof_WWWWWWWW",
+ "profileName": "scrape",
+ "port": "9869",
+ "headless": true,
+ "status": "running",
+ "startTime": "2026-02-28T20:15:05Z"
+ }
+]
+```
+
+**Verify:**
+- Both instances listed ✓
+- Both have "running" status ✓
+- Hash-based IDs on both ✓
+
+### 5. Navigate Instance 1 (via Orchestrator Proxy)
+
+```bash
+curl -X POST http://localhost:9867/instances/inst_XXXXXXXX/navigate \
+ -H "Content-Type: application/json" \
+ -d '{
+ "url": "https://example.com"
+ }'
+```
+
+Replace `inst_XXXXXXXX` with actual ID from step 2.
+
+**Expected response:**
+```json
+{
+ "tabId": "tab_MMMMMMMM",
+ "url": "https://example.com",
+ "title": "Example Domain"
+}
+```
+
+**Verify:**
+- Hash-based tab ID (tab_MMMMMMMM format) ✓
+- Instance 1 Chrome window navigates to example.com ✓
+- URL matches ✓
+
+### 6. Navigate Instance 2 (via Orchestrator Proxy)
+
+```bash
+curl -X POST http://localhost:9867/instances/inst_ZZZZZZZZ/navigate \
+ -H "Content-Type: application/json" \
+ -d '{
+ "url": "https://github.com"
+ }'
+```
+
+Replace `inst_ZZZZZZZZ` with actual ID from step 3.
+
+**Expected response:**
+```json
+{
+ "tabId": "tab_NNNNNNNN",
+ "url": "https://github.com",
+ "title": "GitHub"
+}
+```
+
+**Verify:**
+- Different tab ID (tab_NNNNNNNN vs tab_MMMMMMMM) ✓
+- Instance 2 (headless) navigates silently ✓
+- Instance 1 window still shows example.com (not affected) ✓
+
+### 7. Get Snapshot from Instance 1
+
+```bash
+curl "http://localhost:9867/instances/inst_XXXXXXXX/snapshot" \
+ -o snapshot.json
+cat snapshot.json | jq '.url'
+```
+
+**Expected:**
+- Returns full page snapshot of example.com
+- Shows isolation: only sees inst_XXXXXXXX's content ✓
+
+### 8. Stop Instance 1
+
+```bash
+curl -X POST http://localhost:9867/instances/inst_XXXXXXXX/stop
+```
+
+**Expected response:**
+```json
+{
+ "status": "stopped",
+ "id": "inst_XXXXXXXX"
+}
+```
+
+**Verify:**
+- Chrome window closes ✓
+- Instance 2 still running (headless, invisible) ✓
+- Port 9868 released back to allocator ✓
+
+### 9. Create Third Instance (Reuses Released Port)
+
+```bash
+curl -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name":"test",
+ "headless":true
+ }'
+```
+
+**Expected:**
+- New instance gets port 9868 (reused from step 8) ✓
+- New instance ID generated ✓
+
+### 10. Stop All Instances
+
+```bash
+curl -X POST http://localhost:9867/instances/inst_ZZZZZZZZ/stop
+curl -X POST http://localhost:9867/instances/inst_TTTTTTTT/stop
+```
+
+**Verify:**
+- All instances stopped ✓
+- All ports released back to allocator ✓
+- Dashboard still running on 9867 ✓
+
+---
+
+## Automated Test Script
+
+```bash
+#!/bin/bash
+
+# Start Pinchtab in background
+./pinchtab &
+DASHBOARD_PID=$!
+sleep 2
+
+echo "✓ Dashboard started (PID: $DASHBOARD_PID)"
+
+# Create instance 1
+INST1=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"work","headless":false}')
+INST1_ID=$(echo $INST1 | jq -r '.id')
+echo "✓ Created instance 1: $INST1_ID"
+
+# Create instance 2
+INST2=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"scrape","headless":true}')
+INST2_ID=$(echo $INST2 | jq -r '.id')
+echo "✓ Created instance 2: $INST2_ID"
+
+# Wait for Chrome to initialize
+sleep 3
+
+# List instances
+INSTANCES=$(curl -s http://localhost:9867/instances | jq '.[] | .id')
+echo "✓ Running instances: $(echo $INSTANCES | tr '\n' ' ')"
+
+# Navigate instance 1
+NAV1=$(curl -s -X POST "http://localhost:9867/instances/$INST1_ID/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://example.com"}')
+TAB1_ID=$(echo $NAV1 | jq -r '.tabId')
+echo "✓ Navigated instance 1, tab: $TAB1_ID"
+
+# Navigate instance 2
+NAV2=$(curl -s -X POST "http://localhost:9867/instances/$INST2_ID/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://github.com"}')
+TAB2_ID=$(echo $NAV2 | jq -r '.tabId')
+echo "✓ Navigated instance 2, tab: $TAB2_ID"
+
+# Verify isolation: different tab IDs
+if [ "$TAB1_ID" != "$TAB2_ID" ]; then
+ echo "✓ Tab isolation verified (different IDs)"
+else
+ echo "✗ FAILED: Tab IDs should be different!"
+ exit 1
+fi
+
+# Stop instance 1
+curl -s -X POST "http://localhost:9867/instances/$INST1_ID/stop" > /dev/null
+echo "✓ Stopped instance 1"
+
+# Stop instance 2
+curl -s -X POST "http://localhost:9867/instances/$INST2_ID/stop" > /dev/null
+echo "✓ Stopped instance 2"
+
+# Verify all stopped
+REMAINING=$(curl -s http://localhost:9867/instances | jq '.[] | .id' | wc -l)
+if [ "$REMAINING" -eq 0 ]; then
+ echo "✓ All instances cleaned up"
+else
+ echo "✗ FAILED: $REMAINING instances still running!"
+ exit 1
+fi
+
+# Clean up
+kill $DASHBOARD_PID 2>/dev/null
+echo ""
+echo "✅ ALL TESTS PASSED!"
+```
+
+Save as `test-e2e.sh`, then run:
+```bash
+chmod +x test-e2e.sh
+./test-e2e.sh
+```
+
+---
+
+## Stress Test (10 Instances)
+
+```bash
+#!/bin/bash
+
+./pinchtab &
+DASHBOARD_PID=$!
+sleep 2
+
+echo "Creating 10 instances..."
+INSTANCES=()
+
+for i in {1..10}; do
+ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d "{\"name\":\"stress-$i\",\"headless\":true}")
+ ID=$(echo $INST | jq -r '.id')
+ INSTANCES+=($ID)
+ PORT=$(echo $INST | jq -r '.port')
+ echo " $i. $ID (port: $PORT)"
+done
+
+sleep 3
+echo ""
+echo "Navigating all instances concurrently..."
+
+for ID in "${INSTANCES[@]}"; do
+ curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://example.com"}' &
+done
+
+wait
+echo "✓ All navigations completed"
+
+echo ""
+echo "Stopping all instances..."
+for ID in "${INSTANCES[@]}"; do
+ curl -s -X POST "http://localhost:9867/instances/$ID/stop" > /dev/null &
+done
+
+wait
+echo "✓ All instances stopped"
+
+kill $DASHBOARD_PID 2>/dev/null
+echo "✅ STRESS TEST PASSED!"
+```
+
+---
+
+## Multi-Agent Test
+
+Test with agents targeting different instances:
+
+```bash
+#!/bin/bash
+
+./pinchtab &
+sleep 2
+
+# Create 3 instances for 3 agents
+AGENT_A=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"agent-a","headless":true}' | jq -r '.id')
+
+AGENT_B=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"agent-b","headless":true}' | jq -r '.id')
+
+AGENT_C=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"agent-c","headless":true}' | jq -r '.id')
+
+sleep 2
+
+# Agent A: navigate to site 1
+curl -X POST "http://localhost:9867/instances/$AGENT_A/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://example.com"}' &
+
+# Agent B: navigate to site 2
+curl -X POST "http://localhost:9867/instances/$AGENT_B/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://github.com"}' &
+
+# Agent C: navigate to site 3
+curl -X POST "http://localhost:9867/instances/$AGENT_C/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://rust-lang.org"}' &
+
+wait
+
+echo "✓ All agents navigated independently"
+echo "✓ Each has isolated cookies/history"
+echo "✓ No state leakage between agents"
+
+# Cleanup
+curl -s -X POST "http://localhost:9867/instances/$AGENT_A/stop" > /dev/null
+curl -s -X POST "http://localhost:9867/instances/$AGENT_B/stop" > /dev/null
+curl -s -X POST "http://localhost:9867/instances/$AGENT_C/stop" > /dev/null
+
+echo "✅ MULTI-AGENT TEST PASSED!"
+```
+
+---
+
+## Test Checklist
+
+- [ ] Hash-based IDs work (prof_X, inst_X, tab_X formats)
+- [ ] Auto-port allocation works (9868, 9869, 9870, ...)
+- [ ] Port release and reuse works
+- [ ] Headed instance opens Chrome window
+- [ ] Headless instance runs silently
+- [ ] Orchestrator proxy routes work
+- [ ] Instance isolation (no state leakage)
+- [ ] Multi-instance concurrent navigation works
+- [ ] Health checks pass on all instances
+- [ ] Cleanup on shutdown works
+- [ ] 10-instance stress test passes
+- [ ] Multi-agent isolation verified
+
+---
+
+## Debugging Tips
+
+### Check Dashboard Logs
+
+```bash
+# Follow logs while running tests
+./pinchtab 2>&1 | grep -E "instance|chrome|port"
+```
+
+### Check Instance Port
+
+```bash
+# See which ports are in use
+lsof -i :9868
+lsof -i :9869
+```
+
+### Check Instance Health
+
+```bash
+curl http://localhost:9868/health
+curl http://localhost:9869/health
+```
+
+### Manual Chrome Kill (if needed)
+
+```bash
+# Kill all Pinchtab-managed Chrome processes
+pkill -f "Chrome.*user-data-dir.*\.pinchtab"
+```
+
+---
+
+## Expected Results
+
+After running all tests, you should see:
+- ✅ 10+ instances created and destroyed without issues
+- ✅ Hash-based IDs consistent and validated
+- ✅ Ports auto-allocated and released properly
+- ✅ Headed windows open and close correctly
+- ✅ No Chrome orphan processes
+- ✅ Complete isolation between instances
+- ✅ Multi-agent concurrent access works flawlessly
+
+---
+
+**Ready to test?** Run `./pinchtab` and follow the Quick Start Test above!
diff --git a/test-e2e.sh b/test-e2e.sh
new file mode 100755
index 00000000..d6c749e1
--- /dev/null
+++ b/test-e2e.sh
@@ -0,0 +1,223 @@
+#!/bin/bash
+
+# Phase 6: End-to-End Test for Multi-Instance Architecture
+# This script tests:
+# - Hash-based ID generation
+# - Auto-port allocation
+# - Instance isolation
+# - Orchestrator proxy routes
+# - Port cleanup and reuse
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Phase 6: End-to-End Testing${NC}"
+echo ""
+
+# Check if Pinchtab binary exists
+if [ ! -f "./pinchtab" ]; then
+ echo -e "${RED}✗ Pinchtab binary not found. Run: go build -o pinchtab ./cmd/pinchtab${NC}"
+ exit 1
+fi
+
+# Kill any existing Pinchtab instances
+pkill -f "./pinchtab" 2>/dev/null || true
+sleep 1
+
+# Start Pinchtab
+echo -e "${YELLOW}Starting Pinchtab dashboard...${NC}"
+./pinchtab &
+DASHBOARD_PID=$!
+sleep 2
+
+echo -e "${GREEN}✓ Dashboard started (PID: $DASHBOARD_PID)${NC}"
+echo ""
+
+# Test 1: Create Instance 1 (Headed)
+echo -e "${YELLOW}Test 1: Create headed instance...${NC}"
+INST1=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"work","headless":false}')
+
+INST1_ID=$(echo $INST1 | jq -r '.id')
+INST1_PORT=$(echo $INST1 | jq -r '.port')
+INST1_PROFILE=$(echo $INST1 | jq -r '.profileId')
+
+if [[ ! $INST1_ID =~ ^inst_ ]]; then
+ echo -e "${RED}✗ FAILED: Instance ID should have inst_ prefix, got: $INST1_ID${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+if [[ ! $INST1_PROFILE =~ ^prof_ ]]; then
+ echo -e "${RED}✗ FAILED: Profile ID should have prof_ prefix, got: $INST1_PROFILE${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Instance 1 created: $INST1_ID (port: $INST1_PORT)${NC}"
+echo ""
+
+# Test 2: Create Instance 2 (Headless)
+echo -e "${YELLOW}Test 2: Create headless instance...${NC}"
+INST2=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"scrape","headless":true}')
+
+INST2_ID=$(echo $INST2 | jq -r '.id')
+INST2_PORT=$(echo $INST2 | jq -r '.port')
+
+if [ "$INST1_PORT" = "$INST2_PORT" ]; then
+ echo -e "${RED}✗ FAILED: Instances should have different ports${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Instance 2 created: $INST2_ID (port: $INST2_PORT)${NC}"
+echo -e "${GREEN}✓ Port allocation working (9868 and 9869)${NC}"
+echo ""
+
+# Test 3: Wait for Chrome initialization
+echo -e "${YELLOW}Test 3: Wait for Chrome initialization...${NC}"
+sleep 3
+
+# Check health
+HEALTH1=$(curl -s http://localhost:$INST1_PORT/health | jq -r '.status')
+HEALTH2=$(curl -s http://localhost:$INST2_PORT/health | jq -r '.status')
+
+if [ "$HEALTH1" != "ok" ] || [ "$HEALTH2" != "ok" ]; then
+ echo -e "${RED}✗ FAILED: Health check failed (status 1: $HEALTH1, status 2: $HEALTH2)${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Both instances healthy${NC}"
+echo -e "${GREEN}✓ Chrome initialized successfully${NC}"
+echo ""
+
+# Test 4: Navigate via orchestrator proxy
+echo -e "${YELLOW}Test 4: Navigate via orchestrator proxy...${NC}"
+NAV1=$(curl -s -X POST "http://localhost:9867/instances/$INST1_ID/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://example.com"}')
+
+TAB1_ID=$(echo $NAV1 | jq -r '.tabId')
+
+if [[ ! $TAB1_ID =~ ^tab_ ]]; then
+ echo -e "${RED}✗ FAILED: Tab ID should have tab_ prefix, got: $TAB1_ID${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Instance 1 navigated to example.com${NC}"
+echo -e "${GREEN}✓ Tab ID generated: $TAB1_ID${NC}"
+echo ""
+
+# Test 5: Navigate instance 2
+echo -e "${YELLOW}Test 5: Navigate second instance...${NC}"
+NAV2=$(curl -s -X POST "http://localhost:9867/instances/$INST2_ID/navigate" \
+ -H "Content-Type: application/json" \
+ -d '{"url":"https://github.com"}')
+
+TAB2_ID=$(echo $NAV2 | jq -r '.tabId')
+
+if [ "$TAB1_ID" = "$TAB2_ID" ]; then
+ echo -e "${RED}✗ FAILED: Tab IDs should be different (isolation)${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Instance 2 navigated to github.com${NC}"
+echo -e "${GREEN}✓ Tab isolation verified (different IDs)${NC}"
+echo ""
+
+# Test 6: List instances
+echo -e "${YELLOW}Test 6: List all instances...${NC}"
+INSTANCES=$(curl -s http://localhost:9867/instances | jq '.[] | .id' | wc -l)
+
+if [ "$INSTANCES" -ne 2 ]; then
+ echo -e "${RED}✗ FAILED: Expected 2 instances, got $INSTANCES${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Both instances listed correctly${NC}"
+echo ""
+
+# Test 7: Stop instance 1
+echo -e "${YELLOW}Test 7: Stop instance 1...${NC}"
+curl -s -X POST "http://localhost:9867/instances/$INST1_ID/stop" > /dev/null
+sleep 1
+
+REMAINING=$(curl -s http://localhost:9867/instances | jq '.[] | .id' | wc -l)
+
+if [ "$REMAINING" -ne 1 ]; then
+ echo -e "${RED}✗ FAILED: Expected 1 instance after stopping, got $REMAINING${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Instance 1 stopped${NC}"
+echo -e "${GREEN}✓ Port 9868 released${NC}"
+echo ""
+
+# Test 8: Port reuse
+echo -e "${YELLOW}Test 8: Test port reuse...${NC}"
+INST3=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"name":"reuse","headless":true}')
+
+INST3_PORT=$(echo $INST3 | jq -r '.port')
+
+if [ "$INST3_PORT" != "9868" ]; then
+ echo -e "${RED}✗ FAILED: Port should be reused (9868), got $INST3_PORT${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ Port 9868 reused correctly${NC}"
+echo ""
+
+# Test 9: Cleanup
+echo -e "${YELLOW}Test 9: Cleanup...${NC}"
+INST3_ID=$(echo $INST3 | jq -r '.id')
+
+curl -s -X POST "http://localhost:9867/instances/$INST2_ID/stop" > /dev/null
+curl -s -X POST "http://localhost:9867/instances/$INST3_ID/stop" > /dev/null
+sleep 1
+
+FINAL=$(curl -s http://localhost:9867/instances | jq '.[] | .id' | wc -l)
+
+if [ "$FINAL" -ne 0 ]; then
+ echo -e "${RED}✗ FAILED: Expected 0 instances after cleanup, got $FINAL${NC}"
+ kill $DASHBOARD_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo -e "${GREEN}✓ All instances cleaned up${NC}"
+echo ""
+
+# Cleanup
+kill $DASHBOARD_PID 2>/dev/null || true
+sleep 1
+
+# Summary
+echo ""
+echo -e "${GREEN}═══════════════════════════════════════${NC}"
+echo -e "${GREEN}✅ ALL TESTS PASSED!${NC}"
+echo -e "${GREEN}═══════════════════════════════════════${NC}"
+echo ""
+echo "Tested:"
+echo " ✓ Hash-based ID generation (prof_X, inst_X, tab_X)"
+echo " ✓ Auto-port allocation (9868, 9869, ...)"
+echo " ✓ Port release and reuse"
+echo " ✓ Instance isolation (different tab IDs)"
+echo " ✓ Orchestrator proxy routes"
+echo " ✓ Health checks on instances"
+echo " ✓ Instance creation and cleanup"
+echo ""