High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore: integration tests review and cleanup
Luigi Agostib2757a2400ef
diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.ymlindex 80276d6d..34d9be8f 100644--- a/.github/workflows/integration.yml+++ b/.github/workflows/integration.yml@@ -45,14 +45,14 @@ jobs:- 'internal/**'- 'tests/integration/**'- integration-core:- name: Integration Tests (Core)+ integration:+ name: Integration Testsneeds: changesruns-on: ubuntu-latesttimeout-minutes: 12if: needs.changes.outputs.go == 'true'env:- CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'+ SYSTEM_REGEX: '^(TestProxy_InstanceIsolation|TestOrchestrator_(HealthCheck|HashBasedIDs|PortAllocation|PortReuse|ListInstances|FirstRequestLazyChrome|AggregateTabsEndpoint|StopNonexistent|InstanceCleanup))$'steps:- uses: actions/checkout@v4@@ -71,12 +71,12 @@ jobs:- name: Install gotestsumrun: go install gotest.tools/gotestsum@latest- - name: π§ͺ Run core integration tests+ - name: π§ͺ Run integration testsrun: |- echo "::group::Core Integration Tests Output"- gotestsum --format testname --jsonfile core-events.json -- \+ echo "::group::Integration Tests Output"+ gotestsum --format testname --jsonfile integration-events.json -- \-tags integration -v -timeout 10m -count=1 \- -run "$CORE_REGEX" ./tests/integration/+ -run '^Test' -skip "$SYSTEM_REGEX" ./tests/integration/echo "::endgroup::"env:CI: "true"@@ -98,85 +98,16 @@ jobs:fail=0skip=0- if [ -s core-events.json ]; then- read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' core-events.json \+ if [ -s integration-events.json ]; then+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' integration-events.json \| awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"fi- echo "### β Integration Core Tests" >> "$GITHUB_STEP_SUMMARY"+ echo "### β Integration Tests" >> "$GITHUB_STEP_SUMMARY"echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"echo "- **Port**: 19867" >> "$GITHUB_STEP_SUMMARY"- echo "- **Regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"- echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"- echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"- echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"- echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"-- integration-rest:- name: Integration Tests (Rest)- needs: changes- runs-on: ubuntu-latest- timeout-minutes: 15- if: needs.changes.outputs.go == 'true'- env:- CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'- steps:- - uses: actions/checkout@v4-- - uses: actions/setup-go@v5- with:- go-version: '1.26'-- - name: Install Google Chrome (deb, avoids snap hangs)- run: |- wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -- echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list- sudo apt-get update- sudo apt-get install -y google-chrome-stable- echo "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV-- - name: Install gotestsum- run: go install gotest.tools/gotestsum@latest-- - name: π§ͺ Run rest integration tests- run: |- echo "::group::Rest Integration Tests Output"- gotestsum --format testname --jsonfile rest-events.json -- \- -tags integration -v -timeout 12m -count=1 \- -run '^Test' -skip "$CORE_REGEX" ./tests/integration/- echo "::endgroup::"- env:- CI: "true"- BRIDGE_HEADLESS: "true"- BRIDGE_NO_RESTORE: "true"- PINCHTAB_TEST_PORT: "19868"- PINCHTAB_TEST_RETRY: "true"- PINCHTAB_ALLOW_EVALUATE: "true"- PINCHTAB_ALLOW_MACRO: "true"- PINCHTAB_ALLOW_DOWNLOAD: "true"- PINCHTAB_ALLOW_UPLOAD: "true"- PINCHTAB_ALLOW_SCREENCAST: "true"-- - name: π Add summary- if: always()- run: |- total=0- pass=0- fail=0- skip=0-- if [ -s rest-events.json ]; then- read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' rest-events.json \- | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"- fi-- echo "### β Integration Rest Tests" >> "$GITHUB_STEP_SUMMARY"- echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"- echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"- echo "- **Port**: 19868" >> "$GITHUB_STEP_SUMMARY"- echo "- **Selection**: all integration tests with core tests skipped" >> "$GITHUB_STEP_SUMMARY"- echo "- **Skip regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Skip regex**: \`$SYSTEM_REGEX\`" >> "$GITHUB_STEP_SUMMARY"echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/system.yml b/.github/workflows/system.ymlnew file mode 100644index 00000000..137e1524--- /dev/null+++ b/.github/workflows/system.yml@@ -0,0 +1,74 @@+name: System Tests++on:+ workflow_dispatch:++permissions:+ contents: read++jobs:+ system:+ name: System Tests+ runs-on: ubuntu-latest+ timeout-minutes: 20+ env:+ SYSTEM_REGEX: '^(TestProxy_InstanceIsolation|TestOrchestrator_(HealthCheck|HashBasedIDs|PortAllocation|PortReuse|ListInstances|FirstRequestLazyChrome|AggregateTabsEndpoint|StopNonexistent|InstanceCleanup))$'+ steps:+ - uses: actions/checkout@v4++ - uses: actions/setup-go@v5+ with:+ go-version: '1.26'++ - name: Install Google Chrome (deb, avoids snap hangs)+ run: |+ wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -+ echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list+ sudo apt-get update+ sudo apt-get install -y google-chrome-stable+ echo "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV++ - name: Install gotestsum+ run: go install gotest.tools/gotestsum@latest++ - name: π§ͺ Run system tests+ run: |+ echo "::group::System Tests Output"+ gotestsum --format testname --jsonfile system-events.json -- \+ -tags integration -v -timeout 15m -count=1 \+ -run "$SYSTEM_REGEX" ./tests/integration/+ echo "::endgroup::"+ env:+ CI: "true"+ BRIDGE_HEADLESS: "true"+ BRIDGE_NO_RESTORE: "true"+ PINCHTAB_TEST_PORT: "19869"+ PINCHTAB_TEST_RETRY: "true"+ PINCHTAB_ALLOW_EVALUATE: "true"+ PINCHTAB_ALLOW_MACRO: "true"+ PINCHTAB_ALLOW_DOWNLOAD: "true"+ PINCHTAB_ALLOW_UPLOAD: "true"+ PINCHTAB_ALLOW_SCREENCAST: "true"++ - name: π Add summary+ if: always()+ run: |+ total=0+ pass=0+ fail=0+ skip=0++ if [ -s system-events.json ]; then+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' system-events.json \+ | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"+ fi++ echo "### β System Tests" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Port**: 19869" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Regex**: \`$SYSTEM_REGEX\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex cc50fb8e..5529b983 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -5,18 +5,7 @@```bashgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab--# Build-go build -o pinchtab ./cmd/pinchtab--# Run (headed β Chrome window opens)-./pinchtab--# Run headless-PINCHTAB_HEADLESS=true ./pinchtab--# Enable pre-commit hook-git config core.hooksPath .githooks+./pdev doctor```Requires **Go 1.25+** and **Google Chrome**.@@ -24,11 +13,10 @@ Requires **Go 1.25+** and **Google Chrome**.## Development Workflow1. Make your changes-2. Format: `gofmt -w .`-3. Test: `go test ./... -count=1`-4. Lint: `golangci-lint run ./...`-5. Commit β pre-commit hook runs checks automatically-6. Push: `git pull --rebase && git push`+2. Run `./pdev check`+3. Run `./pdev test`+4. Commit β pre-commit hook runs checks automatically+5. Push: `git pull --rebase && git push`### Creating a Pull Request@@ -40,77 +28,33 @@ Requires **Go 1.25+** and **Google Chrome**.This significantly speeds up the merge process. Thank you! π-## Running Tests+## Checks and Tests```bash-# All unit tests-go test ./... -count=1 -v--# With coverage-go test ./... -coverprofile=coverage.out-go tool cover -func=coverage.out+./pdev doctor # setup environment and hooks+./pdev check # format, vet, build, lint+./pdev test # unit + integration + system+./pdev test unit+./pdev test integration+./pdev test system```-Most tests use a `mockBridge` and do not require a running Chrome instance.--### Integration Tests--Integration tests require Chrome and test the full stack:+If you want the raw commands instead of `pdev`:```bash-# Run integration tests-go test -tags integration ./tests/integration -v--# With retries for stability (recommended)-PINCHTAB_TEST_RETRY=true go test -tags integration ./tests/integration -v--# In CI or slow environments-CI=true go test -tags integration ./tests/integration -v -p 1 -timeout 5m--# Skip flaky tests-go test -tags integration ./tests/integration -v -short+go test ./... -count=1 -v+go test -tags integration ./tests/integration -v'```-**Tips for stable integration tests:**--- Run with `-p 1` to avoid Chrome resource contention-- Set `CI=true` for longer timeouts in CI environments-- Use `-timeout 5m` to allow for Chrome startup-- Tests will automatically retry failed requests when `PINCHTAB_TEST_RETRY=true`--## Project Layout--The project follows the standard Go `internal/` pattern to ensure encapsulation and clean boundaries:--- `cmd/pinchtab/` β Application entry points and CLI commands.-- `internal/bridge/` β Core CDP logic, tab management, and state logic.-- `internal/handlers/` β HTTP API handlers and middleware.-- `internal/orchestrator/` β Multi-instance lifecycle and process management.-- `internal/profiles/` β Chrome profile management and user identity discovery.-- `internal/dashboard/` β Backend logic and static assets for the web UI.-- `internal/assets/` β Centralized embedded files (stealth scripts, CSS).-- `internal/human/` β Human-like interaction simulation (Bezier mouse paths, natural typing).-- `internal/web/` β Shared HTTP and JSON utilities.-## Style-- `gofmt` enforced (CI + pre-commit)- Adhere to **SOLID** principles, specifically using interfaces for dependency inversion.- Handle all error returns explicitly.- Lowercase error strings, wrap with `%w`.- Tests should live in the same package as the source code.- No new dependencies without significant technical justification.+- Comments when necessary-## For AI Agents--See [AGENTS.md](AGENTS.md) for detailed conventions and patterns when contributing via an agentic workflow.--## β οΈ Pre-commit Hook Setup Required--To prevent formatting issues, run this after cloning:--```bash-git config core.hooksPath .githooks-```+## Hooks-This enforces gofmt, go vet, and tests before each commit.+`./pdev doctor` installs the git hooks. They enforce formatting and checks before commit.diff --git a/TESTING.md b/TESTING.mdindex cb6c2927..5d395956 100644--- a/TESTING.md+++ b/TESTING.md@@ -6,10 +6,11 @@ The `pdev` developer toolkit is the easiest way to run checks and tests:```bash./pdev # Interactive picker-./pdev test # All tests (unit + integration)+./pdev test # All tests (unit + integration + system)./pdev test unit # Unit tests only./pdev test integration # Integration tests only-./pdev check # All checks (format, vet, build, test, lint)+./pdev test system # System tests only+./pdev check # All checks (format, vet, build, lint)./pdev check go # Go checks only./pdev check security # Gosec security scan./pdev hooks # Install git hooks (pre-commit)@@ -29,11 +30,25 @@ go test ./...Integration tests launch a real pinchtab server with Chrome and run HTTP-level tests against it.```bash-go test -tags integration ./tests/integration/ -v -timeout 5m+go test -tags integration ./tests/integration/ -v -timeout 10m -skip '^(TestProxy_InstanceIsolation|TestOrchestrator_(HealthCheck|HashBasedIDs|PortAllocation|PortReuse|ListInstances|FirstRequestLazyChrome|AggregateTabsEndpoint|StopNonexistent|InstanceCleanup))$'# or./pdev test integration```+These cover the single-instance HTTP-level suite plus the always-run orchestrator/proxy smoke coverage.++## System Tests++System tests are the heavier optional orchestrator/proxy regression suite:++```bash+go test -tags integration ./tests/integration/ -v -timeout 15m -run '^(TestProxy_InstanceIsolation|TestOrchestrator_(HealthCheck|HashBasedIDs|PortAllocation|PortReuse|ListInstances|FirstRequestLazyChrome|AggregateTabsEndpoint|StopNonexistent|InstanceCleanup))$'+# or+./pdev test system+```++In GitHub Actions, `system` is in a separate manual workflow: [`.github/workflows/system.yml`](/Users/luigi/dev/prj/giago/pt-bosch/.github/workflows/system.yml). You can run it from the Actions tab against a PR branch.+### Environment Variables| Variable | Default | Description |@@ -82,7 +97,7 @@ New tests should use `testutil.Client` and `testutil.NewTestServer` (or `StartSepackage integrationfunc TestMyFeature(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := client.Get(t, "/snapshot")if code != 200 {diff --git a/docs/architecture/building.md b/docs/architecture/building.mdindex a2d19121..c67fa7e9 100644--- a/docs/architecture/building.md+++ b/docs/architecture/building.md@@ -219,8 +219,8 @@ curl http://localhost:9867/health### Try CLI```bash-./pinchtab quick https://example.com-./pinchtab nav https://github.com+./pinchtab quick https://pinchtab.com+./pinchtab nav https://pinchtab.com./pinchtab snap```@@ -259,9 +259,10 @@ All dev scripts are accessible through `./pdev`:| `check dashboard` | Dashboard checks only || `check security` | Gosec security scan || `check docs` | Validate docs JSON |-| `test` | All tests (unit + integration) |+| `test` | All tests (unit + integration + system) || `test unit` | Unit tests only || `test integration` | Integration tests only |+| `test system` | System tests only || `build` | Build & run (default) || `doctor` | Setup dev environment || `hooks` | Install git hooks |@@ -276,7 +277,7 @@ pdev() { if [ -x "./pdev" ]; then ./pdev "$@"; else echo "pdev not found in curr### Code Quality```bash-./pdev check # Full pre-push checks (recommended)+./pdev check # Full non-test checks (recommended)gofmt -w . # Format codegolangci-lint run # Lint./pdev doctor # Verify environmentdiff --git a/pdev b/pdevindex 683f3bd2..17cd14f0 100755--- a/pdev+++ b/pdev@@ -22,9 +22,10 @@ COMMANDS=(" check dashboard:π§ͺ:Dashboard only"" check security:π§ͺ:Gosec security scan"" check docs:π§ͺ:Validate docs JSON"- "test:π¬:All tests (unit + integration)"+ "test:π¬:All tests (unit + integration + system)"" test unit:π¬:Unit tests only"" test integration:π¬:Integration tests only"+ " test system:π¬:System tests only""build:π:Build & run (default)""doctor:π©Ί:Setup dev environment""hooks:πͺ:Install git hooks"@@ -79,6 +80,16 @@ run_command() {echo ""exec bash scripts/check-dashboard.sh;;+ "check security")+ echo " ${ACCENT}${BOLD}π Security scan${NC}"+ echo ""+ exec bash scripts/check-gosec.sh+ ;;+ "check docs")+ echo " ${ACCENT}${BOLD}π Docs validation${NC}"+ echo ""+ exec bash scripts/check-docs-json.sh+ ;;"test")echo " ${ACCENT}${BOLD}π¬ All tests${NC}"echo ""@@ -94,15 +105,10 @@ run_command() {echo ""exec bash scripts/test.sh integration;;- "check security")- echo " ${ACCENT}${BOLD}π Security scan${NC}"+ "test system")+ echo " ${ACCENT}${BOLD}π¬ System tests${NC}"echo ""- exec bash scripts/check-gosec.sh- ;;- "check docs")- echo " ${ACCENT}${BOLD}π Docs validation${NC}"- echo ""- exec bash scripts/check-docs-json.sh+ exec bash scripts/test.sh system;;"build") exec bash scripts/dev.sh ;;"doctor") exec bash scripts/doctor.sh ;;@@ -139,6 +145,8 @@ pick_with_gum() {# Extract command name (first non-space word(s) after optional emoji)local pickedpicked=$(echo "$choice" | sed 's/^[^a-z]*//' | awk '{if ($2 ~ /^[a-z]/) print $1, $2; else print $1}')+ # Clear the picker before streaming command output.+ printf '\033[2J\033[H'run_command "$picked"}@@ -153,9 +161,9 @@ pick_with_select() {IFS=':' read -r name emoji desc <<< "$cmd"local trimmed="${name#"${name%%[![:space:]]*}"}"if [[ "$name" == " "* ]]; then- printf " ${MUTED}[%2d]${NC} ${BOLD}%-18s${NC} ${MUTED}%s${NC}\n" "$i" "$trimmed" "$desc"+ printf " ${MUTED}[%3d]${NC} ${BOLD}%-18s${NC} ${MUTED}%s${NC}\n" "$i" "$trimmed" "$desc"else- printf " ${MUTED}[%2d]${NC} ${SUCCESS}%s${NC} ${BOLD}%-18s${NC} ${MUTED}%s${NC}\n" "$i" "$emoji" "$trimmed" "$desc"+ printf " ${MUTED}[%3d]${NC} ${SUCCESS}%s${NC} ${BOLD}%-18s${NC} ${MUTED}%s${NC}\n" "$i" "$emoji" "$trimmed" "$desc"finames+=("$trimmed")i=$((i + 1))diff --git a/scripts/README.md b/scripts/README.mdindex 399cfeaf..f046eab4 100644--- a/scripts/README.md+++ b/scripts/README.md@@ -8,11 +8,11 @@ Development and CI scripts for PinchTab.| Script | Purpose ||--------|---------|-| `check.sh` | Go pre-push checks (format, vet, build, test, lint) |-| `check-dashboard.sh` | Dashboard checks (typecheck, eslint, prettier, vitest) |+| `check.sh` | Go checks (format, vet, build, lint) |+| `check-dashboard.sh` | Dashboard checks (typecheck, eslint, prettier) || `check-gosec.sh` | Security scan with gosec (reproduces CI security job) || `check-docs-json.sh` | Validate `docs/index.json` structure |-| `test.sh` | Go test runner with progress (unit, integration, or all) |+| `test.sh` | Go test runner with progress (unit, integration, system, or all) || `pre-commit` | Git pre-commit hook (format + lint) |## Build & Rundiff --git a/scripts/check-dashboard.sh b/scripts/check-dashboard.shindex c7e0b2b3..d9951c77 100755--- a/scripts/check-dashboard.sh+++ b/scripts/check-dashboard.sh@@ -2,7 +2,7 @@set -e# check-dashboard.sh β Dashboard quality checks (matches CI: dashboard.yml)-# Runs: typecheck β eslint β prettier β vitest+# Runs: typecheck β eslint β prettiercd "$(dirname "$0")/.."@@ -18,7 +18,7 @@ fail() { echo -e " ${ERROR}β${NC} $1"; [ -n "${2:-}" ] && echo -e " ${MUTEsection() {echo ""- echo -e "${ACCENT}${BOLD}$1${NC}"+ echo -e " ${ACCENT}${BOLD}$1${NC}"}if [ ! -d "dashboard" ]; then@@ -71,14 +71,6 @@ elseexit 1fi-section "Tests"-if $RUN run test:run 2>&1; then- ok "All tests passed"-else- fail "Test failures"- exit 1-fi-section "Summary"echo ""echo -e " ${SUCCESS}${BOLD}Dashboard checks passed!${NC}"diff --git a/scripts/check.sh b/scripts/check.shindex c6237296..638c31e4 100755--- a/scripts/check.sh+++ b/scripts/check.sh@@ -2,7 +2,7 @@set -e# check.sh β Local pre-push checks matching GitHub Actions CI-# Runs: format β vet β build β tests (via test.sh) β lint+# Runs: format β vet β build β lintcd "$(dirname "$0")/.."@@ -20,7 +20,7 @@ hint() { echo -e " ${MUTED}$1${NC}"; }section() {echo ""- echo -e "${ACCENT}${BOLD}$1${NC}"+ echo -e " ${ACCENT}${BOLD}$1${NC}"}trap 'rm -f pinchtab coverage.out 2>/dev/null' EXIT@@ -71,10 +71,6 @@ if ! go build -o pinchtab ./cmd/pinchtab 2>&1; thenfiok "go build"-# ββ Tests (delegates to test.sh) βββββββββββββββββββββββββββββββββββββ--bash scripts/test.sh all-# ββ Lint βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββsection "Lint"diff --git a/scripts/test.sh b/scripts/test.shindex 151a2ba1..b2861085 100755--- a/scripts/test.sh+++ b/scripts/test.sh@@ -2,7 +2,7 @@set -e# test.sh β Run Go tests with optional scope-# Usage: test.sh [unit|integration|all]+# Usage: test.sh [unit|integration|system|all]# Default: allcd "$(dirname "$0")/.."@@ -14,14 +14,14 @@ ERROR=$'\033[38;2;230;57;70m'MUTED=$'\033[38;2;90;100;128m'NC=$'\033[0m'-CORE_REGEX='^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'+SYSTEM_REGEX='^(TestProxy_InstanceIsolation|TestOrchestrator_(HealthCheck|HashBasedIDs|PortAllocation|PortReuse|ListInstances|FirstRequestLazyChrome|AggregateTabsEndpoint|StopNonexistent|InstanceCleanup))$'ok() { echo -e " ${SUCCESS}β${NC} $1"; }fail() { echo -e " ${ERROR}β${NC} $1"; }section() {echo ""- echo -e "${ACCENT}${BOLD}$1${NC}"+ echo -e " ${ACCENT}${BOLD}$1${NC}"}# Parse gotestsum JSON and print summary@@ -64,7 +64,7 @@ test_summary() {# Live progress for integration testsrun_integration() {local json_file="$1"; shift- local count=0+ local completed=0local max_len=40go test -json "$@" 2>&1 | tee "$json_file" | while IFS= read -r line; do@@ -81,21 +81,21 @@ run_integration() {ficase "$action" in- run) printf "\r ${MUTED}βΈ %-${max_len}s${NC} \r" "$display" ;;- pass) count=$((count + 1))+ run) printf "\r ${MUTED}βΈ${NC} ${MUTED}[%2d]${NC} %-${max_len}s" "$((completed + 1))" "$display" ;;+ pass) completed=$((completed + 1))if [ -n "$elapsed" ]; then- printf "\r ${SUCCESS}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED}%6ss${NC}\n" "$count" "$display" "$elapsed"+ printf "\r ${SUCCESS}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED}%6ss${NC}" "$completed" "$display" "$elapsed"else- printf "\r ${SUCCESS}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s\n" "$count" "$display"+ printf "\r ${SUCCESS}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s" "$completed" "$display"fi ;;- fail) count=$((count + 1))+ fail) completed=$((completed + 1))if [ -n "$elapsed" ]; then- printf "\r ${ERROR}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED}%6ss${NC}\n" "$count" "$display" "$elapsed"+ printf "\r ${ERROR}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED}%6ss${NC}" "$completed" "$display" "$elapsed"else- printf "\r ${ERROR}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s\n" "$count" "$display"+ printf "\r ${ERROR}β${NC} ${MUTED}[%2d]${NC} %-${max_len}s" "$completed" "$display"fi ;;- skip) count=$((count + 1))- printf "\r ${ACCENT}Β·${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED} skip${NC}\n" "$count" "$display" ;;+ skip) completed=$((completed + 1))+ printf "\r ${ACCENT}Β·${NC} ${MUTED}[%2d]${NC} %-${max_len}s ${MUTED} skip${NC}" "$completed" "$display" ;;esacdonereturn ${PIPESTATUS[0]}@@ -132,40 +132,40 @@ if [ "$SCOPE" = "all" ] || [ "$SCOPE" = "unit" ]; thentest_summary "$UNIT_JSON" "Unit Test Results"fi-# ββ Integration tests (Core) ββββββββββββββββββββββββββββββββββββββββ+# ββ Integration tests βββββββββββββββββββββββββββββββββββββββββββββββif [ "$SCOPE" = "all" ] || [ "$SCOPE" = "integration" ]; then- section "Integration Tests (Core)"+ section "Integration Tests"- CORE_JSON="$TMPDIR_TEST/core.json"+ INTEGRATION_JSON="$TMPDIR_TEST/integration.json"- if ! run_integration "$CORE_JSON" \+ if ! run_integration "$INTEGRATION_JSON" \-tags integration -timeout 10m -count=1 \- -run "$CORE_REGEX" ./tests/integration/; then- fail "Integration core"- test_summary "$CORE_JSON" "Core Test Results"+ -run '^Test' -skip "$SYSTEM_REGEX" ./tests/integration/; then+ fail "Integration tests"+ test_summary "$INTEGRATION_JSON" "Integration Test Results"exit 1fiprintf "\r%*s\r" 60 ""- ok "Integration core"- test_summary "$CORE_JSON" "Core Test Results"-- # ββ Integration tests (Rest) ββββββββββββββββββββββββββββββββββββ+ ok "Integration tests"+ test_summary "$INTEGRATION_JSON" "Integration Test Results"+fi- section "Integration Tests (Rest)"+if [ "$SCOPE" = "all" ] || [ "$SCOPE" = "system" ]; then+ section "System Tests"- REST_JSON="$TMPDIR_TEST/rest.json"+ SYSTEM_JSON="$TMPDIR_TEST/system.json"- if ! run_integration "$REST_JSON" \+ if ! run_integration "$SYSTEM_JSON" \-tags integration -timeout 12m -count=1 \- -run '^Test' -skip "$CORE_REGEX" ./tests/integration/; then- fail "Integration rest"- test_summary "$REST_JSON" "Rest Test Results"+ -run "$SYSTEM_REGEX" ./tests/integration/; then+ fail "System tests"+ test_summary "$SYSTEM_JSON" "System Test Results"exit 1fiprintf "\r%*s\r" 60 ""- ok "Integration rest"- test_summary "$REST_JSON" "Rest Test Results"+ ok "System tests"+ test_summary "$SYSTEM_JSON" "System Test Results"fi# ββ Summary ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββdiff --git a/tests/AGENT-TEST-TEMPLATE.md b/tests/AGENT-TEST-TEMPLATE.mddeleted file mode 100644index c0f66ea1..00000000--- a/tests/AGENT-TEST-TEMPLATE.md+++ /dev/null@@ -1,214 +0,0 @@-# Agent Test Replication Template--**For agents without Pinchtab to replicate token efficiency testing.**--> **Reference:** Based on [docs/agent-optimization.md](../../docs/agent-optimization.md) β validated Feb 2026 with Corriere.it, BBC News.--## Quick Start--Copy these steps into your session and run sequentially.-------## Test: Extract News Headlines + Measure Tokens--### Prerequisites-```bash-# 1. Verify pinchtab is running-curl http://localhost:9867/health-# Expected: {"status": "ok"}--# 2. Have jq installed (for JSON parsing)-which jq-```--### Test Steps (Copy + Paste)--**Step 1: Navigate**-```bash-BASE_URL="http://localhost:9867"-curl -s -X POST $BASE_URL/navigate \- -H "Content-Type: application/json" \- -d '{"url": "https://www.corriere.it"}' | jq '.tabId'-# Save the tabId for next steps-```--**Step 2: Wait for page load**-```bash-sleep 3-```--**Step 3: Test Method A β Full snapshot (baseline)**-```bash-echo "=== FULL SNAPSHOT ==="-curl -s $BASE_URL/snapshot > /tmp/snap-full.json-SIZE=$(wc -c < /tmp/snap-full.json)-TOKENS=$((SIZE / 4))-echo "Size: $SIZE bytes"-echo "Est. tokens: ~$TOKENS"-```--**Step 4: Test Method B β Compact snapshot (optimized)**-```bash-echo "=== COMPACT + FILTER SNAPSHOT ==="-curl -s "$BASE_URL/snapshot?format=compact&filter=interactive" > /tmp/snap-compact.json-SIZE=$(wc -c < /tmp/snap-compact.json)-TOKENS=$((SIZE / 4))-echo "Size: $SIZE bytes"-echo "Est. tokens: ~$TOKENS"-```--**Step 5: Test Method C β Text only (cheapest)**-```bash-echo "=== TEXT ONLY ==="-curl -s $BASE_URL/text > /tmp/text.json-SIZE=$(wc -c < /tmp/text.json)-TOKENS=$((SIZE / 4))-echo "Size: $SIZE bytes"-echo "Est. tokens: ~$TOKENS"-```--**Step 6: Compare results**-```bash-echo ""-echo "=== COMPARISON ==="-FULL=$(wc -c < /tmp/snap-full.json)-COMPACT=$(wc -c < /tmp/snap-compact.json)-TEXT=$(wc -c < /tmp/text.json)--SAVINGS=$((100 - (COMPACT * 100 / FULL)))-echo "Full snapshot: ~$((FULL / 4)) tokens (baseline)"-echo "Compact snapshot: ~$((COMPACT / 4)) tokens (savings: $SAVINGS%)"-echo "Text only: ~$((TEXT / 4)) tokens (savings: $((100 - (TEXT * 100 / FULL)))%)"-```-------## Sample Output--```-=== FULL SNAPSHOT ===-Size: 4250 bytes-Est. tokens: ~1062--=== COMPACT + FILTER SNAPSHOT ===-Size: 1850 bytes-Est. tokens: ~462--=== TEXT ONLY ===-Size: 925 bytes-Est. tokens: ~231--=== COMPARISON ===-Full snapshot: ~1062 tokens (baseline)-Compact snapshot: ~462 tokens (savings: 56%)-Text only: ~231 tokens (savings: 78%)-```-------## Instructions for Another Agent--**To replicate this test without any prior knowledge:**--1. **Get the test file:**- ```bash- curl -s https://raw.githubusercontent.com/pinchtab/pinchtab/main/tests/AGENT-TEST-TEMPLATE.md- ```--2. **Run each "Test Steps" command one by one** (they're independent)--3. **Record the token counts** in a table like above--4. **Compare:**- - Compact should be ~50-70% smaller than full- - Text should be ~75-85% smaller than full--5. **Report result:**- ```- β Token efficiency verified- - Full: 1062 tokens- - Compact: 462 tokens (56% savings)- - Text: 231 tokens (78% savings)- - Recommended: Use /text for reading, /snapshot?format=compact&filter=interactive for interaction- ```-------## Troubleshooting--| Issue | Solution |-|-------|----------|-| `curl: (7) Failed to connect` | Pinchtab not running. Run `pinchtab &` first |-| `jq not found` | Install: `brew install jq` (macOS) or `apt-get install jq` (Linux) |-| `404 not found` | Wrong endpoint. Check: `curl http://localhost:9867/health` |-| Token counts seem off | Use `echo $TEXT \| wc -c` for exact byte count; divide by 4 for rough token estimate |-------## For Exact Token Counting--Use Python + tiktoken (OpenAI's official tokenizer):--```python-import tiktoken-import json--with open('/tmp/snap-full.json') as f:- data = json.load(f)- text = json.dumps(data)--enc = tiktoken.encoding_for_model("gpt-4")-tokens = enc.encode(text)-print(f"Exact tokens: {len(tokens)}")-```--Or online: https://platform.openai.com/tokenizer-------## Next Steps--After confirming token efficiency:--1. **Extract specific headlines:**- ```bash- curl -s "$BASE_URL/snapshot?format=compact&filter=interactive" | \- jq '.nodes[] | select(.role == "heading") | {ref, title: .name}' | \- head -10- ```--2. **Use diff mode for repeated snapshots:**- ```bash- curl -s "$BASE_URL/snapshot?diff=true&format=compact" | wc -c- # Much smaller (only changes shown)- ```--3. **Test on other news sites:** Replace corriere.it with any site and rerun-------## BONUS: Pattern-Driven Approach (93% Savings) β--**This is the VALIDATED optimal method from docs/agent-optimization.md**--Instead of exploring different approaches, use this exact pattern:--```bash-curl -X POST http://localhost:9867/navigate \- -H "Content-Type: application/json" \- -d '{"url": "https://www.corriere.it"}' && \-sleep 3 && \-curl http://localhost:9867/snapshot | \-jq '.nodes[] | select(.name | length > 15) | .name' | \-head -30-```--**Why it works:**-- Navigate + 3-second wait = full accessibility tree (2,645 nodes on Corriere.it)-- jq filter = extract only headline-length text-- `head -30` = limit output (saves tokens)--**Token cost:** ~272 tokens (vs 3,842 exploratory)--**Lesson:** Clear instructions beat exploration by 14.2x βdiff --git a/tests/AUTOMATED.md b/tests/AUTOMATED.mddeleted file mode 100644index b24f1c95..00000000--- a/tests/AUTOMATED.md+++ /dev/null@@ -1,196 +0,0 @@-# Automated Integration Tests--This document tracks which scenarios from the test plan are now covered by automated CI tests in `integration/`.--**CI Workflow:** `.github/workflows/integration.yml` β runs on PRs and main branch pushes.--**Run locally:** `go test -tags integration -v -timeout 10m -count=1 ./tests/integration/`-------## Test Coverage (Automated)--### Health & Startup-- β **H1** β Health check (`GET /health` returns 200 with status=ok)--### Navigation-- β **N1** β Basic navigate to example.com-- β **N2** β Navigate returns title-- β **N3** β SPA title loading (httpbin.org/html)-- β **N4** β Navigate with newTab flag-- β **N5** β Navigate invalid URL returns error-- β **N6** β Navigate missing URL returns 400-- β **N7** β Navigate bad JSON returns 400-- β **N8** β Navigation timeout behavior (reserved IP timeout)--### Snapshot (Accessibility Tree)-- β **S1** β Basic snapshot returns nodes/tree-- β **S2** β Interactive filter works-- β **S3** β Depth filter works-- β **S4** β Text format output-- β **S5** β YAML format output-- β **S5** (variant) β maxTokens parameter-- β **S6** β Snapshot diff mode (optimized delta)-- β **S7** β Snapshot diff first call (graceful fallback)-- β **S8** β Snapshot file output (save to disk)-- β **S9** β Snapshot with tabId parameter (specific tab extraction)-- β **S10** β Snapshot no tab error (bad tabId returns error)-- β **S11** β Large page snapshot (20K+ tokens, no timeout)-- β **S12** β Ref stability across actions (refs unchanged after click)--### Text Extraction-- β **T1** β Readability mode (`GET /text`)-- β **T2** β Raw mode (`GET /text?mode=raw`)-- β **T3** β Text with tabId parameter (specific tab extraction)-- β **T4** β Text no tab error (bad tabId returns error)-- β **T5** β Token efficiency (real-world content handling)--### Actions-- β **A1** β Click by ref-- β **A2** β Type by ref-- β **A3** β Fill by ref-- β **A4** β Press key-- β **A5** β Focus element-- β **A6** β Hover action-- β **A7** β Select option-- β **A8** β Scroll page-- β **A9** β Unknown kind returns 400-- β **A10** β Missing kind returns 400-- β **A11** β Ref not found error-- β **A12** β CSS selector click-- β **A13** β Action no tab error (bad tabId)-- β **A14** β Batch actions-- β **A15** β Batch empty returns 400--### Tabs-- β **TB1** β List tabs-- β **TB2** β New tab-- β **TB3** β Close tab-- β **TB4** β Close without tabId returns 400-- β **TB5** β Bad action returns 400-- β **TB6** β Max tabs limit behavior--### Screenshots-- β **SS1** β Basic screenshot (base64)-- β **SS2** β Raw screenshot (JPEG bytes) β skips gracefully on headless limitations--### JavaScript Evaluation-- β **E1** β Simple eval (1+1)-- β **E2** β DOM eval (document.title)-- β **E3** β Missing expression returns 400-- β **E4** β Bad JSON returns 400--### PDF Export-- β **PD1** β PDF base64 output-- β **PD2** β PDF raw bytes-- β **PD3** β PDF save to file-- β **PD5** β PDF landscape mode-- β **PD6** β PDF scale parameter--### File Upload-- β **UP1** β Upload single file with selector (skips if file:// not supported)-- β **UP4** β Upload multiple files (skips if file:// not supported)-- β **UP6** β Upload with default selector (skips if file:// not supported)-- β **UP7** β Upload invalid selector error (skips if file:// not supported)-- β **UP8** β Upload missing files error-- β **UP9** β Upload file not found error-- β **UP11** β Upload bad JSON error--### Cookies-- β **C1** β Get cookies-- β **C2** β Set cookies-- β **C3** β Get cookies no tab (error)-- β **C4** β Set cookies bad JSON (400)-- β **C5** β Set cookies empty (400)--### Stealth & Fingerprinting-- β **ST1** β navigator.webdriver undefined-- β **ST3** β navigator.plugins present-- β **ST4** β window.chrome.runtime present-- β **ST5** β Fingerprint rotation with OS specified-- β **ST6** β Fingerprint rotation random (no OS)-- β **ST8** β Stealth status endpoint--*Note: ST2 (canvas noise) skipped β unreliable in headless CI. ST7 replaced with specific tab rotation test.*--### Error Handling & Edge Cases-- β **ER3** β Binary page (PDF URL) graceful handling-- β **ER4** β Rapid navigate stress test (concurrent requests)-- β **ER5** β Unicode content (CJK/emoji/RTL) handling in snapshot & text-- β **ER6** β Empty page (about:blank) handling in snapshot & text--### Configuration-- β **CF1** β Config file preference (config.json loading)-- β **CF2** β Env overrides config (BRIDGE_PORT precedence)-- β **CF3** β CDP_URL external Chrome (remote CDP connection)-- β **CF4** β Custom profile directory (`BRIDGE_PROFILE` env var)-- β **CF5** β No restore flag (`BRIDGE_NO_RESTORE=true`)-- β **CF6** (variant) β Chrome version override via TEST_CHROME_VERSION-- β **CF7** β Chrome version default in UA-- β **CF8** β Chrome version persists after fingerprint rotate-------## Manual Test Coverage--The following scenarios require manual testing or deployment-specific setups:--### Manual Verification (Fix Verified in Code)-- β **CF3-Extended** β CDP_URL mode (fix verified, needs manual test to confirm: `manual/cf3-cdp-create-tab-repro.md`)--### Not Automating (Not Worth It)-- **ER1, ER2, ER7-ER8** β Chrome crash recovery, connection refused, port conflict (system-level, not practical)--### Manual Testing (Additional/Verification)-- π **UP1-UP11** (7 tests) β File upload also in CI but skips if `file://` fails. See `tests/manual/file-upload.md` for headed Chrome verification.-- π **SS2** (1 test) β Raw screenshot also in CI but skips on headless limitations. See `tests/manual/screenshot-raw.md` for headed Chrome verification.-- **A16-A17** β Human click/type (bezier movement, mouse trajectory)-- **SP1-SP3** β Session persistence (requires server restart sequencing)-- **HM1-HM3** β Headed mode (requires display server)-- **MA1-MA8** β Multi-agent scenarios (requires coordination)-- **Docker (D1-D7)** β Requires Docker, deployment testing-- **Dashboard (DA1-DA5)** β Requires manual profile management--See `manual/` directory for detailed test plans.-------## Performance Testing--Token usage, speed benchmarks, and Chrome startup metrics tracked separately in `performance/`.-------## Statistics--**Automated (in CI, may skip on headless limitations):** 84 scenarios-- Health: 1-- Navigation: 8 (N1-N8)-- Snapshot: 12 (S1-S12)-- Text: 5 (T1-T5)-- Actions: 15 (A1-A15)-- Tabs: 6 (TB1-TB6)-- Screenshots: 2 (SS1-SS2) β SS2 skips if headless-- Eval: 4 (E1-E4)-- PDF: 5 (PD1-PD3, PD5-PD6)-- File Upload: 7 (UP1, UP4, UP6-UP9, UP11) β skip if file:// not supported-- Cookies: 5 (C1-C5)-- Stealth: 6 (ST1, ST3-ST6, ST8)-- Error Handling: 4 (ER3-ER6)-- Configuration: 8 (CF1-CF8)--**Automated (always run):** ~76 tests (some UP/SS2 skip on headless)--**Manual Testing (Additional/Verification):** 16 scenarios-- π UP1-UP11 (7 tests) β Also in CI, verify with headed Chrome-- π SS2 (1 test) β Also in CI, verify with headed Chrome-- A16-A17, SP1-SP3, HM1-HM3, MA1-MA8, D1-D7, DA1-DA5 (8 tests)--**Not Automating:** 4 scenarios (ER1, ER2, ER7-ER8 β system-level)-**Total Coverage:** 98 test scenarios--**Coverage achieved: 86% automated (84 of 98 test scenarios, 76+ always run)**-------*Last updated: 2026-02-24 21:50 GMT β 84 automated (86%), 16 additional manual, 4 not doing*diff --git a/tests/integration/actions_test.go b/tests/integration/actions_test.goindex 194e9c42..af5a8c69 100644--- a/tests/integration/actions_test.go+++ b/tests/integration/actions_test.go@@ -8,12 +8,11 @@ import ("testing")-// A1: Click by ref β navigate to example.com, find the "More information..." link, click it+// A1: Click by ref β navigate to example page, find the "More information..." link, click itfunc TestAction_Click(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)- // Get snapshot to find a clickable ref_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)s := string(snapBody)@@ -36,7 +35,7 @@ func TestAction_Click(t *testing.T) {// A1b: Click actually triggers navigation (verifies fix for issue #80)// This test ensures clicks dispatch at the correct element position, not (0,0)func TestAction_Click_TriggersNavigation(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)t.Logf("current tab: %s", currentTabID)@@ -92,7 +91,7 @@ func TestAction_Click_TriggersNavigation(t *testing.T) {// A4: Press keyfunc TestAction_Press(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, _ := httpPost(t, "/action", map[string]any{@@ -123,7 +122,7 @@ func TestAction_MissingKind(t *testing.T) {// A11: Ref not foundfunc TestAction_RefNotFound(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, _ := httpPost(t, "/action", map[string]any{@@ -139,7 +138,7 @@ func TestAction_RefNotFound(t *testing.T) {// A12: CSS selector clickfunc TestAction_CSSSelector(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, _ := httpPost(t, "/action", map[string]any{@@ -181,7 +180,7 @@ func findRef(snapshot string, role string) string {// A2: Type by ref β need an input elementfunc TestAction_Type(t *testing.T) {// Navigate to httpbin form- navigate(t, "https://httpbin.org/forms/post")+ navigate(t, formsPageURL(t))defer closeCurrentTab(t)_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)@@ -206,7 +205,7 @@ func TestAction_Type(t *testing.T) {// A3: Fill by reffunc TestAction_Fill(t *testing.T) {- navigate(t, "https://httpbin.org/forms/post")+ navigate(t, formsPageURL(t))defer closeCurrentTab(t)_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)@@ -231,7 +230,7 @@ func TestAction_Fill(t *testing.T) {// A5: Focusfunc TestAction_Focus(t *testing.T) {- navigate(t, "https://httpbin.org/forms/post")+ navigate(t, formsPageURL(t))defer closeCurrentTab(t)_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)@@ -252,7 +251,7 @@ func TestAction_Focus(t *testing.T) {// A8: Scrollfunc TestAction_Scroll(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, _ := httpPost(t, "/action", map[string]any{@@ -267,7 +266,7 @@ func TestAction_Scroll(t *testing.T) {// Batch actions (A14)func TestAction_Batch(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))payload := map[string]any{"tabId": currentTabID,"actions": []map[string]any{@@ -293,7 +292,7 @@ func TestAction_BatchEmpty(t *testing.T) {// A6: Hoverfunc TestAction_Hover(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Get snapshot to find a link ref_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)@@ -319,7 +318,7 @@ func TestAction_Hover(t *testing.T) {// A7: Selectfunc TestAction_Select(t *testing.T) {- navigate(t, "https://httpbin.org/forms/post")+ navigate(t, formsPageURL(t))defer closeCurrentTab(t)// Get snapshot to find a select element@@ -345,7 +344,7 @@ func TestAction_Select(t *testing.T) {// A13: No tabfunc TestAction_NoTab(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, _ := httpPost(t, "/action", map[string]string{"kind": "click",@@ -359,7 +358,7 @@ func TestAction_NoTab(t *testing.T) {}func TestAction_Fill_ActuallySetsValue(t *testing.T) {- navigate(t, "https://httpbin.org/forms/post")+ navigate(t, formsPageURL(t))defer closeCurrentTab(t)_, snapBody := httpGet(t, "/snapshot?filter=interactive&format=text&tabId="+currentTabID)diff --git a/tests/integration/config_test.go b/tests/integration/config_test.goindex 2b337217..78c5653e 100644--- a/tests/integration/config_test.go+++ b/tests/integration/config_test.go@@ -23,7 +23,7 @@ func extractChromeVersion(ua string) string {// CF7: Chrome version default// Navigate, eval navigator.userAgent, verify it contains a valid Chrome version.func TestConfig_ChromeVersionDefault(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPost(t, "/evaluate", map[string]string{"tabId": currentTabID,@@ -54,7 +54,7 @@ func TestConfig_ChromeVersionDefault(t *testing.T) {// CF8: Chrome version in fingerprint// Navigate, POST /fingerprint/rotate, verify UA still contains the same Chrome version.func TestConfig_ChromeVersionInFingerprint(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Get initial user agentcode1, body1 := httpPost(t, "/evaluate", map[string]string{@@ -115,7 +115,7 @@ func TestConfig_ChromeVersionInFingerprint(t *testing.T) {func TestConfig_ConfigFilePreference(t *testing.T) {// If we reach here, the server has already started successfully.// This test verifies that config file loading works by attempting basic operations.- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPost(t, "/evaluate", map[string]string{"tabId": currentTabID,@@ -139,7 +139,7 @@ func TestConfig_ConfigFilePreference(t *testing.T) {func TestConfig_EnvOverridesConfig(t *testing.T) {// The test harness already starts the server with BRIDGE_PORT set via env var.// If we can connect to the server and it responds, this proves env vars work.- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPost(t, "/evaluate", map[string]string{"tabId": currentTabID,diff --git a/tests/integration/cookies_test.go b/tests/integration/cookies_test.goindex 84fdd5f3..5a75ec17 100644--- a/tests/integration/cookies_test.go+++ b/tests/integration/cookies_test.go@@ -9,7 +9,7 @@ import (// C1: Get cookiesfunc TestCookies_Get(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, "/cookies?tabId="+currentTabID)if code != 200 {t.Fatalf("expected 200, got %d (body: %s)", code, body)@@ -53,12 +53,12 @@ func TestCookies_Get(t *testing.T) {// C2: Set cookiesfunc TestCookies_Set(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Set a cookiecode, body := httpPost(t, "/cookies", map[string]any{"tabId": currentTabID,- "url": "https://example.com",+ "url": examplePageURL(t),"cookies": []map[string]any{{"name": "test_cookie",@@ -84,7 +84,7 @@ func TestCookies_Set(t *testing.T) {}// Verify the cookie was set by getting cookies again- code2, body2 := httpGet(t, "/cookies?url=https://example.com&tabId="+currentTabID)+ code2, body2 := httpGet(t, "/cookies?url="+examplePageURL(t)+"&tabId="+currentTabID)if code2 != 200 {t.Fatalf("GET /cookies failed: %d", code2)}@@ -129,7 +129,7 @@ func TestCookies_GetNoTab(t *testing.T) {// C4: Set cookies bad JSONfunc TestCookies_SetBadJSON(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPostRaw(t, "/cookies", "{broken")if code != 400 {@@ -139,12 +139,12 @@ func TestCookies_SetBadJSON(t *testing.T) {// C5: Set cookies emptyfunc TestCookies_SetEmpty(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Post with empty cookies arraycode, body := httpPost(t, "/cookies", map[string]any{"tabId": currentTabID,- "url": "https://example.com",+ "url": examplePageURL(t),"cookies": []map[string]any{},})diff --git a/tests/integration/error_handling_test.go b/tests/integration/error_handling_test.goindex d204b423..dec01ad9 100644--- a/tests/integration/error_handling_test.go+++ b/tests/integration/error_handling_test.go@@ -12,8 +12,8 @@ import (// ER5: Unicode content handlingfunc TestError_UnicodeContent(t *testing.T) {- // Navigate to a page with Unicode (CJK/emoji/RTL)- navigate(t, "https://www.wikipedia.org")+ // Navigate to a local page with Unicode+ navigate(t, fixtureURL(t, "/unicode"))// Test snapshotcode, snapBody := httpGet(t, "/snapshot?tabId="+currentTabID)@@ -72,25 +72,20 @@ func TestError_EmptyPage(t *testing.T) {// ER3: Binary page (PDF) handlingfunc TestError_BinaryPage(t *testing.T) {- // Navigate to a PDF- navigate(t, "https://www.w3.org/WAI/WCAG21/Techniques/pdf/pdf_files/techniques.pdf")+ // Navigate to a local PDF+ navigate(t, fixtureURL(t, "/binary.pdf"))- // Verify navigation completes (any status code, not a hang)- // The navigate() helper will fail if the request hangs+ // Verify navigation completest.Logf("navigation to PDF completed successfully")// Test snapshot on PDF content- // PDF may not render as a traditional page, so snapshot might fail or return empty- // We just verify it doesn't crash and returns gracefullycode, snapBody := httpGet(t, "/snapshot?tabId="+currentTabID)if code == 200 {- // Verify response is valid JSON (even if empty/error)var snapData map[string]anyif err := json.Unmarshal(snapBody, &snapData); err != nil {t.Errorf("snapshot response is not valid JSON: %v", err)}} else if code >= 400 && code < 500 {- // Client error is acceptable for binary contentt.Logf("snapshot returned %d (acceptable for PDF)", code)} else {t.Errorf("snapshot failed with unexpected code %d", code)@@ -104,7 +99,6 @@ func TestError_BinaryPage(t *testing.T) {t.Errorf("text response is not valid JSON: %v", err)}} else if code >= 400 && code < 500 {- // Client error is acceptable for binary contentt.Logf("text returned %d (acceptable for PDF)", code)} else {t.Errorf("text failed with unexpected code %d", code)@@ -114,11 +108,11 @@ func TestError_BinaryPage(t *testing.T) {// ER4: Rapid navigation stress testfunc TestError_RapidNavigate(t *testing.T) {urls := []string{- "https://example.com",- "https://httpbin.org",- "https://example.com",- "https://httpbin.org",- "https://example.com",+ fixtureURL(t, "/page1"),+ fixtureURL(t, "/page2"),+ fixtureURL(t, "/slow"),+ fixtureURL(t, "/page1"),+ fixtureURL(t, "/page2"),}// Use a WaitGroup to ensure all navigations complete@@ -133,6 +127,7 @@ func TestError_RapidNavigate(t *testing.T) {wg.Add(1)go func(idx int, u string) {defer wg.Done()+ // Use local navigate logic to avoid tabId closure in loopcode, _ := httpPost(t, "/navigate", map[string]string{"url": u})if code != 200 {mu.Lock()@@ -146,9 +141,9 @@ func TestError_RapidNavigate(t *testing.T) {wg.Wait()elapsed := time.Since(startTime)- // Check that navigations completed quickly (within 5 seconds for rapid test)+ // Check that navigations completed quicklyif elapsed > 5*time.Second {- t.Logf("rapid navigation took %v (slower than expected but acceptable)", elapsed)+ t.Logf("rapid navigation took %v", elapsed)}// Verify no critical errors occurred@@ -158,8 +153,7 @@ func TestError_RapidNavigate(t *testing.T) {}}- // Verify final page is example.com (last navigate wins)- // Wait a bit for the last navigation to settle+ // Verify server didn't crashtime.Sleep(500 * time.Millisecond)code, snapBody := httpGet(t, "/snapshot")@@ -168,8 +162,6 @@ func TestError_RapidNavigate(t *testing.T) {if err := json.Unmarshal(snapBody, &snapData); err != nil {t.Errorf("snapshot response is not valid JSON: %v", err)}- // Note: We can't easily verify the exact URL without accessing browser state,- // but the important check is that we get a valid response (server didn't crash)} else {t.Errorf("snapshot failed with code %d", code)}diff --git a/tests/integration/eval_test.go b/tests/integration/eval_test.goindex 711fb925..0312d54a 100644--- a/tests/integration/eval_test.go+++ b/tests/integration/eval_test.go@@ -8,7 +8,7 @@ import (// E1: Simple evalfunc TestEval_Simple(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPost(t, "/evaluate", map[string]string{"tabId": currentTabID,"expression": "1+1",@@ -24,7 +24,7 @@ func TestEval_Simple(t *testing.T) {// E2: DOM evalfunc TestEval_DOM(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpPost(t, "/evaluate", map[string]string{"tabId": currentTabID,"expression": "document.title",diff --git a/tests/integration/fixture_site_test.go b/tests/integration/fixture_site_test.gonew file mode 100644index 00000000..4d0f3769--- /dev/null+++ b/tests/integration/fixture_site_test.go@@ -0,0 +1,127 @@+//go:build integration++package integration++import (+ "fmt"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "time"+)++var fixtureSite *httptest.Server++func startFixtureSite() {+ if fixtureSite != nil {+ return+ }++ mux := http.NewServeMux()++ mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {+ switch r.URL.Path {+ case "/":+ writeHTML(w, "Example Domain", `+ <h1>Example Domain</h1>+ <p>This domain is for use in illustrative examples.</p>+ <a id="more-info" href="/more">More information...</a>+ <div style="height:1200px"></div>+ `)+ case "/more":+ writeHTML(w, "IANA Reserved Domains", `+ <h1>IANA Reserved Domains</h1>+ <p>IANA-managed reserved domains documentation.</p>+ <p>This page intentionally differs from Example Domain.</p>+ `)+ case "/forms/post":+ writeHTML(w, "httpbin Form Post", `+ <h1>httpbin Form Post</h1>+ <form action="/forms/post" method="post">+ <label for="custname">Customer name</label>+ <input id="custname" name="custname" type="text" />+ <label for="comments">Comments</label>+ <textarea id="comments" name="comments"></textarea>+ <label for="size">Size</label>+ <select id="size" name="size">+ <option value="">--</option>+ <option value="opt1">opt1</option>+ <option value="opt2">opt2</option>+ </select>+ <button type="submit">Submit</button>+ </form>+ `)+ case "/unicode":+ writeHTML(w, "Unicode Test", `<p>CJK: γγγ«γ‘γ―, Emoji: π, RTL: Ω Ψ±ΨΨ¨Ψ§ Ψ¨Ω</p>`)+ case "/binary.pdf":+ w.Header().Set("Content-Type", "application/pdf")+ _, _ = w.Write([]byte("%PDF-1.4\n1 0 obj\n<< /Title (Test) >>\nendobj\ntrailer\n<< /Root 1 0 R >>\n%%EOF"))+ case "/page1":+ writeHTML(w, "Page 1", "<h1>Page 1</h1>")+ case "/page2":+ writeHTML(w, "Page 2", "<h1>Page 2</h1>")+ case "/slow":+ time.Sleep(100 * time.Millisecond)+ writeHTML(w, "Slow Page", "<h1>Slow Page</h1>")+ case "/large":+ var b strings.Builder+ b.WriteString("<h1>Large Fixture Page</h1>")+ for i := 0; i < 400; i++ {+ b.WriteString(fmt.Sprintf("<p>Section %d: Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>", i))+ }+ writeHTML(w, "Large Page", b.String())+ case "/assets/upload-test.html":+ http.ServeFile(w, r, filepath.Join(findRepoRoot(), "tests/assets/upload-test.html"))+ default:+ writeHTML(w, "Fixture Page", fmt.Sprintf("<h1>Fixture Page</h1><p>Path: %s</p>", r.URL.Path))+ }+ })++ fixtureSite = httptest.NewServer(mux)++ // Fail fast if the shared upload fixture disappeared.+ if _, err := os.Stat(filepath.Join(findRepoRoot(), "tests/assets/upload-test.html")); err != nil {+ panic(fmt.Sprintf("missing upload fixture: %v", err))+ }+}++func stopFixtureSite() {+ if fixtureSite == nil {+ return+ }+ fixtureSite.Close()+ fixtureSite = nil+}++func fixtureURL(t *testing.T, path string) string {+ t.Helper()+ if fixtureSite == nil {+ t.Fatal("fixture site is not started")+ }+ if path == "" || path == "/" {+ return fixtureSite.URL + "/"+ }+ if strings.HasPrefix(path, "/") {+ return fixtureSite.URL + path+ }+ return fixtureSite.URL + "/" + path+}++func examplePageURL(t *testing.T) string { return fixtureURL(t, "/") }+func moreInfoPageURL(t *testing.T) string { return fixtureURL(t, "/more") }+func formsPageURL(t *testing.T) string { return fixtureURL(t, "/forms/post") }+func largePageURL(t *testing.T) string { return fixtureURL(t, "/large") }+func uploadPageURL(t *testing.T) string { return fixtureURL(t, "/assets/upload-test.html") }++func writeHTML(w http.ResponseWriter, title string, body string) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = fmt.Fprintf(+ w,+ "<!doctype html><html><head><meta charset=\"utf-8\"><title>%s</title></head><body>%s</body></html>",+ title,+ body,+ )+}diff --git a/tests/integration/main_test.go b/tests/integration/main_test.goindex 1ef1f4bd..6e2a2c5d 100644--- a/tests/integration/main_test.go+++ b/tests/integration/main_test.go@@ -17,12 +17,15 @@ var ()func TestMain(m *testing.M) {+ startFixtureSite()+cfg := testutil.DefaultConfig()var err errorserver, err = testutil.StartServer(cfg)if err != nil {fmt.Fprintf(os.Stderr, "failed to start server: %v\n", err)+ stopFixtureSite()os.Exit(1)}@@ -32,11 +35,13 @@ func TestMain(m *testing.M) {if _, err := testutil.LaunchInstance(server.URL); err != nil {fmt.Fprintf(os.Stderr, "failed to launch test instance: %v\n", err)server.Stop()+ stopFixtureSite()os.Exit(1)}code := m.Run()server.Stop()+ stopFixtureSite()os.Exit(code)}diff --git a/tests/integration/metrics_test.go b/tests/integration/metrics_test.goindex 15a77fb6..be52c141 100644--- a/tests/integration/metrics_test.go+++ b/tests/integration/metrics_test.go@@ -10,7 +10,7 @@ import (// M1: Get metrics endpoint returns aggregated memory across instancesfunc TestMetrics_Basic(t *testing.T) {// Navigate to a page first to ensure we have a tab with content- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, body := httpGet(t, "/instances/metrics")@@ -40,7 +40,7 @@ func TestMetrics_Basic(t *testing.T) {// M2: Per-tab metrics (proxied through orchestrator)func TestMetrics_PerTab(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, body := httpGet(t, "/tabs/"+currentTabID+"/metrics")@@ -71,7 +71,7 @@ func TestMetrics_InvalidTab(t *testing.T) {// M4: Metrics endpoint returns valid datafunc TestMetrics_ValidResponse(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))defer closeCurrentTab(t)code, body := httpGet(t, "/tabs/"+currentTabID+"/metrics")diff --git a/tests/integration/navigate_test.go b/tests/integration/navigate_test.goindex 0f45ff17..2c2c3018 100644--- a/tests/integration/navigate_test.go+++ b/tests/integration/navigate_test.go@@ -9,7 +9,7 @@ import (// N1: Basic navigatefunc TestNavigate_Basic(t *testing.T) {- code, body := httpPost(t, "/navigate", map[string]string{"url": "https://example.com"})+ code, body := httpPost(t, "/navigate", map[string]string{"url": examplePageURL(t)})if code != 200 {t.Fatalf("expected 200, got %d (body: %s)", code, body)}@@ -45,7 +45,7 @@ func TestNavigate_BadJSON(t *testing.T) {// N2: Navigate returns titlefunc TestNavigate_ReturnsTitle(t *testing.T) {- code, body := httpPost(t, "/navigate", map[string]string{"url": "https://example.com"})+ code, body := httpPost(t, "/navigate", map[string]string{"url": examplePageURL(t)})if code != 200 {t.Fatalf("expected 200, got %d", code)}@@ -58,7 +58,7 @@ func TestNavigate_ReturnsTitle(t *testing.T) {// N4: Navigate with newTabfunc TestNavigate_NewTab(t *testing.T) {code, body := httpPost(t, "/navigate", map[string]any{- "url": "https://example.com",+ "url": examplePageURL(t),"newTab": true,})if code != 200 {@@ -88,7 +88,7 @@ func TestNavigate_Timeout(t *testing.T) {func TestNavigate_SPATitle(t *testing.T) {// Use a page that definitely has a title - example.com has "Example Domain" as title// Use retry logic for stability in CI/slow environments- code, body := httpPostWithRetry(t, "/navigate", map[string]any{"url": "https://example.com"}, 2)+ code, body := httpPostWithRetry(t, "/navigate", map[string]any{"url": examplePageURL(t)}, 2)if code != 200 {t.Fatalf("expected 200, got %d", code)}diff --git a/tests/integration/orchestrator_test.go b/tests/integration/orchestrator_test.goindex 1d1755f7..ce815595 100644--- a/tests/integration/orchestrator_test.go+++ b/tests/integration/orchestrator_test.go@@ -109,7 +109,7 @@ func TestOrchestrator_HashBasedIDs(t *testing.T) {time.Sleep(2 * time.Second)// Navigate to create tab- navStatus, navBody, tabID := navigateInstance(t, instID, "https://example.com")+ navStatus, navBody, tabID := navigateInstance(t, instID, examplePageURL(t))if navStatus != 200 {t.Fatalf("navigate failed: %d: %s", navStatus, string(navBody))}@@ -239,13 +239,13 @@ func TestOrchestrator_InstanceIsolation(t *testing.T) {time.Sleep(2 * time.Second)// Navigate on instance 1- status, navBody, tabID1 := navigateInstance(t, instIDs[0], "https://example.com")+ status, navBody, tabID1 := navigateInstance(t, instIDs[0], examplePageURL(t))if status != 200 {t.Fatalf("navigate instance 1 failed: %d: %s", status, string(navBody))}// Navigate on instance 2- status, navBody, tabID2 := navigateInstance(t, instIDs[1], "https://github.com")+ status, navBody, tabID2 := navigateInstance(t, instIDs[1], moreInfoPageURL(t))if status != 200 {t.Fatalf("navigate instance 2 failed: %d: %s", status, string(navBody))}@@ -325,7 +325,7 @@ func TestOrchestrator_ProxyRouting(t *testing.T) {time.Sleep(2 * time.Second)// Test navigation via orchestrator proxy- status, body, tabID := navigateInstance(t, instID, "https://example.com")+ status, body, tabID := navigateInstance(t, instID, examplePageURL(t))if status != 200 {t.Fatalf("proxy navigate failed: %d: %s", status, string(body))}@@ -398,12 +398,12 @@ func TestOrchestrator_ProxyRouting(t *testing.T) {}// Test cookies via orchestrator tab route- status, body = httpGet(t, fmt.Sprintf("/tabs/%s/cookies?url=https://example.com", tabID))+ status, body = httpGet(t, fmt.Sprintf("/tabs/%s/cookies?url=%s", tabID, examplePageURL(t)))if status != 200 {t.Fatalf("proxy get cookies failed: %d: %s", status, string(body))}status, body = httpPost(t, fmt.Sprintf("/tabs/%s/cookies", tabID), map[string]any{- "url": "https://example.com",+ "url": examplePageURL(t),"cookies": []map[string]any{{"name": "orch_test_cookie", "value": "1"},},@@ -499,7 +499,7 @@ func TestOrchestrator_FirstRequestLazyChrome(t *testing.T) {}// Now make the actual proxy request - Chrome is already initialized- status, body, tabID := navigateInstance(t, instID, "https://example.com")+ status, body, tabID := navigateInstance(t, instID, examplePageURL(t))if status != 200 {t.Fatalf("navigate failed: %d: %s", status, string(body))}@@ -542,7 +542,7 @@ func TestOrchestrator_AggregateTabsEndpoint(t *testing.T) {// Navigate on each instancefor _, instID := range instIDs {- httpStatus, navBody, _ := navigateInstance(t, instID, "https://example.com")+ httpStatus, navBody, _ := navigateInstance(t, instID, examplePageURL(t))if httpStatus != 200 {t.Fatalf("navigate failed for %s: %d: %s", instID, httpStatus, string(navBody))}diff --git a/tests/integration/pdf_test.go b/tests/integration/pdf_test.goindex c7e4f421..2aea5d7b 100644--- a/tests/integration/pdf_test.go+++ b/tests/integration/pdf_test.go@@ -23,7 +23,7 @@ func tabPDFPath(t *testing.T, query string) string {// PD1: PDF base64func TestPDF_Base64(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, ""))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -44,7 +44,7 @@ func TestPDF_Base64(t *testing.T) {// PD2: PDF raw bytesfunc TestPDF_Raw(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -56,7 +56,7 @@ func TestPDF_Raw(t *testing.T) {// PD3: PDF save to file (uses default state dir)func TestPDF_SaveFile(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "output=file"))if code != 200 {t.Fatalf("expected 200, got %d (body: %s)", code, body)@@ -79,7 +79,7 @@ func TestPDF_SaveFile(t *testing.T) {// PD5: PDF landscapefunc TestPDF_Landscape(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "landscape=true&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -91,7 +91,7 @@ func TestPDF_Landscape(t *testing.T) {// PD6: PDF scalefunc TestPDF_Scale(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "scale=0.5&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -103,7 +103,7 @@ func TestPDF_Scale(t *testing.T) {// PD7: PDF with custom paper sizefunc TestPDF_CustomPaperSize(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "paperWidth=7&paperHeight=9&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -115,7 +115,7 @@ func TestPDF_CustomPaperSize(t *testing.T) {// PD8: PDF with custom marginsfunc TestPDF_CustomMargins(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "marginTop=0.75&marginLeft=0.75&marginRight=0.75&marginBottom=0.75&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -127,7 +127,7 @@ func TestPDF_CustomMargins(t *testing.T) {// PD9: PDF with page rangesfunc TestPDF_PageRanges(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "pageRanges=1&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -139,7 +139,7 @@ func TestPDF_PageRanges(t *testing.T) {// PD10: PDF with header/footerfunc TestPDF_HeaderFooter(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "displayHeaderFooter=true&headerTemplate=%3Cspan%20class=url%3E%3C/span%3E&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -151,7 +151,7 @@ func TestPDF_HeaderFooter(t *testing.T) {// PD11: PDF with accessibility and outlinefunc TestPDF_AccessiblePDF(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "generateTaggedPDF=true&generateDocumentOutline=true&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -163,7 +163,7 @@ func TestPDF_AccessiblePDF(t *testing.T) {// PD12: PDF with preferCSSPageSizefunc TestPDF_PreferCSSPageSize(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, tabPDFPath(t, "preferCSSPageSize=true&raw=true"))if code != 200 {t.Fatalf("expected 200, got %d", code)diff --git a/tests/integration/screenshot_test.go b/tests/integration/screenshot_test.goindex 8c2b31d3..9b8f229d 100644--- a/tests/integration/screenshot_test.go+++ b/tests/integration/screenshot_test.go@@ -10,7 +10,7 @@ import (// Note: May timeout in CI if headless Chrome has display limitations.// See tests/manual/screenshot-basic.md for headed Chrome testing.func TestScreenshot_Basic(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, "/screenshot")if code != 200 {t.Skipf("screenshot returned %d (headless display limitation), skipping", code)@@ -25,7 +25,7 @@ func TestScreenshot_Basic(t *testing.T) {// Note: May skip in CI if headless Chrome has display limitations.// See tests/manual/screenshot-raw.md for headed Chrome testing.func TestScreenshot_Raw(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, "/screenshot?raw=true")if code != 200 {t.Skipf("screenshot raw returned %d (headless display limitation), skipping", code)diff --git a/tests/integration/security_proxy_test.go b/tests/integration/security_proxy_test.goindex e99650a7..7375f3d2 100644--- a/tests/integration/security_proxy_test.go+++ b/tests/integration/security_proxy_test.go@@ -39,7 +39,7 @@ func TestProxy(t *testing.T) {t.Run("LocalhostOnly", func(t *testing.T) {// Verify instance can be accessed via proxy (SSRF prevention)- code, _, _ := navigateInstance(t, instID, "https://example.com")+ code, _, _ := navigateInstance(t, instID, examplePageURL(t))if code != 200 {t.Errorf("expected 200 for valid localhost proxy, got %d", code)}@@ -47,7 +47,7 @@ func TestProxy(t *testing.T) {t.Run("URLValidation", func(t *testing.T) {// Verify URL construction is safe with query params- code, respBody, _ := navigateInstance(t, instID, "https://example.com/path?query=value")+ code, respBody, _ := navigateInstance(t, instID, fixtureURL(t, "/path?query=value"))if code != 200 {t.Logf("navigate with query params got %d: %s", code, string(respBody))}@@ -55,7 +55,7 @@ func TestProxy(t *testing.T) {t.Run("SchemeValidation", func(t *testing.T) {// Verify proxy uses http scheme for localhost- code, respBody, _ := navigateInstance(t, instID, "https://example.com")+ code, respBody, _ := navigateInstance(t, instID, examplePageURL(t))if code != 200 {t.Errorf("navigate failed (scheme validation): %d: %s", code, string(respBody))}@@ -98,12 +98,12 @@ func TestProxy_InstanceIsolation(t *testing.T) {waitForInstanceReady(t, instIDs[0])waitForInstanceReady(t, instIDs[1])- code1, body1, _ := navigateInstance(t, instIDs[0], "https://example.com/page1")+ code1, body1, _ := navigateInstance(t, instIDs[0], fixtureURL(t, "/page1"))if code1 != 200 {t.Errorf("navigate in inst1 failed: %d: %s", code1, string(body1))}- code2, body2, _ := navigateInstance(t, instIDs[1], "https://example.com/page2")+ code2, body2, _ := navigateInstance(t, instIDs[1], fixtureURL(t, "/page2"))if code2 != 200 {t.Errorf("navigate in inst2 failed: %d: %s", code2, string(body2))}diff --git a/tests/integration/snapshot_test.go b/tests/integration/snapshot_test.goindex 071103e4..f888f50e 100644--- a/tests/integration/snapshot_test.go+++ b/tests/integration/snapshot_test.go@@ -23,7 +23,7 @@ func snapshotPath(path string) string {// S1: Basic snapshotfunc TestSnapshot_Basic(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, snapshotPath("/snapshot"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -40,7 +40,7 @@ func TestSnapshot_Basic(t *testing.T) {// S2: Interactive filterfunc TestSnapshot_Interactive(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, snapshotPath("/snapshot?filter=interactive"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -54,7 +54,7 @@ func TestSnapshot_Interactive(t *testing.T) {// S4: Text formatfunc TestSnapshot_TextFormat(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, snapshotPath("/snapshot?format=text"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -71,7 +71,7 @@ func TestSnapshot_TextFormat(t *testing.T) {// S5: YAML formatfunc TestSnapshot_YAMLFormat(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, snapshotPath("/snapshot?format=yaml"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -84,7 +84,7 @@ func TestSnapshot_YAMLFormat(t *testing.T) {// S3: Depth filterfunc TestSnapshot_Depth(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, _ := httpGet(t, snapshotPath("/snapshot?depth=2"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -93,7 +93,7 @@ func TestSnapshot_Depth(t *testing.T) {// S5 (compact): maxTokensfunc TestSnapshot_MaxTokens(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, _ := httpGet(t, snapshotPath("/snapshot?maxTokens=500"))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -105,7 +105,7 @@ func TestSnapshot_WithTabId(t *testing.T) {// Create first tab and navigate to example.comcode, body := httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://example.com",+ "url": examplePageURL(t),})if code != 200 {t.Skip("could not create first tab")@@ -120,7 +120,7 @@ func TestSnapshot_WithTabId(t *testing.T) {// Create second tab and navigate to httpbin.orgcode, body = httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://httpbin.org",+ "url": formsPageURL(t),})if code != 200 {t.Skip("could not create second tab")@@ -159,7 +159,7 @@ func TestSnapshot_NoTab(t *testing.T) {// S8: Snapshot file outputfunc TestSnapshot_FileOutput(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, snapshotPath("/snapshot?output=file"))if code != 200 {t.Fatalf("expected 200, got %d (body: %s)", code, body)@@ -182,7 +182,7 @@ func TestSnapshot_FileOutput(t *testing.T) {// S12: Snapshot ref stability across interactionsfunc TestSnapshot_RefStability(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Get initial snapshot with interactive filtercode, body := httpGet(t, snapshotPath("/snapshot?filter=interactive"))@@ -221,7 +221,7 @@ func TestSnapshot_RefStability(t *testing.T) {// S6: Snapshot diff modefunc TestSnapshot_DiffMode(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// First snapshot call - stores statecode, body1 := httpGet(t, snapshotPath("/snapshot"))@@ -261,7 +261,7 @@ func TestSnapshot_DiffMode(t *testing.T) {// S7: Snapshot diff on first call (no prior state)func TestSnapshot_DiffFirstCall(t *testing.T) {// Fresh navigate - no prior snapshot stored- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Call /snapshot?diff=true immediately (first call with diff=true)code, body := httpGet(t, snapshotPath("/snapshot?diff=true"))@@ -285,7 +285,7 @@ func TestSnapshot_DiffFirstCall(t *testing.T) {// S11: Snapshot on large pagefunc TestSnapshot_LargePage(t *testing.T) {// Navigate to a large Wikipedia article- url := "https://en.wikipedia.org/wiki/List_of_countries_and_territories_by_total_area"+ url := largePageURL(t)navigate(t, url)// Call /snapshot on the large pagediff --git a/tests/integration/stealth_test.go b/tests/integration/stealth_test.goindex bc2602aa..9c6c57bb 100644--- a/tests/integration/stealth_test.go+++ b/tests/integration/stealth_test.go@@ -10,7 +10,7 @@ import (// ST1: Webdriver is hidden (undefined)func TestStealth_WebdriverUndefined(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Poll for stealth injection to complete instead of fixed sleep// This is more reliable than a fixed wait across different CI runnersfor retry := 0; retry < 10; retry++ {@@ -40,7 +40,7 @@ func TestStealth_WebdriverUndefined(t *testing.T) {// ST3: Plugins are presentfunc TestStealth_PluginsPresent(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Poll for stealth injection instead of fixed sleepfor retry := 0; retry < 10; retry++ {code, body := httpPost(t, "/evaluate", map[string]string{@@ -64,7 +64,7 @@ func TestStealth_PluginsPresent(t *testing.T) {// ST4: Chrome runtime is presentfunc TestStealth_ChromeRuntimePresent(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Poll for stealth injection instead of fixed sleepfor retry := 0; retry < 10; retry++ {code, body := httpPost(t, "/evaluate", map[string]string{@@ -88,7 +88,7 @@ func TestStealth_ChromeRuntimePresent(t *testing.T) {// ST5: Fingerprint rotation with specific OSfunc TestStealth_FingerprintRotate(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Get initial user agentcode1, body1 := httpPost(t, "/evaluate", map[string]string{@@ -134,7 +134,7 @@ func TestStealth_FingerprintRotate(t *testing.T) {// ST6: Fingerprint rotation without OS specified (random)func TestStealth_FingerprintRotateRandom(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Rotate fingerprint with empty body (random OS)code, body := httpPost(t, "/fingerprint/rotate", map[string]string{"tabId": currentTabID})@@ -151,7 +151,7 @@ func TestStealth_FingerprintRotateRandom(t *testing.T) {// ST7: Fingerprint rotation on specific tabfunc TestStealth_FingerprintRotateSpecificTab(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))// Get tab ID from tabs listcode1, tabsBody := httpGet(t, "/tabs")diff --git a/tests/integration/tabs_test.go b/tests/integration/tabs_test.goindex e7fbd6ed..f4806bea 100644--- a/tests/integration/tabs_test.go+++ b/tests/integration/tabs_test.go@@ -31,7 +31,7 @@ func TestTabs_List(t *testing.T) {func TestTabs_New(t *testing.T) {code, body := httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://example.com",+ "url": examplePageURL(t),})if code != 200 {t.Fatalf("expected 200, got %d (body: %s)", code, body)@@ -53,7 +53,7 @@ func TestTabs_Close(t *testing.T) {// Create a tab to close_, newBody := httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://example.com",+ "url": examplePageURL(t),})var newTab map[string]any_ = json.Unmarshal(newBody, &newTab)@@ -107,7 +107,7 @@ func TestTabs_MaxTabs(t *testing.T) {for i := 0; i < 20; i++ {code, body := httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://example.com",+ "url": examplePageURL(t),})if code == 200 {var newTab map[string]any@@ -181,7 +181,7 @@ func TestTabs_RejectsNonexistentID(t *testing.T) {// Try to navigate using nonexistent tab ID - should fail with 404code, _ := httpPost(t, "/tabs/"+rawCDPID+"/navigate", map[string]string{- "url": "https://example.com",+ "url": examplePageURL(t),})if code != 404 {t.Errorf("expected 404 for raw CDP ID, got %d", code)diff --git a/tests/integration/text_test.go b/tests/integration/text_test.goindex ac9ea8e2..7d40ad27 100644--- a/tests/integration/text_test.go+++ b/tests/integration/text_test.go@@ -11,7 +11,7 @@ import (// T1: Readability modefunc TestText_Readability(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, "/text?tabId="+url.QueryEscape(currentTabID))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -24,7 +24,7 @@ func TestText_Readability(t *testing.T) {// T2: Raw modefunc TestText_Raw(t *testing.T) {- navigate(t, "https://example.com")+ navigate(t, examplePageURL(t))code, body := httpGet(t, "/text?mode=raw&tabId="+url.QueryEscape(currentTabID))if code != 200 {t.Fatalf("expected 200, got %d", code)@@ -40,7 +40,7 @@ func TestText_WithTabId(t *testing.T) {// Create first tab and navigate to example.comcode, body := httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://example.com",+ "url": examplePageURL(t),})if code != 200 {t.Skip("could not create first tab")@@ -55,7 +55,7 @@ func TestText_WithTabId(t *testing.T) {// Create second tab and navigate to httpbin.orgcode, body = httpPost(t, "/tab", map[string]string{"action": "new",- "url": "https://httpbin.org",+ "url": formsPageURL(t),})if code != 200 {t.Skip("could not create second tab")@@ -103,7 +103,7 @@ func TestText_NoTab(t *testing.T) {// T5: Token efficiency (real-world content)func TestText_TokenEfficiency(t *testing.T) {- navigate(t, "https://google.com")+ navigate(t, largePageURL(t))code, body := httpGet(t, "/text?tabId="+url.QueryEscape(currentTabID))if code != 200 {t.Fatalf("expected 200, got %d", code)diff --git a/tests/integration/upload_test.go b/tests/integration/upload_test.goindex 42560979..36e2f604 100644--- a/tests/integration/upload_test.go+++ b/tests/integration/upload_test.go@@ -3,31 +3,41 @@package integrationimport (+ "encoding/base64""encoding/json"- "fmt"+ "os""path/filepath""testing")+func uploadFixtureFile(t *testing.T) string {+ t.Helper()+ return filepath.Join(findRepoRoot(), "tests/assets/test-upload.png")+}++func uploadFixtureBase64(t *testing.T) string {+ t.Helper()+ data, err := os.ReadFile(uploadFixtureFile(t))+ if err != nil {+ t.Fatalf("read upload fixture: %v", err)+ }+ return base64.StdEncoding.EncodeToString(data)+}+// UP1: Single file upload with explicit selectorfunc TestUpload_SingleFile(t *testing.T) {- repoRoot := findRepoRoot()- testHtmlPath := filepath.Join(repoRoot, "tests/assets/upload-test.html")- testFileURL := fmt.Sprintf("file://%s", testHtmlPath)-- navCode, _ := httpPost(t, "/navigate", map[string]string{"url": testFileURL})+ navCode, _ := httpPost(t, "/navigate", map[string]string{"url": uploadPageURL(t)})if navCode != 200 {- t.Skipf("navigation to file:// URL not supported (code %d), skipping upload test", navCode)+ t.Fatalf("navigation to upload fixture failed with %d", navCode)}- testFilePath := filepath.Join(repoRoot, "tests/assets/test-upload.png")code, body := httpPost(t, "/upload", map[string]any{"selector": "#single",- "paths": []string{testFilePath},+ "files": []string{uploadFixtureBase64(t)},})if code != 200 {- t.Skipf("upload returned %d (file:// URLs have limitations in headless Chrome)", code)+ t.Fatalf("upload returned %d: %s", code, body)}var resp map[string]any@@ -48,23 +58,19 @@ func TestUpload_SingleFile(t *testing.T) {// UP4: Multiple files upload with explicit selectorfunc TestUpload_MultipleFiles(t *testing.T) {- repoRoot := findRepoRoot()- testHtmlPath := filepath.Join(repoRoot, "tests/assets/upload-test.html")- testFileURL := fmt.Sprintf("file://%s", testHtmlPath)-- navCode, _ := httpPost(t, "/navigate", map[string]string{"url": testFileURL})+ navCode, _ := httpPost(t, "/navigate", map[string]string{"url": uploadPageURL(t)})if navCode != 200 {- t.Skipf("navigation to file:// URL not supported (code %d), skipping upload test", navCode)+ t.Fatalf("navigation to upload fixture failed with %d", navCode)}- testFilePath := filepath.Join(repoRoot, "tests/assets/test-upload.png")+ fileData := uploadFixtureBase64(t)code, body := httpPost(t, "/upload", map[string]any{"selector": "#multi",- "paths": []string{testFilePath, testFilePath},+ "files": []string{fileData, fileData},})if code != 200 {- t.Skipf("upload returned %d (file:// URLs have limitations in headless Chrome)", code)+ t.Fatalf("upload returned %d: %s", code, body)}var resp map[string]any@@ -80,34 +86,27 @@ func TestUpload_MultipleFiles(t *testing.T) {// UP6: Default selector (uses default input[type=file])func TestUpload_DefaultSelector(t *testing.T) {- repoRoot := findRepoRoot()- testHtmlPath := filepath.Join(repoRoot, "tests/assets/upload-test.html")- testFileURL := fmt.Sprintf("file://%s", testHtmlPath)-- navCode, _ := httpPost(t, "/navigate", map[string]string{"url": testFileURL})+ navCode, _ := httpPost(t, "/navigate", map[string]string{"url": uploadPageURL(t)})if navCode != 200 {- t.Skipf("navigation to file:// URL not supported (code %d), skipping upload test", navCode)+ t.Fatalf("navigation to upload fixture failed with %d", navCode)}- testFilePath := filepath.Join(repoRoot, "tests/assets/test-upload.png")- code, _ := httpPost(t, "/upload", map[string]any{- "paths": []string{testFilePath},+ code, body := httpPost(t, "/upload", map[string]any{+ "files": []string{uploadFixtureBase64(t)},})if code != 200 {- t.Skipf("upload with default selector returned %d", code)+ t.Fatalf("upload with default selector returned %d: %s", code, body)}}// UP7: Invalid selector should errorfunc TestUpload_InvalidSelector(t *testing.T) {repoRoot := findRepoRoot()- testHtmlPath := filepath.Join(repoRoot, "tests/assets/upload-test.html")- testFileURL := fmt.Sprintf("file://%s", testHtmlPath)- navCode, _ := httpPost(t, "/navigate", map[string]string{"url": testFileURL})+ navCode, _ := httpPost(t, "/navigate", map[string]string{"url": uploadPageURL(t)})if navCode != 200 {- t.Skipf("navigation to file:// URL not supported, skipping upload test")+ t.Fatalf("navigation to upload fixture failed with %d", navCode)}testFilePath := filepath.Join(repoRoot, "tests/assets/test-upload.png")diff --git a/tests/manual/cf3-cdp-create-tab-repro.md b/tests/manual/cf3-cdp-create-tab-repro.mddeleted file mode 100644index d6d05f02..00000000--- a/tests/manual/cf3-cdp-create-tab-repro.md+++ /dev/null@@ -1,154 +0,0 @@-# CF3-Extended: Create Tab via POST in CDP_URL Mode--**Status:** β FIXED (Verified in main.go β CDP_URL mode check added)--**Goal:** Reproduce the crash when creating a new tab via `POST /tab` in CDP_URL mode.--## Prerequisites--- Chrome/Chromium installed-- `curl` CLI-- `jq` for JSON parsing (optional, but helpful)--## Test Steps--### Step 1: Start Chrome with Remote Debugging--```bash-# Kill any existing Chrome instances on port 9222-pkill -f "remote-debugging-port=9222" || true--# Start Chrome with CDP port open (macOS)-# IMPORTANT: Use --headless=chrome NOT --headless (legacy mode with GUI support)-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \- --remote-debugging-port=9222 \- --no-first-run \- --no-default-browser-check \- --disable-background-networking \- --new-window &--sleep 3--# Verify it's listening-curl -s http://localhost:9222/json/version | jq . && echo "β Chrome listening on port 9222"-```--### Step 2: Get the CDP WebSocket URL--```bash-CDP_WS=$(curl -s http://localhost:9222/json/version | jq -r '.webSocketDebuggerUrl')-echo "CDP WebSocket URL: $CDP_WS"-```--Example: `ws://localhost:9222/devtools/browser/12345...`--### Step 3: Start Pinchtab in CDP_URL Mode--```bash-# From pinchtab root-CDP_URL="$CDP_WS" ./pinchtab &-sleep 2--curl http://localhost:9222/health && echo "β Pinchtab started"-```--Expected: Pinchtab should start and connect to remote Chrome without launching its own.--### Step 4: Verify Initial Connection (Should Pass)--```bash-curl -s http://localhost:9222/snapshot | jq '.nodes | length' && echo "β Can snapshot"-```--### Step 5: Pinchtab Startup Fails (Reproducible β)--Pinchtab doesn't even start successfully. It crashes during initialization when trying to set up the remote browser context.--**Actual broken behavior:**-```-2026/02/23 12:29:59 WARN Chrome startup failed, clearing sessions and retrying once-err="Failed to open new tab - no browser is open (-32000)"-2026/02/23 12:29:59 ERROR Chrome failed to start after retry-err="Failed to open new tab - no browser is open (-32000)"-```--**Why it happens:**-- Pinchtab's `startChrome()` function (browser.go line 94) calls `NavigatePage()` to open about:blank-- When using a remote allocator, `NavigatePage()` fails because the remote Chrome instance has no open window/tab to attach to-- No graceful fallback: Pinchtab retries once then exits-- The error should be handled differently for CDP_URL mode (don't require initial tab, respect existing Chrome state)--## Cleanup--```bash-pkill -f "pinchtab"-pkill -f "remote-debugging-port=9222"-```--## Root Cause--**Primary:** In `cmd/pinchtab/browser.go`, `startChrome()` (line 94) always calls `NavigatePage(ctx, "about:blank")` to set up initial state. This assumes a tab already exists or can be created.--**For CDP_URL mode:** Remote Chrome instances may have no windows open, so `NavigatePage()` fails with `-32000` ("Failed to open new tab - no browser is open").--**Secondary:** In `internal/bridge/tab_manager.go`, `CreateTab()` (line 65) doesn't distinguish between:-- Local allocator (can create tabs freely)-- Remote allocator (must use `target.CreateTarget` CDP protocol call, or check browser state first)--## Affected Code--```go-// browser.go, line 94-99-func startChrome(allocCtx context.Context, seededScript string) (context.Context, context.CancelFunc, error) {- bCtx, bCancel := chromedp.NewContext(allocCtx)- // ...- if err := NavigatePage(ctx, "about:blank"); err != nil { // β FAILS for CDP_URL mode- bCancel()- return nil, nil, err- }-}--// tab_manager.go, line 65-func (tm *TabManager) CreateTab(url string) (string, context.Context, context.CancelFunc, error) {- ctx, cancel := chromedp.NewContext(tm.browserCtx) // β CRASHES for remote- if err := NavigatePage(ctx, navURL); err != nil {- cancel()- return "", nil, nil, fmt.Errorf("new tab: %w", err)- }-}-```--## Fix Strategy--1. **In `browser.go` `startChrome()`:**- - Check if we're using CDP_URL mode (can detect via allocator type or config)- - If CDP_URL: Skip `NavigatePage()` during startup (browser may have no windows yet)- - If local: Keep existing behavior (ensure about:blank is open)--2. **In `tab_manager.go` `CreateTab()`:**- - Use `target.CreateTarget` CDP protocol call instead of relying on `chromedp.NewContext`- - This works for both local and remote allocators- - Example:- ```go- targetID, err := target.CreateTarget("about:blank").Do(ctx) // Use CDP protocol directly- ```--3. **Test coverage:**- - Add unit test: `TestCreateTabCDPURL` in `tab_manager_test.go`- - Add integration test: CF3-ext in TEST-PLAN.md--## Status--β **FIXED** β Code review shows fix in place:-- `cmd/pinchtab/main.go` lines ~116-121 now check for CDP_URL mode-- Skips initial tab registration when `cfg.CdpURL != ""`-- `CreateTab()` in tab_manager.go properly uses CDP protocol--**How to verify the fix:**-1. Follow the test steps above (start remote Chrome, start Pinchtab in CDP_URL mode)-2. Expected: Pinchtab should start successfully without crashing-3. Navigate to a URL: `curl -X POST http://localhost:9867/navigate -H "Content-Type: application/json" -d '{"url":"https://example.com"}'`-4. Create new tab: `curl -X POST http://localhost:9867/tab -d '{"action":"new","url":"https://example.com"}'`-5. Both should work without `-32000` errors--**Test this before release to confirm fix is production-ready.**diff --git a/tests/manual/core.md b/tests/manual/core.mddeleted file mode 100644index 35119018..00000000--- a/tests/manual/core.md+++ /dev/null@@ -1,355 +0,0 @@-# Pinchtab Test Plan--**Goal:** Establish a repeatable test suite to validate Pinchtab for stable release.--**Scope:** Functional correctness, regression, edge cases. Covers headless and headed modes, single and multi-agent scenarios.--**How to run:** Each scenario can be executed manually via `curl` or scripted. Integration tests requiring Chrome should use build tag `integration`.-------## 1. Core Endpoints β Headless Single Agent--### 1.1 Health & Startup--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| H1 | Health check | `GET /health` | 200, `{"status":"ok"}` | β Unit test (error path) |-| H2 | Startup headless | `BRIDGE_HEADLESS=true ./pinchtab` | Launches, binds port, Chrome not visible |-| H3 | Startup headed | `./pinchtab` | Chrome window opens, visible |-| H4 | Custom port | `BRIDGE_PORT=9999 ./pinchtab` | Binds to 9999 |-| H5 | Auth token required | `BRIDGE_TOKEN=secret ./pinchtab`, then `GET /health` without token | 401 |-| H6 | Auth token accepted | `GET /health` with `Authorization: Bearer secret` | 200 |-| H7 | Graceful shutdown | Send SIGINT | Chrome closes, port released, exit 0 |--### 1.2 Navigation--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| N1 | Basic navigate | `POST /navigate {"url":"https://example.com"}` | 200, title="Example Domain", url matches |-| N2 | Navigate returns title | Navigate to `https://www.bbc.co.uk` | Title = "BBC - Home" (or similar) |-| N3 | Navigate SPA (slow title) | Navigate to `https://x.com` | Title may be empty (known limitation for heavy SPAs) |-| N4 | Navigate with newTab | `POST /navigate {"url":"...","newTab":true}` | New tab created, new tabId returned, tab count +1 |-| N5 | Navigate invalid URL | `POST /navigate {"url":"not-a-url"}` | Error response, no crash |-| N6 | Navigate missing URL | `POST /navigate {}` | 400, clear error message |-| N7 | Navigate bad JSON | `POST /navigate {broken` | 400, JSON parse error |-| N8 | Navigate timeout | Navigate to extremely slow/hanging URL | Returns within timeout, error or partial |--### 1.3 Snapshot (Accessibility Tree)--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| S1 | Basic snapshot | Navigate to example.com, `GET /snapshot` | Valid JSON, nodes array, refs (e0, e1...) |-| S2 | Interactive filter | `GET /snapshot?filter=interactive` | Only buttons, links, inputs returned |-| S3 | Depth filter | `GET /snapshot?depth=2` | Tree truncated at depth 2 |-| S4 | Text format | `GET /snapshot?format=text` | Indented plain text, not JSON |-| S5 | YAML format | `GET /snapshot?format=yaml` | Valid YAML output |-| S6 | Diff mode | Snapshot twice with `?diff=true` on second | Second returns only changes |-| S7 | Diff first call | `GET /snapshot?diff=true` (no prior snapshot) | Full snapshot (no previous to diff against) |-| S8 | File output | `GET /snapshot?output=file&path=/tmp/test.json` | File written, response confirms path |-| S9 | Snapshot with tabId | `GET /snapshot?tabId=<specific>` | Returns snapshot for that specific tab |-| S10 | Snapshot no tab | Close all tabs, `GET /snapshot` | Error: no tab available |-| S11 | Large page | Navigate to Wikipedia article, snapshot | Handles 20K+ token pages without error |-| S12 | Ref stability | Snapshot β click β snapshot | Refs for unchanged elements stay the same |--### 1.4 Text Extraction--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| T1 | Readability mode | Navigate to BBC article, `GET /text` | Clean article text, no nav/ads |-| T2 | Raw mode | `GET /text?mode=raw` | Full innerText including nav/footer |-| T3 | Text with tabId | `GET /text?tabId=<specific>` | Text from correct tab |-| T4 | Text no tab | `GET /text` with no tabs | Error response |-| T5 | Token efficiency | `/text` on Google | ~150 tokens (not 700+, language blob removed) |--### 1.5 Actions--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| A1 | Click by ref | Snapshot, find button ref, `POST /action {"kind":"click","ref":"eN"}` | Click executed, page state changes |-| A2 | Type by ref | Find input ref, `POST /action {"kind":"type","ref":"eN","text":"hello"}` | Text entered in input |-| A3 | Fill by ref | `POST /action {"kind":"fill","ref":"eN","text":"hello"}` | Input value set (no key events) |-| A4 | Press key | `POST /action {"kind":"press","key":"Enter"}` | Key pressed |-| A5 | Focus | `POST /action {"kind":"focus","ref":"eN"}` | Element focused |-| A6 | Hover | `POST /action {"kind":"hover","ref":"eN"}` | Hover state triggered |-| A7 | Select option | Find select ref, `POST /action {"kind":"select","ref":"eN","value":"opt1"}` | Option selected |-| A8 | Scroll | `POST /action {"kind":"scroll","direction":"down"}` | Page scrolls |-| A9 | Unknown kind | `POST /action {"kind":"dance"}` | 400, lists valid kinds |-| A10 | Missing kind | `POST /action {"ref":"e0"}` | 400, clear error about missing kind |-| A11 | Ref not found | `POST /action {"kind":"click","ref":"e9999"}` | Error: ref not found |-| A12 | CSS selector | `POST /action {"kind":"click","selector":"#submit"}` | Click by CSS selector |-| A13 | Action no tab | Close tabs, `POST /action {"kind":"click","ref":"e0"}` | Error: no tab |-| A14 | Batch actions | `POST /actions [{"kind":"click","ref":"e1"},{"kind":"type","ref":"e2","text":"hi"}]` | Both executed in order |-| A15 | Batch empty | `POST /actions []` | Error: empty batch |-| A16 | Human click | `POST /action {"kind":"humanClick","ref":"eN"}` | Bezier mouse movement + click |-| A17 | Human type | `POST /action {"kind":"humanType","ref":"eN","text":"hello"}` | Natural typing with variable delays |--### 1.6 Tabs--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| TB1 | List tabs | `GET /tabs` | Array of tab objects with id, url, title |-| TB2 | New tab | `POST /tab {"action":"new","url":"https://example.com"}` | New tab opened, id returned |-| TB3 | Close tab | `POST /tab {"action":"close","tabId":"<id>"}` | Tab closed, tab count -1 |-| TB4 | Close without tabId | `POST /tab {"action":"close"}` | 400, tabId required |-| TB5 | Bad action | `POST /tab {"action":"explode"}` | 400, invalid action |-| TB6 | Max tabs | Open 3+ tabs (default limit) | Error or blocks at limit |--### 1.7 Screenshots--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| SS1 | Basic screenshot | `GET /screenshot` | JPEG image data |-| SS2 | Raw screenshot | `GET /screenshot?raw=true` | Raw JPEG bytes (no base64) |-| SS3 | Screenshot no tab | `GET /screenshot` with no tabs | Error |--### 1.8 JavaScript Evaluation--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| E1 | Simple eval | `POST /evaluate {"expression":"1+1"}` | `{"result":"2"}` |-| E2 | DOM eval | `POST /evaluate {"expression":"document.title"}` | Returns page title |-| E3 | Missing expression | `POST /evaluate {}` | 400, error message |-| E4 | Bad JSON | `POST /evaluate {broken` | 400, parse error |-| E5 | Eval no tab | `POST /evaluate {"expression":"1"}` with no tabs | Error |--### 1.9 Cookies--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| C1 | Get cookies | Navigate to site, `GET /cookies` | Returns cookie array |-| C2 | Set cookies | `POST /cookies {"url":"...","cookies":[...]}` | Cookies set |-| C3 | Get cookies no tab | `GET /cookies` with no tabs | Error |-| C4 | Set cookies bad JSON | `POST /cookies {broken` | 400 |-| C5 | Set cookies empty | `POST /cookies {"url":"...","cookies":[]}` | Error or no-op |--### 1.10 File Upload--**Test assets:** `tests/assets/upload-test.html` (HTML page with file inputs), `tests/assets/test-upload.png` (1x1 PNG).-Navigate to the test page first: `POST /navigate {"url":"file://<repo>/tests/assets/upload-test.html"}`--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| UP1 | Upload local file | `POST /upload {"selector":"#single","paths":["tests/assets/test-upload.png"]}` | `{"status":"ok","files":1}` |-| UP2 | Upload base64 data URL | `POST /upload {"selector":"#single","files":["data:image/png;base64,..."]}` | `{"status":"ok","files":1}` |-| UP3 | Upload raw base64 | `POST /upload {"selector":"#single","files":["iVBOR..."]}` | `{"status":"ok","files":1}` |-| UP4 | Upload multiple files | `POST /upload {"selector":"#multi","paths":["tests/assets/test-upload.png","tests/assets/test-upload.png"]}` | `{"status":"ok","files":2}` |-| UP5 | Combined paths + base64 | `POST /upload {"selector":"#multi","paths":["tests/assets/test-upload.png"],"files":["data:image/png;base64,..."]}` | `{"status":"ok","files":2}` |-| UP6 | Default selector | `POST /upload {"paths":["tests/assets/test-upload.png"]}` (no selector) | Uses `input[type=file]`, succeeds |-| UP7 | Invalid selector | `POST /upload {"selector":"#nonexistent","paths":["tests/assets/test-upload.png"]}` | 500, selector error |-| UP8 | Missing files and paths | `POST /upload {"selector":"input[type=file]"}` | 400, error |-| UP9 | File not found | `POST /upload {"paths":["/tmp/nonexistent.jpg"]}` | 400, file not found |-| UP10 | Invalid base64 | `POST /upload {"files":["not-valid!!!"]}` | 400, decode error |-| UP11 | Bad JSON body | `POST /upload {broken` | 400, parse error |-| UP12 | No tab | `POST /upload {"paths":["tests/assets/test-upload.png"]}` with no tabs | Error |--### 1.11 PDF Export--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| PD1 | PDF base64 | Navigate to page, capture `TAB_ID`, `GET /tabs/TAB_ID/pdf` | JSON with `format: "pdf"` and `base64` field |-| PD2 | PDF raw bytes | `GET /tabs/TAB_ID/pdf?raw=true` | Content-Type `application/pdf`, valid PDF bytes |-| PD3 | PDF save to file | `GET /tabs/TAB_ID/pdf?output=file` | JSON with `path` and `size` |-| PD4 | PDF custom path | `GET /tabs/TAB_ID/pdf?output=file&path=/tmp/test.pdf` | File written to `/tmp/test.pdf` |-| PD5 | PDF landscape | `GET /tabs/TAB_ID/pdf?landscape=true&raw=true` | Valid PDF in landscape |-| PD6 | PDF scale | `GET /tabs/TAB_ID/pdf?scale=0.5&raw=true` | Valid PDF with scaled content |-| PD7 | PDF no tab | `GET /tabs/nonexistent/pdf` | 404 error |-| PD8 | PDF specific tab | `GET /tabs/TAB_ID/pdf` | PDF of specified tab |--### 1.12 Stealth--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| ST1 | Stealth status | `GET /stealth/status` | JSON with feature booleans and score |-| ST2 | Webdriver hidden | Navigate, eval `navigator.webdriver` | `undefined` |-| ST3 | Chrome runtime present | Eval `!!window.chrome.runtime` | `true` |-| ST4 | Plugins present | Eval `navigator.plugins.length` | > 0 |-| ST5 | Fingerprint rotate | `POST /fingerprint/rotate {"os":"windows"}` | New fingerprint applied |-| ST6 | Fingerprint rotate random | `POST /fingerprint/rotate {}` | Random OS selected |-| ST7 | Fingerprint no tab | `POST /fingerprint/rotate {}` with no tabs | Error |-| ST8 | Bot detection site | Navigate to `bot.sannysoft.com` | Most checks pass (green) |--### 1.13 Configuration--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| CF1 | Config file | Create `~/.pinchtab/config.json` with port override, start | Uses config port | β Unit test |-| CF2 | Env overrides config | Set `BRIDGE_PORT` env + config file port | Env wins | β Unit test |-| CF3 | CDP_URL external Chrome | `CDP_URL=ws://... ./pinchtab` | Connects to existing Chrome, no launch |-| CF4 | Custom profile dir | `BRIDGE_PROFILE=/tmp/test-profile ./pinchtab` | Uses specified profile |-| CF5 | No restore | `BRIDGE_NO_RESTORE=true ./pinchtab` | Doesn't restore previous tabs |--### 1.16 Security & Validation--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| SEC1 | Profile name with ".." | `POST /profiles {"name":"../../../etc/passwd"}` | 400, invalid profile name |-| SEC2 | Profile name with "/" | `POST /profiles {"name":"test/profile"}` | 400, path separators not allowed |-| SEC3 | Profile name with "\" | `POST /profiles {"name":"test\\profile"}` | 400, path separators not allowed |-| SEC4 | Profile name empty | `POST /profiles {"name":""}` | 400, name required |-| SEC5 | Valid profile names | `POST /profiles {"name":"valid-profile"}` | 201, profile created |-| SEC6 | SSRF prevention | Proxy to non-localhost (e.g., example.com via /tabs/{tabId}/navigate) | 400, localhost required or fails safely |-| SEC7 | Proxy safe URL | Proxy normal navigate via /tabs/{tabId}/navigate | 200, works as expected |--### 1.14 CLI Subcommands--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| CL1 | Navigate | `pinchtab nav https://example.com` | JSON with title and url |-| CL2 | Snapshot interactive | `pinchtab snap -i -c` | Compact output, interactive elements only |-| CL3 | Snapshot diff | `pinchtab snap -d` | Only changes since last snapshot |-| CL4 | Click | `pinchtab click e5` | Action success |-| CL5 | Type | `pinchtab type e12 hello world` | Text typed into element |-| CL6 | Press | `pinchtab press Enter` | Key pressed |-| CL7 | Text extract | `pinchtab text` | JSON with url, title, text |-| CL8 | Text raw | `pinchtab text --raw` | Raw innerText |-| CL9 | Screenshot | `pinchtab ss -o /tmp/test.jpg` | File saved, size reported |-| CL10 | Evaluate | `pinchtab eval "document.title"` | Returns page title |-| CL11 | PDF | `pinchtab pdf --tab <TAB_ID> -o /tmp/test.pdf` | PDF file saved |-| CL12 | Tabs list | `pinchtab tabs` | JSON array of tabs |-| CL13 | Tab new | `pinchtab tabs new https://example.com` | New tab opened |-| CL14 | Health | `pinchtab health` | JSON with status ok |-| CL15 | Help | `pinchtab help` | Help text with all commands |-| CL16 | Custom URL | `PINCHTAB_URL=http://localhost:9877 pinchtab health` | Connects to custom URL |-| CL17 | Auth token | `PINCHTAB_TOKEN=secret pinchtab health` (server has BRIDGE_TOKEN=secret) | Auth succeeds |-| CL18 | Server down | `pinchtab health` (no server running) | Error: connection failed |--### 1.15 Session Persistence--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| SP1 | Tab restore | Open tabs, stop, restart | Previous tabs restored |-| SP2 | Cookie persistence | Log into site, restart | Still logged in |-| SP3 | No restore flag | Open tabs, restart with `BRIDGE_NO_RESTORE=true` | Clean start, no old tabs |-------## 2. Headed Mode β Additional Scenarios--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| HM1 | Chrome visible | Start without `BRIDGE_HEADLESS` | Chrome window visible, interactable |-| HM2 | Manual + API coexist | Manually browse in Chrome + API calls | Both work, no conflicts |-| HM3 | Manual login persists | Log into GitHub manually in Chrome window | `/cookies` shows session, persists on restart |-------## 3. Multi-Agent Scenarios--Multiple agents (or concurrent scripts) hitting the same Pinchtab instance.--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| MA1 | Concurrent reads | Two agents snapshot different tabs by tabId simultaneously | Both get correct results |-| MA2 | Concurrent navigates | Agent A navigates tab1, Agent B navigates tab2 (by tabId) | Both succeed, no cross-talk |-| MA3 | Tab isolation | Agent A works on tab1, Agent B on tab2 | Actions don't leak across tabs |-| MA4 | Concurrent actions | Agent A clicks on tab1, Agent B types on tab2 | Both succeed |-| MA5 | Ref collision | Both agents snapshot same tab, get same refs | Refs consistent, actions work for both |-| MA6 | Rapid fire | 10 concurrent `/snapshot` requests | All return valid data, no 500s |-| MA7 | Tab limit | Two agents both try to open tabs up to limit | One gets error, no crash |-| MA8 | No tabId default | Agent A navigates, Agent B calls `/snapshot` (no tabId) | Returns *some* tab (undefined which β this is the active tab tracking issue) |-------## 4. Stealth Integration Tests (require Chrome)--Run with: `go test -tags integration -v`--### Automated (in `integration_test.go`) β-| # | Test | Status |-|---|------|--------|-| SI1 | TestStealthScriptInjected β `navigator.webdriver === undefined` | β Pass |-| SI2 | TestCanvasNoiseApplied β `toDataURL` differs per call | β Pass |-| SI3 | TestFontMetricsNoise β Proxy-wrapped TextMetrics, positive widths | β Pass |-| SI4 | TestWebGLVendorSpoofed β `UNMASKED_VENDOR_WEBGL = "Intel Inc."` | βοΈ Skip (headless, no GPU) |-| SI5 | TestPluginsPresent β `navigator.plugins.length >= 3` | β Pass |-| SI6 | TestFingerprintRotation β CDP UA override, Edge UA after rotate | β Pass |-| SI7 | TestCDPTimezoneOverride β `Intl.DateTimeFormat` returns spoofed TZ | β Pass |-| SI8 | TestStealthStatusEndpoint β score >= 50, level high/medium | β Pass |--### Manual (quarterly against detection sites)-| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| SI9 | bot.sannysoft.com | Navigate, screenshot | Most items green |-| SI10 | creepjs | Navigate to `abrahamjuliot.github.io/creepjs/` | Trust score reasonable |-| SI11 | browserleaks | Navigate to `browserleaks.com/javascript` | No automation flags |-------## 5. Docker Scenarios--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D1 | Docker build | `docker build -t pinchtab .` | Builds successfully |-| D2 | Docker run | `docker run -d -p 9867:9867 pinchtab` | Container starts, health returns 200 |-| D3 | Docker navigate | Navigate to example.com from host | Works, returns title |-| D4 | Docker snapshot | `GET /snapshot` from host | Valid JSON |-| D5 | Docker with token | `docker run -e BRIDGE_TOKEN=secret ...` | Auth enforced |-| D6 | Docker CHROME_BINARY | Verify Chromium binary path consumed | Uses container Chromium |-| D7 | Docker CHROME_FLAGS | Set custom flags via env | Flags applied |-------## 6. Configuration β Extended--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| CF6 | Chrome version override | `BRIDGE_CHROME_VERSION=134.0.0.0 ./pinchtab` | UA string uses 134 |-| CF7 | Chrome version default | Start without `BRIDGE_CHROME_VERSION` | UA uses 133.0.6943.98 |-| CF8 | Chrome version in fingerprint | Set version, then `POST /fingerprint/rotate` | Rotated fingerprint uses same Chrome version |-------## 7. Error Handling & Edge Cases--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| ER1 | Chrome crash recovery | Kill Chrome process while Pinchtab running | Pinchtab detects, returns errors (not hang) |-| ER2 | Large page snapshot | Navigate to page with 1000+ a11y nodes | Returns full snapshot, no timeout |-| ER3 | Binary page | Navigate to PDF/image URL | Handles gracefully (error or empty snapshot) |-| ER4 | Rapid navigate | 5 navigates in 1 second | No crash, last one wins |-| ER5 | Unicode content | Navigate to page with CJK/emoji/RTL | Text and snapshot handle correctly |-| ER6 | Empty page | Navigate to `about:blank` | Snapshot returns minimal tree |-| ER7 | Connection refused (CDP_URL) | `CDP_URL=ws://localhost:1111` | Clear error message, exits |-| ER8 | Port in use | Start two instances on same port | Second fails with clear error |-------## 8. Known Issues (from QA rounds)--Track these separately β they are known bugs, not test failures.--| # | Issue | Severity | Status | Notes |-|---|-------|----------|--------|-------|-| K1 | Active tab tracking unreliable after navigate | π΄ P0 | β FIXED | Confirmed working in autorun hour 00. |-| K2 | Tab close hangs | π‘ P1 | β FIXED | Hour 07: switched to `target.CloseTarget` (browser-level CDP). No more hangs. |-| K3 | x.com title always empty | π’ P2 | π§ IMPROVED | Hour 03: added `waitTitle` param to navigate. Agents can wait for SPA titles. |-| K4 | Chrome flag warning banner | π’ P2 | β FIXED | Removed deprecated flag (hour 05); CDP stealth handles it. |-| K5 | Stealth PRNG weak (8F-2) | π‘ P1 | β FIXED | Now uses Mulberry32 with Go-injected seed. |-| K6 | Chrome UA hardcoded to 131 (8F-6) | π‘ P1 | β FIXED | Configurable via `BRIDGE_CHROME_VERSION`, default 133. |-| K7 | Fingerprint rotation JS-only (8F-7) | π’ P2 | β FIXED | Now uses CDP `Emulation.SetUserAgentOverride` for UA/platform/language. |-| K8 | Timezone hardcoded EST (8F-9) | π’ P2 | β FIXED | Now uses CDP `Emulation.SetTimezoneOverride` via `BRIDGE_TIMEZONE` env var. |-| K9 | Stealth status hardcoded (8F-10) | π’ P2 | β FIXED | Now probes browser when tab available. |-------## 9. Release Criteria for Stable v1.0--### Must Pass (P0)-- All Section 1 scenarios (core endpoints) pass in headless-- All Section 1 scenarios pass in headed-- K1 (active tab tracking) fixed OR documented as "always use tabId"-- K2 (tab close hangs) fixed-- Zero crashes across full test suite-- `go test ./...` 100% pass (currently: β 54 unit tests)-- `go test -tags integration` pass (currently: β 6 pass, 1 skip headless, 1 skip headed-only)--### Should Pass (P1)-- Section 3 multi-agent scenarios MA1-MA5 pass-- Stealth passes `bot.sannysoft.com` basic checks-- Session persistence works (SP1, SP2)--### Nice to Have (P2)-- Coverage > 30%-- K3-K4 addressed or documented (K5-K9 all fixed)-- Performance benchmarks baselineddiff --git a/tests/manual/dashboard.md b/tests/manual/dashboard.mddeleted file mode 100644index 2ef22df4..00000000--- a/tests/manual/dashboard.md+++ /dev/null@@ -1,266 +0,0 @@-# PinchTab Dashboard Test Plan--**Goal:** Validate the dashboard mode β profile management, orchestrator (instance lifecycle), proxy routing, SSE events, and UI serving.--**Constraint:** Tests MUST NOT delete or modify existing profiles. Use a dedicated test profile (`__test_profile__`) for all mutations.-------## 1. Health & Mode--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DH1 | Dashboard health | `GET /health` | 200, `{"status":"ok","mode":"dashboard"}` | β |-| DH2 | Dashboard UI serves | `GET /` | 200, HTML with `<html` | β |-------## 2. Profile Management (CRUD)--All tests use `__test_profile__` β cleaned up at end.--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DP1 | List profiles | `GET /profiles` | 200, array of profiles (existing ones present) | β |-| DP2 | Create profile | `POST /profiles/create {"name":"__test_profile__"}` | 201, created | β |-| DP3 | Create duplicate | `POST /profiles/create {"name":"__test_profile__"}` | 409, conflict | β |-| DP4 | Create missing name | `POST /profiles/create {}` | 400, name required | β |-| DP5 | Create bad JSON | `POST /profiles/create {broken` | 400, invalid JSON | β |-| DP6 | Create with metadata | `POST /profiles/create {"name":"__test_profile_meta__","useWhen":"testing","description":"test profile"}` | 201, created with meta | β |-| DP7 | Update metadata | `PATCH /profiles/__test_profile__ {"useWhen":"updated","description":"updated desc"}` | 200, updated info | β |-| DP8 | Rename profile | `PATCH /profiles/__test_profile__ {"name":"__test_profile_renamed__"}` | 200, renamed | β |-| DP9 | Reset profile | `POST /profiles/__test_profile_renamed__/reset` | 200, reset | β |-| DP10 | Delete profile | `DELETE /profiles/__test_profile_renamed__` | 200, deleted | β |-| DP11 | Delete nonexistent | `DELETE /profiles/__nonexistent__` | 404 | β |-| DP12 | Reset nonexistent | `POST /profiles/__nonexistent__/reset` | 404 | β |-| DP13 | Profile logs (empty) | `GET /profiles/__test_profile_meta__/logs` | 200, empty array | β |-| DP14 | Profile analytics | `GET /profiles/__test_profile_meta__/analytics` | 200, analytics object | β |-| DP15 | Cleanup meta profile | `DELETE /profiles/__test_profile_meta__` | 200, deleted | β |-------## 3. Orchestrator β Instance Lifecycle--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DO1 | List instances (initial) | `GET /instances` | 200, array (may be empty or have running instances) | β |-| DO2 | Launch instance | `POST /instances/launch {"name":"__test_profile__","port":"<free>"}` | 201, instance with id/status | β |-| DO3 | Launch missing fields | `POST /instances/launch {"name":""}` | 400, name and port required | β |-| DO4 | Launch bad JSON | `POST /instances/launch {broken` | 400 | β |-| DO5 | Instance appears in list | `GET /instances` | Array includes __test_profile__ instance | β |-| DO6 | Profile instance status | `GET /profiles/__test_profile__/instance` | 200, running=true, port matches | β |-| DO7 | Instance logs | `GET /instances/{id}/logs` | 200, text content | β |-| DO8 | All tabs across instances | `GET /instances/tabs` | 200, array | β |-| DO9 | Stop instance | `POST /instances/{id}/stop` | 200, stopped | β |-| DO10 | Stop nonexistent | `POST /instances/nonexistent/stop` | 404 | β |-| DO11 | Profile instance after stop | `GET /profiles/__test_profile__/instance` | 200, running=false | β |-| DO12 | Launch duplicate port | Launch two profiles on same port | 409, conflict | β |-| DO13 | Stop by profile name | `POST /profiles/__test_profile__/stop` (when running) | 200, stopped | β |-| DO14 | Start by profile ID | `POST /profiles/{profileId}/start` | 201, auto-allocated port | β |-| DO15 | Stop by profile ID | `POST /profiles/{profileId}/stop` | 200, stopped | β |-------## 4. Proxy Routing (requires running instance)--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DX1 | Proxy with no instances | Stop all test instances, `GET /snapshot` | 503, "no running instances" | β |-| DX2 | Proxy navigate | Launch instance, `POST /navigate {"url":"https://example.com"}` via dashboard port | 200, proxied to instance | β |-| DX3 | Proxy snapshot | `GET /snapshot` via dashboard port | 200, valid JSON with nodes | β |-| DX4 | Proxy tabs | `GET /tabs` via dashboard port | 200, array | β |-| DX5 | Proxy screenshot | `GET /screenshot` via dashboard port | 200, image data | β |-| DX6 | Proxy evaluate | `POST /evaluate {"expression":"1+1"}` via dashboard | 200, result | β |-| DX7 | Proxy cookies | `GET /cookies` via dashboard | 200, array | β |-| DX8 | Proxy stealth | `GET /stealth/status` via dashboard | 200, stealth info | β |-------## 5. SSE Events--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DS1 | SSE connect | `GET /dashboard/events` with Accept: text/event-stream | 200, receives `event: init` with agent data | β οΈ |-| DS2 | SSE keepalive | Hold connection 35s | Receives `: keepalive` comment | π§ Manual |-------## 6. Dashboard Agents API--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DA1 | List agents | `GET /dashboard/agents` | 200, array of agent objects | β |-------## 7. Edge Cases--| # | Scenario | Steps | Expected | Auto |-|---|----------|-------|----------|------|-| DE1 | Shutdown endpoint | `POST /shutdown` | 200, dashboard shuts down | π§ Manual |-| DE2 | CORS headers | `OPTIONS /health` | CORS headers present | β |-| DE3 | Port already in use | Launch on occupied port | 409 or error | β |-| DE4 | Rapid launch/stop | Launch β stop β launch same profile | Both succeed, no crash | β |-| DE5 | Screencast proxy info | `GET /instances/{id}/proxy/screencast?tabId=test` | 200, wsUrl | β |-------## 8. UI Functional Tests (Manual / Browser)--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| DU1 | Dashboard loads | Open `http://localhost:9867/dashboard` in browser | Page renders, profiles visible |-| DU2 | Profile list shows | View Profiles tab | Existing profiles listed with status |-| DU3 | Create profile via UI | Click create, enter name | Profile appears in list |-| DU4 | Launch profile via UI | Click launch/start on a profile | Instance starts, status updates to running |-| DU5 | Stop profile via UI | Click stop on running profile | Instance stops, status updates |-| DU6 | Screencast tab | Switch to screencast tab while instance running | Live view of browser |-| DU7 | Agents tab | Switch to agents tab | Shows connected agents / activity |-| DU8 | Settings tab | Switch to settings tab | Displays configuration |-| DU9 | Profile analytics via UI | Click analytics on a profile with history | Shows charts/stats |-------## 9. Endpoint Existence Checks--Verify every registered route returns a non-404 status (may return 400/503 for missing params, but not 404 routing failures).--### Dashboard / Health--| # | Route | Method | Expected | Auto |-|---|-------|--------|----------|------|-| RE1 | `/health` | GET | 200 | β |-| RE2 | `/dashboard` | GET | 200 (HTML) | β |-| RE3 | `/dashboard/agents` | GET | 200 | β |-| RE4 | `/dashboard/events` | GET | 200 (SSE stream) | β |-| RE5 | `/shutdown` | POST | 200 (β οΈ kills dashboard) | π§ Manual |--### Profiles--| # | Route | Method | Expected | Auto |-|---|-------|--------|----------|------|-| RE6 | `/profiles` | GET | 200 | β |-| RE7 | `/profiles/create` | POST | 400 (no body) | β |-| RE8 | `/profiles/import` | POST | 400 (no body) | β |-| RE9 | `/profiles/meta` | PATCH | 400 (no body) | β |-| RE10 | `/profiles/__nonexistent__` | DELETE | 404 | β |-| RE11 | `/profiles/__nonexistent__` | PATCH | 400 (no body) | β |-| RE12 | `/profiles/__nonexistent__/reset` | POST | 404 | β |-| RE13 | `/profiles/__nonexistent__/logs` | GET | 200 (empty) | β |-| RE14 | `/profiles/__nonexistent__/analytics` | GET | 200 | β |-| RE15 | `/profiles/__nonexistent__/instance` | GET | 200 (running=false) | β |-| RE16 | `/profiles/__nonexistent__/stop` | POST | 404 | β |--### Orchestrator--| # | Route | Method | Expected | Auto |-|---|-------|--------|----------|------|-| RE17 | `/instances` | GET | 200 | β |-| RE18 | `/instances/tabs` | GET | 200 | β |-| RE19 | `/instances/launch` | POST | 400 (no body) | β |-| RE20 | `/instances/nonexistent/stop` | POST | 404 | β |-| RE21 | `/instances/nonexistent/logs` | GET | 404 | β |-| RE22 | `/instances/nonexistent/proxy/screencast?tabId=x` | GET | 404 | β |--### Profile lifecycle (by ID β canonical for agents)--| # | Route | Method | Expected | Auto |-|---|-------|--------|----------|------|-| RE23 | `/profiles/{id}/start` | POST | 201 (launches instance) | β |-| RE24 | `/profiles/{id}/stop` | POST | 200 (stops instance) | β |-| RE25a | `/profiles/{id}/instance` | GET | 200 (instance status) | β |-| RE25b | `/profiles/{unknownId}/start` | POST | 404 | β |--### Proxy endpoints (503 when no instance running)--| # | Route | Method | Expected (no instance) | Auto |-|---|-------|--------|------------------------|------|-| RE25 | `/tabs` | GET | 503 | β |-| RE26 | `/snapshot` | GET | 503 | β |-| RE27 | `/screenshot` | GET | 503 | β |-| RE28 | `/text` | GET | 503 | β |-| RE29 | `/navigate` | POST | 503 | β |-| RE30 | `/action` | POST | 503 | β |-| RE31 | `/actions` | POST | 503 | β |-| RE32 | `/evaluate` | POST | 503 | β |-| RE33 | `/tab` | POST | 503 | β |-| RE34 | `/tab/lock` | POST | 503 | β |-| RE35 | `/tab/unlock` | POST | 503 | β |-| RE36 | `/cookies` | GET | 503 | β |-| RE37 | `/cookies` | POST | 503 | β |-| RE38 | `/stealth/status` | GET | 503 | β |-| RE39 | `/fingerprint/rotate` | POST | 503 | β |-| RE40 | `/screencast` | GET | 503 | β |-| RE41 | `/screencast/tabs` | GET | 503 | β |-------## 10. Security: Validation Tests--### DSE1: Profile Name Validation--**Goal:** Verify invalid profile names are rejected by the API.--**Steps:**-1. Start dashboard-2. Try to create profile with ".." in name:- ```bash- curl -X POST http://localhost:9867/profiles \- -H "Content-Type: application/json" \- -d '{"name":"../test"}'- ```- Should get **400 Bad Request** (invalid profile name)--3. Try with "/" separator:- ```bash- curl -X POST http://localhost:9867/profiles \- -H "Content-Type: application/json" \- -d '{"name":"test/profile"}'- ```- Should get **400 Bad Request**--4. Try with empty name:- ```bash- curl -X POST http://localhost:9867/profiles \- -H "Content-Type: application/json" \- -d '{"name":""}'- ```- Should get **400 Bad Request**--5. Create valid profile (control):- ```bash- curl -X POST http://localhost:9867/profiles \- -H "Content-Type: application/json" \- -d '{"name":"__test_security__"}'- ```- Should get **201 Created**--6. Clean up:- ```bash- curl -X DELETE http://localhost:9867/profiles/__test_security__- ```--**Expected:** Invalid names rejected with 400, valid names accepted with 201.--**Criteria:** β ".." rejected | β "/" rejected | β "" rejected | β Valid names work-------## Release Criteria--### Must Pass-- All Section 1 (health/UI serving)-- All Section 2 (profile CRUD) β no side effects on existing profiles-- Section 3 DO1-DO11 (basic instance lifecycle)-- Section 4 DX1-DX4 (proxy basics)-- Section 9 RE1-RE41 (all endpoints reachable)--### Should Pass-- Section 3 DO12-DO15 (advanced orchestration)-- Section 4 DX5-DX8 (all proxy endpoints)-- Section 6 (agents API)--### Nice to Have-- Section 5 (SSE)-- Section 7 (edge cases)-- Section 8 (UI manual)diff --git a/tests/manual/docker.md b/tests/manual/docker.mddeleted file mode 100644index 6b3d600f..00000000--- a/tests/manual/docker.md+++ /dev/null@@ -1,81 +0,0 @@-# Pinchtab Docker Test Plan--**Goal:** Validate the Docker image builds, runs, and behaves identically to the native binary.--**Prerequisites:** Docker installed, `pinchtab/pinchtab:latest` image available (pull or local build).-------## 1. Image Build & Structure--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D1 | Build succeeds | `docker build -t pinchtab/pinchtab .` | Exit 0, image created |-| D2 | Image size reasonable | `docker images pinchtab/pinchtab --format '{{.Size}}'` | < 1GB |-| D3 | Non-root user | `docker run --rm pinchtab/pinchtab whoami` | `pinchtab` |-| D4 | Binary present | `docker run --rm pinchtab/pinchtab which pinchtab` | `/usr/local/bin/pinchtab` |-| D5 | Chromium present | `docker run --rm pinchtab/pinchtab which chromium-browser` | Path returned |-| D6 | No build artifacts | `docker run --rm pinchtab/pinchtab ls /build 2>&1` | Directory not found |--## 2. Container Startup & Health--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D7 | Default startup | `docker run -d -p 9867:9867 --security-opt seccomp=unconfined pinchtab/pinchtab` | Container starts, stays running |-| D8 | Health check | `curl http://localhost:9867/health` | 200, `{"status":"ok"}` |-| D9 | Custom port | `docker run -d -p 8080:8080 -e BRIDGE_PORT=8080 --security-opt seccomp=unconfined pinchtab/pinchtab` | Health on :8080 |-| D10 | Auth token | `docker run -d -p 9867:9867 -e BRIDGE_TOKEN=secret --security-opt seccomp=unconfined pinchtab/pinchtab` | `/health` without token β 401, with token β 200 |-| D11 | Graceful stop | `docker stop <container>` | Exit 0, no zombie Chrome processes |--## 3. Core Functionality (in container)--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D12 | Navigate | `POST /navigate {"url":"https://example.com"}` | 200, title="Example Domain" |-| D13 | Snapshot | `GET /snapshot?tabId=<id>` | 200, accessibility tree returned |-| D14 | Text extract | `GET /text?tabId=<id>` | 200, page text content |-| D15 | Click action | `POST /action {"kind":"click","ref":"e1"}` | 200, action performed |-| D16 | Multi-tab | Open 3 tabs via `/navigate`, `GET /tabs` | All 3 tabs listed |--## 4. Persistence & Volumes--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D17 | State dir mounted | `docker run -v pinchtab-data:/data ...`, navigate + login, stop, restart | Session/cookies persist |-| D18 | Profile persistence | Same as D17 β Chrome profile in `/data/chrome-profile` | Login state survives restart |-| D19 | Without volume | Run without `-v`, stop, restart | Clean slate, no state |--## 5. Docker Compose--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D20 | Compose up | `docker compose up -d` | Container starts, health OK |-| D21 | Compose with token | `PINCHTAB_TOKEN=secret docker compose up -d` | Auth enforced |-| D22 | Compose down + up | `docker compose down && docker compose up -d` | Volume persists, clean restart |-| D23 | SHM size | Check Chrome stability under load (compose sets `shm_size: 2gb`) | No crashes from shared memory exhaustion |--## 6. Multi-Platform--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D24 | AMD64 image | Pull/run on x86_64 host | Works correctly |-| D25 | ARM64 image | Pull/run on ARM host (e.g. Apple Silicon via Rosetta, Raspberry Pi) | Works correctly |--## 7. Resource & Security--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D26 | Memory limit | `docker run --memory=512m ...` | Runs (may OOM on heavy pages, but starts OK) |-| D27 | CPU limit | `docker run --cpus=1 ...` | Runs, slower but functional |-| D28 | seccomp required | `docker run -d -p 9867:9867 pinchtab/pinchtab` (no seccomp flag) | Chrome may fail to launch β document requirement |-| D29 | Read-only rootfs | `docker run --read-only -v pinchtab-data:/data ...` | Runs (writes only to /data) |-| D30 | No privileged | `docker run ...` (without `--privileged`) | Works with seccomp=unconfined, no need for privileged |--## 8. Edge Cases--| # | Scenario | Steps | Expected |-|---|----------|-------|----------|-| D31 | Rapid restart | `docker restart <container>` 5 times quickly | No port conflicts, no zombie processes |-| D32 | OOM kill recovery | Kill Chrome inside container | Pinchtab detects and either restarts Chrome or exits cleanly |-| D33 | Container logs | `docker logs <container>` | Startup info visible, no sensitive data leaked |-| D34 | Signal forwarding | `docker kill -s SIGTERM <container>` | dumb-init forwards signal, clean shutdown |diff --git a/tests/manual/file-upload.md b/tests/manual/file-upload.mddeleted file mode 100644index 06870f26..00000000--- a/tests/manual/file-upload.md+++ /dev/null@@ -1,65 +0,0 @@-# UP1-UP11: File Upload Tests (Manual)--**Status:** β οΈ Manual test β headless Chrome limitations--## Why Manual?--Headless Chrome doesn't support:-- `file://` URL navigation (security restriction)-- File picker UI interactions-- Local file access in headless mode--These limitations make automated testing impractical in CI.--## Test Steps--### Setup-1. Start Pinchtab in headed mode (with display):- ```bash- BRIDGE_HEADLESS=false ./pinchtab- ```--2. Have test files ready:- - `tests/assets/upload-test.html` (form with `#single` and `#multi` inputs)- - `tests/assets/test-upload.png` (1x1 PNG test image)--### UP1: Single File Upload-1. Navigate to `file:///<repo>/tests/assets/upload-test.html`-2. POST `/upload` with:- ```json- {- "selector": "#single",- "paths": ["/path/to/test-upload.png"]- }- ```-3. Verify response: `{"status":"ok","files":1}`--### UP4: Multiple Files-1. Same setup as UP1-2. POST to `#multi` selector with multiple file paths-3. Verify: `{"status":"ok","files":2}`--### UP6: Default Selector-1. POST `/upload` without selector (should use first `input[type=file]`)-2. Verify: 200 response--### UP7: Invalid Selector-1. POST with selector `#nonexistent`-2. Verify: 400 or 500 error--### UP8: Missing Files-1. POST without `paths` field-2. Verify: 400 error--### UP9: File Not Found-1. POST with non-existent file path-2. Verify: 400 error--### UP11: Bad JSON-1. POST malformed JSON-2. Verify: 400 error--## Notes-- Use headed Chrome (not headless) for these tests-- File picker security may still block access depending on system-- Alternative: mock the file input via JS if `file://` still blockeddiff --git a/tests/manual/npm.md b/tests/manual/npm.mddeleted file mode 100644index 55741864..00000000--- a/tests/manual/npm.md+++ /dev/null@@ -1,48 +0,0 @@-# Pinchtab npm Package β Test Plan--## Scope-Test that the npm package correctly:-1. Finds and executes the Pinchtab binary-2. Manages process lifecycle (start/stop)-3. Communicates with the API via HTTP-4. Handles errors gracefully--## Test Cases--### 1. Binary Discovery-- β Binary exists at `~/.pinchtab/bin/pinchtab-<os>-<arch>`-- β CLI wrapper finds and executes binary-- β Graceful error if binary missing--### 2. Process Lifecycle-- β `start()` spawns server on correct port-- β Server responds to health check (any endpoint)-- β `stop()` kills process cleanly-- β `start()` twice throws error-- β `stop()` when not running is no-op--### 3. API Requests-- β `snapshot()` returns valid response-- β `click()` executes without error-- β `lock()` / `unlock()` work-- β `createTab()` returns tab ID-- β Request timeout after 30s--### 4. Error Handling-- β Invalid endpoint returns 404-- β Malformed params rejected-- β Server crashes β clear error message--## Environment-- Binary must exist: `~/.pinchtab/bin/pinchtab-darwin-arm64` (or platform equivalent)-- Port 9867 must be available-- Test runner: Node.js native `test` module--## Execution-```bash-cd npm && npm test-```-------*Add new test cases as you discover edge cases.*diff --git a/tests/manual/orchestrator.md b/tests/manual/orchestrator.mddeleted file mode 100644index bb972236..00000000--- a/tests/manual/orchestrator.md+++ /dev/null@@ -1,620 +0,0 @@-# 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- TAB_ID=$(curl -s -X POST http://localhost:9867/instances/{id}/tabs/open \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"about:blank"}' | jq -r '.tabId')- curl -X POST http://localhost:9867/tabs/$TAB_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- TAB_ID=$(curl -s -X POST http://localhost:9867/instances/${IDS[$i]}/tabs/open \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"about:blank"}' | jq -r '.tabId')- curl -X POST http://localhost:9867/tabs/$TAB_ID/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')-- TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$ID/tabs/open \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"about:blank"}' | jq -r '.tabId')- curl -X POST http://localhost:9867/tabs/$TAB_ID/navigate \- -H "Content-Type: application/json" \- -d '{"url":"https://example.com"}' > /dev/null- ```--2. Request snapshot via orchestrator:- ```bash- curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | length'- ```--3. Request screenshot via orchestrator:- ```bash- curl http://localhost:9867/tabs/$TAB_ID/screenshot > /tmp/test.jpg- file /tmp/test.jpg- ```--4. Verify both succeed and return expected formats.--**Criteria:** β Snapshot JSON valid | β Screenshot is JPEG | β 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-------## 10. Security: Path Traversal & SSRF Prevention--### MSE1: Profile Name Path Traversal Blocked--**Goal:** Verify that profile names with "..", "/", or "\" are rejected.--**Steps:**-1. Start dashboard-2. Try to create a profile with traversal pattern:- ```bash- curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"../../../etc/passwd","headless":true}'- ```- Should get **400 Bad Request** (invalid profile name)--3. Try with "/" separator:- ```bash- curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"test/malicious","headless":true}'- ```- Should get **400 Bad Request**--4. Try with empty name:- ```bash- curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"","headless":true}'- ```- Should get **400 Bad Request**--5. Create valid profile (control):- ```bash- curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"valid-profile","headless":true}'- ```- Should get **201 Created**--**Expected:** Malicious names rejected with 400, valid names accepted with 201.--**Criteria:** β ".." rejected | β "/" rejected | β "\" rejected | β "" rejected | β valid names accepted-------### MSE2: SSRF Prevention β Proxy Localhost Only--**Goal:** Verify that proxy endpoints only target localhost.--**Steps:**-1. Create an instance:- ```bash- curl -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d '{"name":"ssrf-test","headless":true}'- ```- Note the `id` and `port`.--2. Navigate via proxy (should work):- ```bash- TAB_ID=$(curl -s -X POST http://localhost:9867/instances/{id}/tabs/open \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"about:blank"}' | jq -r '.tabId')- curl -X POST http://localhost:9867/tabs/$TAB_ID/navigate \- -H "Content-Type: application/json" \- -d '{"url":"https://example.com"}'- ```- Should get **200 OK** (proxy routes to localhost instance)--3. Stop instance:- ```bash- curl -X POST http://localhost:9867/instances/{id}/stop- ```--**Expected:** Proxy routes to localhost instance without error.--**Criteria:** β Proxy navigates successfully | β URL constructed safely-------## 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).diff --git a/tests/manual/screenshot-raw.md b/tests/manual/screenshot-raw.mddeleted file mode 100644index 96b83e5a..00000000--- a/tests/manual/screenshot-raw.md+++ /dev/null@@ -1,59 +0,0 @@-# SS2: Raw Screenshot Test (Manual)--**Status:** β οΈ Manual test β headless Chrome CDP limitations--## Why Manual?--Headless Chrome's CDP implementation has limitations with raw screenshot output:-- May fail under certain display configurations-- Requires proper GPU/display context that's not always available in headless-- Works fine in headed mode or with GPU-enabled Docker--## Test Steps--### Setup-1. Start Pinchtab normally (can be headed or headless, but with display support):- ```bash- ./pinchtab- ```--2. Ensure Chrome is running with display context (or GPU if headless)--### SS2: Raw Screenshot--1. Navigate to a page:- ```bash- curl -X POST http://localhost:9867/navigate \- -H "Content-Type: application/json" \- -d '{"url":"https://example.com"}'- ```--2. Request raw screenshot:- ```bash- curl http://localhost:9867/screenshot?raw=true \- --output screenshot.jpg- ```--3. Verify:- - Status code: 200- - File exists and is valid JPEG- - File starts with JPEG magic bytes: `FF D8`- - Can be opened in image viewer--### Alternative: Base64 Screenshot (Works in CI)--If raw fails, the base64 version works reliably:-```bash-curl http://localhost:9867/screenshot-```--This returns JSON with `base64` field containing the image data.--## Debugging--If `/screenshot?raw=true` returns 500:--1. Check Pinchtab logs for CDP errors-2. Try base64 version instead (SS1)-3. Ensure display is available (check `DISPLAY` env var)-4. Try in headed mode: `BRIDGE_HEADLESS=false ./pinchtab`diff --git a/tests/manual/test-recovery.ps1 b/tests/manual/test-recovery.ps1deleted file mode 100644index 985856eb..00000000--- a/tests/manual/test-recovery.ps1+++ /dev/null@@ -1,879 +0,0 @@-# =============================================================================-# PinchTab - Self-Healing Recovery System Manual Test Suite-# =============================================================================-# Tests: /find enhancements + self-healing recovery engine (PR #2)-#-# What is tested:-# - POST /find : TrimSpace, per-request weights, explain field-# - POST /action: recovery field in response, stale-ref self-healing-# - POST /actions: batch recovery-# - POST /macro : macro-step recovery-# - Failure classification edge cases via known error patterns-# - Real-world recovery scenarios on live websites-#-# How recovery is triggered in these tests:-# 1. Navigate to a page - Chrome assigns fresh nodeIDs-# 2. POST /find - intent is cached in the RecoveryEngine-# 3. Navigate to the SAME page (reload) - Chrome rebuilds the DOM;-# all nodeIDs are now different, but our snapshot still holds-# the OLD refs -> nodeID mapping-# 4. POST /action with the old ref - ExecuteAction fails with-# "could not find node" since the nodeID is stale -> recovery-# re-matches semantically and re-executes -> response.recovery.recovered = true-#-# Prerequisites:-# - PinchTab server running on $BASE (default: http://localhost:9867)-# - jq.exe on PATH OR PowerShell 7+ (ConvertFrom-Json used instead)-# - Internet access for real-site tests-#-# Usage:-# # Default (localhost:9867)-# .\tests\manual\test-recovery.ps1-#-# # Custom port-# .\tests\manual\test-recovery.ps1 -Port 9868-#-# # Skip slow website tests-# .\tests\manual\test-recovery.ps1 -SkipRealSites-#-# # Stop on first failure-# .\tests\manual\test-recovery.ps1 -FailFast-# =============================================================================--param(- [int] $Port = 9867,- [switch]$SkipRealSites,- [switch]$FailFast,- [switch]$Verbose-)--$BASE = "http://localhost:$Port"-$PASS = 0-$FAIL = 0-$SKIP = 0-$TAB = $null # active tab ID, set after each navigate--# ----------------------------------------------------------------------------# Helpers-# ----------------------------------------------------------------------------function Write-Header($text) {- Write-Host ""- Write-Host ("=" * 72) -ForegroundColor Cyan- Write-Host " $text" -ForegroundColor Cyan- Write-Host ("=" * 72) -ForegroundColor Cyan-}--function Write-Section($text) {- Write-Host ""- Write-Host "--- $text ---" -ForegroundColor Yellow-}--function Pass($name) {- $script:PASS++- Write-Host " [PASS] $name" -ForegroundColor Green-}--function Fail($name, $detail = "") {- $script:FAIL++- Write-Host " [FAIL] $name" -ForegroundColor Red- if ($detail) { Write-Host " $detail" -ForegroundColor DarkRed }- if ($FailFast) { throw "FailFast: $name" }-}--function Skip($name, $reason = "") {- $script:SKIP++- $suffix = if ($reason) { " ($reason)" } else { "" }- Write-Host " [SKIP] $name$suffix" -ForegroundColor DarkYellow-}--function Invoke-Api($method, $path, $body = $null, $quiet = $false) {- $uri = "$BASE$path"- $params = @{ Method = $method; Uri = $uri; ContentType = "application/json"; UseBasicParsing = $true }- if ($body) { $params.Body = ($body | ConvertTo-Json -Depth 10) }- try {- $resp = Invoke-WebRequest @params -ErrorAction Stop- return ($resp.Content | ConvertFrom-Json)- } catch {- $code = $_.Exception.Response.StatusCode.value__- try {- $errBody = $_.ErrorDetails.Message | ConvertFrom-Json- if (-not $quiet) { Write-Host " HTTP $code - $($errBody.error)" -ForegroundColor DarkGray }- $errBody | Add-Member -NotePropertyName "__status" -NotePropertyValue $code- return $errBody- } catch {- if (-not $quiet) { Write-Host " HTTP $code - (no JSON body)" -ForegroundColor DarkGray }- $e = [pscustomobject]@{ __status = $code; error = $_.Exception.Message }- return $e- }- }-}--function Navigate($url, $sleepSec = 3) {- $r = Invoke-Api POST "/navigate" @{ url = $url }- if ($r.tabId) {- $script:TAB = $r.tabId- if ($Verbose) { Write-Host " Navigated -> tabId=$($r.tabId)" -ForegroundColor DarkGray }- }- Start-Sleep -Seconds $sleepSec- return $r-}--function Find-Element($query, $extra = @{}) {- $body = @{ query = $query; tabId = $TAB } + $extra- return Invoke-Api POST "/find" $body-}--function Do-Action($ref, $kind = "click", $extra = @{}) {- $body = @{ ref = $ref; kind = $kind; tabId = $TAB } + $extra- return Invoke-Api POST "/action" $body-}--# ----------------------------------------------------------------------------# Preflight-# ----------------------------------------------------------------------------Write-Header "PinchTab Recovery System - Manual Test Suite"-Write-Host " Server : $BASE"-Write-Host " Date : $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"--$health = Invoke-Api GET "/health" -quiet $true-if (-not $health -or $health.__status -ge 400) {- Write-Host ""- Write-Host " ERROR: Server not reachable at $BASE - start PinchTab first." -ForegroundColor Red- exit 1-}-Write-Host " Health : OK" -ForegroundColor Green--# ----------------------------------------------------------------------------# Detect whether a bridge instance is running (dashboard proxies need one)-# ----------------------------------------------------------------------------$HAS_INSTANCE = $false-try {- $instances = Invoke-RestMethod -Uri "$BASE/instances" -UseBasicParsing -ErrorAction SilentlyContinue- if ($instances -and $instances.Count -gt 0) {- $running = $instances | Where-Object { $_.status -eq "running" }- if ($running) { $HAS_INSTANCE = $true }- }-} catch {}-if ($HAS_INSTANCE) {- Write-Host " Instance: running (bridge proxy active)" -ForegroundColor Green-} else {- Write-Host " Instance: none running (Sections 1-2 require a running instance for validation tests)" -ForegroundColor DarkYellow-}--# =============================================================================-# SECTION 1 - /find endpoint enhancements (requires running instance)-# =============================================================================-Write-Header "Section 1: /find Endpoint Enhancements"--if (-not $HAS_INSTANCE) {- Write-Host " No running instance - /find and /macro validation tests require a running bridge instance." -ForegroundColor DarkYellow- Write-Host " Launch a profile from the dashboard, then re-run this test." -ForegroundColor DarkYellow- Skip "Empty query returns 400" "no running instance"- Skip "Whitespace-only query returns 400" "no running instance"- Skip "Tab/newline-only query returns 400" "no running instance"- Skip "Missing query field returns 400" "no running instance"- Skip "Unknown tabId returns 404" "no running instance"- Skip "Malformed JSON body returns 400" "no running instance"- Skip "Non-string query returns 400" "no running instance"- Skip "Negative threshold clamped to 0.3" "no running instance"- Skip "Zero topK clamped to 3" "no running instance"-} else {--# 1.1 Empty query -> 400-Write-Section "1.1 Input Validation"-$r = Invoke-Api POST "/find" @{ query = "" } -quiet $true-if ($r.__status -eq 400) { Pass "Empty query returns 400" }-else { Fail "Empty query should return 400" "got $($r.__status)" }--# 1.2 Whitespace-only query -> 400 (TrimSpace fix)-$r = Invoke-Api POST "/find" @{ query = " " } -quiet $true-if ($r.__status -eq 400) { Pass "Whitespace-only query returns 400 (TrimSpace)" }-else { Fail "Whitespace-only query should return 400" "got $($r.__status)" }--# 1.3 Tab-and-newline whitespace -> 400-$r = Invoke-Api POST "/find" @{ query = "`t`n `r" } -quiet $true-if ($r.__status -eq 400) { Pass "Tab/newline-only query returns 400 (TrimSpace)" }-else { Fail "Tab/newline-only query should return 400" "got $($r.__status)" }--# 1.4 Missing query field entirely -> 400-$r = Invoke-Api POST "/find" @{ tabId = "someTab" } -quiet $true-if ($r.__status -eq 400) { Pass "Missing query field returns 400" }-else { Fail "Missing query field should return 400" "got $($r.__status)" }--# 1.5 Unknown tabId -> 404-$r = Invoke-Api POST "/find" @{ query = "submit button"; tabId = "tab_doesnotexist" } -quiet $true-if ($r.__status -eq 404) { Pass "Unknown tabId returns 404" }-else { Fail "Unknown tabId should return 404" "got $($r.__status)" }--# 1.6 Bad JSON body -> 400-Write-Section "1.2 Bad Request Bodies"-try {- $uri = "$BASE/find"- $resp = Invoke-WebRequest -Method POST -Uri $uri -ContentType "application/json" -Body "{ bad json }" -UseBasicParsing -ErrorAction Stop- Fail "Malformed JSON should return 400" "got $($resp.StatusCode)"-} catch {- $code = $_.Exception.Response.StatusCode.value__- if ($code -eq 400) { Pass "Malformed JSON body returns 400" }- else { Fail "Malformed JSON should return 400" "got $code" }-}--# 1.7 Integer passed for query field -> 400-try {- $uri = "$BASE/find"- $resp = Invoke-WebRequest -Method POST -Uri $uri -ContentType "application/json" -Body '{"query":12345}' -UseBasicParsing -ErrorAction Stop- Fail "Non-string query should not succeed silently"-} catch {- $code = $_.Exception.Response.StatusCode.value__- if ($code -eq 400) { Pass "Non-string query returns 400" }- else { Fail "Non-string query should return 400" "got $code" }-}--# 1.8 Negative threshold -> treated as default (0.3), not an error-Write-Section "1.3 Threshold & TopK Boundary Values"-# These are tested on live pages in Section 3 (Google).-# Here we just verify the server doesn't reject them.-$r = Invoke-Api POST "/find" @{ query = "test"; threshold = -5; topK = 0 } -quiet $true-if (-not $r.__status -or $r.__status -lt 500) { Pass "Negative threshold + zero topK accepted without server error" }-else { Fail "Negative threshold/zero topK should not cause 500" "got $($r.__status)" }--} # end if ($HAS_INSTANCE) for Section 1--# =============================================================================-# SECTION 2 - Recovery System: Edge Cases (requires running instance)-# =============================================================================-Write-Header "Section 2: Recovery Edge Cases"--if (-not $HAS_INSTANCE) {- Write-Host " No running instance - action/batch/macro validation tests require a running bridge instance." -ForegroundColor DarkYellow- Skip "Unknown ref with unknown tab returns 404" "no running instance"- Skip "Missing kind returns 4xx" "no running instance"- Skip "Empty actions array returns 400" "no running instance"- Skip "Empty macro steps returns 400" "no running instance"- Skip "All actions with unknown tab returns 404" "no running instance"-} else {--Write-Section "2.1 Action with unknown ref - triggers 404 before recovery"-# When ref is not in snapshot cache at all, system returns 404 immediately-# (recovery is only attempted when CDP execution fails, not on cache miss)-$r = Invoke-Api POST "/action" @{ kind = "click"; ref = "e99999"; tabId = "tab_fake" } -quiet $true-if ($r.__status -eq 404) { Pass "Unknown ref with unknown tab returns 404" }-else { Fail "Unknown ref + unknown tab should return 404" "got $($r.__status): $($r.error)" }--Write-Section "2.2 Action missing kind -> 400"-$r = Invoke-Api POST "/action" @{ ref = "e1" } -quiet $true-if ($r.__status -ge 400 -and $r.__status -lt 500) { Pass "Missing kind returns 4xx" }-else { Fail "Missing kind should return 4xx" "got $($r.__status)" }--Write-Section "2.3 Batch actions - empty array -> 400"-$r = Invoke-Api POST "/actions" @{ actions = @() } -quiet $true-if ($r.__status -eq 400) { Pass "Empty actions array returns 400" }-else { Fail "Empty actions array should return 400" "got $($r.__status)" }--Write-Section "2.4 Macro - empty steps -> 400"-$r = Invoke-Api POST "/macro" @{ steps = @() } -quiet $true-if ($r.__status -eq 400) { Pass "Empty macro steps returns 400" }-else { Fail "Empty macro steps should return 400" "got $($r.__status)" }--Write-Section "2.5 Batch actions - unknown tabId for all actions"-$r = Invoke-Api POST "/actions" @{- tabId = "tab_ghost"- actions = @(- @{ kind = "click"; ref = "e1" },- @{ kind = "click"; ref = "e2" }- )-} -quiet $true-if ($r.__status -eq 404) { Pass "All actions with unknown tab returns 404" }-else { Fail "Unknown tab for batch should return 404" "got $($r.__status)" }--} # end if ($HAS_INSTANCE) for Section 2--# =============================================================================-# SECTION 3 - Real Websites (requires Chrome + internet)-# =============================================================================-if ($SkipRealSites) {- Write-Header "Section 3-8: Real Website Tests (SKIPPED - use without -SkipRealSites)"- $SKIP += 30-} else {--# =============================================================================-# SECTION 3 - Google.com: Basic /find + explain + weights-# =============================================================================-Write-Header "Section 3: Google.com - /find Enhancements"--Write-Section "3.1 Navigate to Google"-$r = Navigate "https://www.google.com" 3-if ($r.tabId) { Pass "Navigated to Google" }-else { Fail "Navigate to Google failed" "$($r.error)" }--Write-Section "3.2 Exact match - Google Search button"-$r = Find-Element "Google Search button"-if ($r.best_ref -and $r.score -gt 0) {- Pass "Found 'Google Search button' (ref=$($r.best_ref), score=$([math]::Round($r.score,3)), conf=$($r.confidence))"-} else { Fail "Should find Google Search button" "score=$($r.score) ref=$($r.best_ref)" }--Write-Section "3.3 Explain field - lexical vs embedding breakdown"-$r = Find-Element "search input field" @{ explain = $true; topK = 3 }-if ($r.best_ref) {- $hasExplain = $r.matches | Where-Object { $_.explain -ne $null }- if ($hasExplain) { Pass "explain field populated with lexical_score + embedding_score" }- else { Fail "explain field should be present when explain=true" }- if ($Verbose) {- $r.matches | ForEach-Object {- Write-Host " ref=$($_.ref) score=$($_.score) lex=$($_.explain.lexical_score) emb=$($_.explain.embedding_score)" -ForegroundColor DarkGray- }- }-} else { Fail "explain test: should find elements on Google" }--Write-Section "3.4 Per-request weights - lexical-heavy (1.0 / 0.0)"-$r = Find-Element "I'm Feeling Lucky" @{ lexicalWeight = 1.0; embeddingWeight = 0.0; explain = $true }-if ($r.best_ref) {- # All embedding_score should be 0 when embeddingWeight=0- $nonZeroEmb = $r.matches | Where-Object { $_.explain -and $_.explain.embedding_score -ne 0 }- if (-not $nonZeroEmb) { Pass "lexicalWeight=1.0/embeddingWeight=0.0 -> embedding_score=0 in explain" }- else { Fail "embeddingWeight=0 should produce embedding_score=0" }-} else { Fail "Should find elements with lexical-only weights" }--Write-Section "3.5 Per-request weights - embedding-heavy (0.0 / 1.0)"-$r = Find-Element "I'm Feeling Lucky" @{ lexicalWeight = 0.0; embeddingWeight = 1.0; explain = $true }-if ($r.best_ref) {- $nonZeroLex = $r.matches | Where-Object { $_.explain -and $_.explain.lexical_score -ne 0 }- if (-not $nonZeroLex) { Pass "lexicalWeight=0.0/embeddingWeight=1.0 -> lexical_score=0 in explain" }- else { Fail "lexicalWeight=0 should produce lexical_score=0" }-} else { Fail "Should find elements with embedding-only weights" }--Write-Section "3.6 Threshold boundary - topK=1 returns exactly 1 match"-$r = Find-Element "search" @{ topK = 1 }-if ($r.matches.Count -le 1) { Pass "topK=1 returns at most 1 match (got $($r.matches.Count))" }-else { Fail "topK=1 should return at most 1 match" "got $($r.matches.Count)" }--Write-Section "3.7 Very high threshold - returns empty matches"-$r = Find-Element "some obscure query unlikely to match X7Z9" @{ threshold = 0.99 }-if ($r.best_ref -eq "" -or $r.best_ref -eq $null) {- Pass "Threshold=0.99 returns no match for non-existent element"-} else { Fail "Threshold=0.99 should not match low-score elements" "got ref=$($r.best_ref) score=$($r.score)" }--Write-Section "3.8 Low threshold - returns more candidates"-$r = Find-Element "click" @{ threshold = 0.01; topK = 10 }-if ($r.matches.Count -gt 1) { Pass "threshold=0.01 returns multiple matches (got $($r.matches.Count))" }-else { Fail "threshold=0.01 should return many matches" "got $($r.matches.Count)" }--Write-Section "3.9 Response structure validation"-$r = Find-Element "Google Search"-$fields = @("best_ref","confidence","score","matches","strategy","threshold","latency_ms","element_count")-$missing = $fields | Where-Object { $r.PSObject.Properties.Name -notcontains $_ }-if ($missing) { Fail "Response missing fields: $($missing -join ', ')" }-else { Pass "All expected fields present in /find response" }-if ($r.latency_ms -ge 0) { Pass "latency_ms is non-negative ($($r.latency_ms)ms)" }-else { Fail "latency_ms should be >= 0" }-if ($r.element_count -gt 0) { Pass "element_count > 0 ($($r.element_count) elements)" }-else { Fail "element_count should be > 0" }--Write-Section "3.10 TrimSpace - leading/trailing whitespace stripped"-$r1 = Find-Element "Google Search"-$r2 = Find-Element " Google Search "-$r3 = Find-Element "`t`tGoogle Search`n"-if ($r1.best_ref -and $r1.best_ref -eq $r2.best_ref -and $r2.best_ref -eq $r3.best_ref) {- Pass "TrimSpace: queries with leading/trailing whitespace return same result"-} else {- Fail "TrimSpace: trimmed queries should produce equal results" "r1=$($r1.best_ref) r2=$($r2.best_ref) r3=$($r3.best_ref)"-}--# =============================================================================-# SECTION 4 - Google.com: Recovery Simulation (Stale Ref)-# =============================================================================-Write-Header "Section 4: Google.com - Stale-Ref Recovery Simulation"-Write-Host " NOTE: Recovery is triggered by navigating to the SAME page after" -ForegroundColor DarkCyan-Write-Host " caching intent via /find. The second navigate resets Chrome's" -ForegroundColor DarkCyan-Write-Host " nodeIDs but our snapshot cache still holds OLD refs -> stale." -ForegroundColor DarkCyan--Write-Section "4.1 Cache intent for Google Search button via /find"-$r = Find-Element "Google Search button"-$googleSearchRef = $r.best_ref-if ($googleSearchRef) {- Pass "Intent cached: ref=$googleSearchRef (score=$([math]::Round($r.score,3)))"-} else {- Skip "4.2-4.4 (could not find Google Search button)" "skipping recovery tests"- $googleSearchRef = $null-}--if ($googleSearchRef) {- Write-Section "4.2 Reload page - Chrome assigns new nodeIDs (snapshot cache now stale)"- # Reload by navigating to the same URL - Chrome rebuilds the DOM- Invoke-Api POST "/navigate" @{ url = "https://www.google.com"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2- Pass "Page reloaded - old snapshot refs are now stale"-- Write-Section "4.3 Click old ref WITHOUT refreshing snapshot (triggers recovery)"- # DO NOT call /snapshot - use old snapshot so nodeID is stale- $r = Do-Action $googleSearchRef "click"- if ($r.success -eq $true) {- if ($r.recovery -and $r.recovery.recovered -eq $true) {- Pass "RECOVERY TRIGGERED: action succeeded via semantic re-match"- Pass " original_ref=$($r.recovery.original_ref) -> new_ref=$($r.recovery.new_ref)"- Pass " confidence=$($r.recovery.confidence) score=$([math]::Round($r.recovery.score,3)) latency=$($r.recovery.latency_ms)ms"- } else {- # nodeID was still valid (Chrome sometimes keeps IDs across soft reload)- Pass "Action succeeded without recovery (nodeID still valid - soft reload)"- }- } else {- # Recovery attempted but failed, or ref was not in cache- if ($r.recovery) {- Fail "Recovery attempted but could not heal" "error=$($r.recovery.error)"- } else {- Fail "Action failed and no recovery attempted" "error=$($r.error)"- }- }-- Write-Section "4.4 Verify recovery response structure"- # Do another find + stale-ref click to inspect response shape- $r2 = Find-Element "I'm Feeling Lucky button"- $luckyRef = $r2.best_ref- if ($luckyRef) {- Invoke-Api POST "/navigate" @{ url = "https://www.google.com"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2- $r3 = Do-Action $luckyRef "click"- if ($r3.recovery -ne $null) {- $rfields = @("recovered","original_ref","failure_type","attempts","latency_ms")- $rmissing = $rfields | Where-Object { $r3.recovery.PSObject.Properties.Name -notcontains $_ }- if ($rmissing) { Fail "Recovery object missing fields: $($rmissing -join ', ')" }- else { Pass "Recovery response contains all expected fields" }- if ($r3.recovery.attempts -ge 1) { Pass "attempts >= 1 ($($r3.recovery.attempts))" }- else { Fail "attempts should be >= 1" }- if ($r3.recovery.latency_ms -ge 0) { Pass "recovery.latency_ms >= 0 ($($r3.recovery.latency_ms)ms)" }- else { Fail "recovery.latency_ms should be >= 0" }- } else {- Skip "Recovery response structure" "action did not trigger recovery (nodeID still valid)"- }- } else {- Skip "4.4 recovery structure" "could not find Feeling Lucky button"- }-}--# =============================================================================-# SECTION 5 - GitHub.com: Login page stale-ref recovery-# =============================================================================-Write-Header "Section 5: GitHub.com - Login Form Recovery"--Write-Section "5.1 Navigate to GitHub login"-$r = Navigate "https://github.com/login" 3-if ($r.tabId) { Pass "Navigated to GitHub login" }-else { Fail "Navigate to GitHub login failed" "$($r.error)" }--Write-Section "5.2 Find password field"-$passFind = Find-Element "password input"-if ($passFind.best_ref) {- Pass "Found password field (ref=$($passFind.best_ref), conf=$($passFind.confidence))"-} else { Fail "Should find password field on GitHub login" }--Write-Section "5.3 Find Sign In button"-$signinFind = Find-Element "sign in button"-$signinRef = $signinFind.best_ref-if ($signinRef) {- Pass "Found Sign In button (ref=$signinRef, score=$([math]::Round($signinFind.score,3)))"-} else {- Fail "Should find Sign In button on GitHub"- $signinRef = $null-}--Write-Section "5.4 Find username field"-$userFind = Find-Element "username or email field"-if ($userFind.best_ref) {- Pass "Found username/email field (ref=$($userFind.best_ref))"-} else { Fail "Should find username field on GitHub" }--Write-Section "5.5 Reload page to make refs stale, then recover Sign In click"-if ($signinRef) {- Invoke-Api POST "/navigate" @{ url = "https://github.com/login"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2- Pass "GitHub login page reloaded - old refs are stale"-- $r = Do-Action $signinRef "click"- if ($r.success -eq $true) {- if ($r.recovery -and $r.recovery.recovered) {- Pass "RECOVERY: GitHub Sign In button re-found after DOM rebuild"- Pass " new_ref=$($r.recovery.new_ref) confidence=$($r.recovery.confidence)"- } else {- Pass "Click succeeded (nodeID still valid - no full rebuild)"- }- } else {- if ($r.recovery) {- Skip "Sign In recovery" "recovery attempted but failed (may need credentials - action correct)"- } else {- Fail "Sign In action failed without recovery attempt" "$($r.error)"- }- }-} else {- Skip "5.5 stale-ref recovery" "Sign In ref not found in 5.3"-}--Write-Section "5.6 Explain + weights on login form"-$r = Find-Element "Sign in with passkey" @{ explain = $true; topK = 5; lexicalWeight = 0.7; embeddingWeight = 0.3 }-if ($r.best_ref) {- Pass "Custom weights (0.7/0.3) returned result on GitHub login"- $withExplain = $r.matches | Where-Object { $_.explain -ne $null }- if ($withExplain) { Pass "explain field present with custom weights" }- else { Fail "explain field missing with explain=true" }-} else { Pass "No match above threshold - acceptable for 'passkey' on this page" }--# =============================================================================-# SECTION 6 - Wikipedia: Text/link elements + edge-case queries-# =============================================================================-Write-Header "Section 6: Wikipedia - Edge-Case Queries"--Write-Section "6.1 Navigate to Wikipedia"-$r = Navigate "https://en.wikipedia.org/wiki/React_(JavaScript_library)" 3-if ($r.tabId) { Pass "Navigated to Wikipedia (React article)" }-else { Fail "Navigate to Wikipedia failed" "$($r.error)" }--Write-Section "6.2 Long query - sentence-length natural language"-$longQ = "click the link that takes me to the contents table of this article"-$r = Find-Element $longQ @{ topK = 5 }-if ($r.best_ref -and $r.score -gt 0) {- Pass "Long sentence query returned a result (ref=$($r.best_ref), score=$([math]::Round($r.score,3)))"-} else { Fail "Long query should find at least one element" }--Write-Section "6.3 Single word query"-$r = Find-Element "history"-if ($r.best_ref) { Pass "Single word query 'history' returned ref=$($r.best_ref)" }-else { Fail "Single word query should return a result" }--Write-Section "6.4 Emoji in query - should not crash, graceful result"-$r = Find-Element "search [magnify] button"-# Not crashing is the main goal; match is a bonus-Pass "Emoji in query did not crash server (status=$($r.__status), ref=$($r.best_ref))"--Write-Section "6.5 Very long query (>200 chars)"-$veryLong = ("the button that will " * 15).TrimEnd()-$r = Find-Element $veryLong-Pass "300-char query did not crash server (ref=$($r.best_ref))"--Write-Section "6.6 Special-character query - SQL injection pattern (should be safe)"-$r = Find-Element "'; DROP TABLE elements; --"-if (-not $r.__status -or $r.__status -lt 500) {- Pass "SQL-injection-pattern query handled safely"-} else { Fail "Server should not 500 on special-char query" "status=$($r.__status)" }--Write-Section "6.7 Unicode query - Arabic script"-$r = Find-Element "search button in Arabic" # "search button" in Arabic-Pass "Arabic-script query handled gracefully (ref=$($r.best_ref))"--Write-Section "6.8 Batch /find via multiple calls - concurrent intent caching"-$queries = @("search box","logo image","login button","navigation menu","footer link")-$refs = @()-foreach ($q in $queries) {- $rq = Find-Element $q- if ($rq.best_ref) { $refs += $rq.best_ref }-}-if ($refs.Count -ge 2) { Pass "Multiple /find calls succeed concurrently ($($refs.Count) intents cached)" }-else { Fail "Should cache multiple intents" "only $($refs.Count) found" }--# =============================================================================-# SECTION 7 - Batch Actions + Macro Recovery Tests-# =============================================================================-Write-Header "Section 7: Batch /actions + /macro Recovery"--Write-Section "7.1 Navigate to example.com"-$r = Navigate "https://example.com" 2-if ($r.tabId) { Pass "Navigated to example.com" }-else { Fail "Navigate to example.com failed" }--Write-Section "7.2 Find elements for batch test"-$linkFind = Find-Element "more information link"-$linkRef = $linkFind.best_ref-if ($linkRef) { Pass "Found 'More information' link (ref=$linkRef)" }-else { Fail "Should find a link on example.com" }--Write-Section "7.3 Batch actions - mixed valid/invalid refs (stopOnError=false)"-$r = Invoke-Api POST "/actions" @{- tabId = $TAB- stopOnError = $false- actions = @(- @{ kind = "click"; ref = "e99998" }, # nonexistent ref -> 404 item- @{ kind = "click"; ref = "e99999" } # nonexistent ref -> 404 item- )-}-if ($r.results) {- $failures = $r.results | Where-Object { $_.success -eq $false }- if ($failures.Count -eq 2) { Pass "Batch: both invalid refs fail gracefully (stopOnError=false)" }- else { Fail "Expected 2 failures in batch" "got $($failures.Count)" }- if ($r.failed -eq 2) { Pass "Batch summary: failed=2 correct" }- else { Fail "Batch summary.failed should be 2" "got $($r.failed)" }-} else { Fail "Batch response should have results array" }--Write-Section "7.4 Batch actions - stopOnError=true stops at first failure"-$r = Invoke-Api POST "/actions" @{- tabId = $TAB- stopOnError = $true- actions = @(- @{ kind = "click"; ref = "e99997" }, # will fail -> should stop- @{ kind = "click"; ref = "e99996" } # should never run- )-}-if ($r.results -and $r.results.Count -le 1) {- Pass "stopOnError=true stops after first failure (processed $($r.results.Count) action(s))"-} else { Fail "stopOnError=true should stop after first failure" }--Write-Section "7.5 Batch actions - stale-ref recovery in batch"-if ($linkRef) {- # Reload page to stale refs- Invoke-Api POST "/navigate" @{ url = "https://example.com"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2-- $r = Invoke-Api POST "/actions" @{- tabId = $TAB- stopOnError = $false- actions = @(- @{ kind = "click"; ref = $linkRef } # stale ref - recovery should kick in- )- }- if ($r.results -and $r.results.Count -ge 1) {- $a1 = $r.results[0]- if ($a1.success) { Pass "Batch: action item succeeded (with or without recovery)" }- else { Fail "Batch: stale-ref action failed" "$($a1.error)" }- } else { Fail "Batch response missing results" }-}-else { Skip "7.5 batch stale-ref recovery" "link ref not found in 7.2" }--Write-Section "7.6 Macro - steps with invalid refs (stopOnError=false)"-$r = Invoke-Api POST "/macro" @{- tabId = $TAB- stopOnError = $false- steps = @(- @{ kind = "click"; ref = "e99994"; tabId = $TAB },- @{ kind = "click"; ref = "e99993"; tabId = $TAB }- )-}-if ($r.kind -eq "macro" -and $r.results) {- Pass "Macro returns kind='macro' with results array"- if ($r.failed -ge 1) { Pass "Macro correctly reports failures (failed=$($r.failed))" }- else { Fail "Macro should report failed count" "failed=$($r.failed)" }-} else { Fail "Macro response should have kind='macro' and results" }--Write-Section "7.7 Macro - zero steps -> 400"-$r = Invoke-Api POST "/macro" @{ steps = @() } -quiet $true-if ($r.__status -eq 400) { Pass "Macro with empty steps returns 400" }-else { Fail "Empty macro steps should return 400" "got $($r.__status)" }--Write-Section "7.8 Macro - stale-ref recovery"-$r = Navigate "https://example.com" 2-$moreInfoFind = Find-Element "more information"-$moreInfoRef = $moreInfoFind.best_ref-if ($moreInfoRef) {- Invoke-Api POST "/navigate" @{ url = "https://example.com"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2-- $r = Invoke-Api POST "/macro" @{- tabId = $TAB- stopOnError = $false- steps = @( @{ kind = "click"; ref = $moreInfoRef; tabId = $TAB } )- }- if ($r.results -and $r.results[0].success) {- Pass "Macro: stale-ref step succeeded (recovery may have helped)"- } else {- if ($r.results) { Fail "Macro step failed" "$($r.results[0].error)" }- else { Fail "Macro returned no results" }- }-}-else { Skip "7.8 macro stale-ref" "more-info link ref not found" }--# =============================================================================-# SECTION 8 - E-commerce + SPA: Realistic Recovery Scenarios-# =============================================================================-Write-Header "Section 8: Realistic Recovery Scenarios"--# --- 8.1 : Hacker News - dynamic voting buttons-Write-Section "8.1 Hacker News - voting arrows (SPA-like interaction)"-$r = Navigate "https://news.ycombinator.com" 3-if ($r.tabId) {- Pass "Navigated to Hacker News"-- $upvoteFind = Find-Element "upvote button"- if ($upvoteFind.best_ref) {- Pass "Found upvote element (ref=$($upvoteFind.best_ref), conf=$($upvoteFind.confidence))"- } else {- Pass "No labeled upvote button (aria-label may be absent) - element_count=$($upvoteFind.element_count)"- }-- $moreFind = Find-Element "more link"- if ($moreFind.best_ref) {- Pass "Found 'more' link on HN (ref=$($moreFind.best_ref))"- } else { Fail "Should find 'more' pagination link on Hacker News" }-} else { Fail "Navigate to HN failed" }--# --- 8.2 : Wikipedia login page - two-step form simulation-Write-Section "8.2 Wikipedia login form - find then stale-ref recovery"-$r = Navigate "https://en.wikipedia.org/w/index.php?title=Special:UserLogin" 3-if ($r.tabId) {- Pass "Navigated to Wikipedia login"-- $wikiUser = Find-Element "username input"- $wikiPass = Find-Element "password field"- $wikiBtn = Find-Element "log in button"-- if ($wikiUser.best_ref -and $wikiPass.best_ref -and $wikiBtn.best_ref) {- Pass "Found all 3 login form elements: username, password, login button"- $loginRef = $wikiBtn.best_ref-- # Reload to stale refs- Invoke-Api POST "/navigate" @{ url = "https://en.wikipedia.org/w/index.php?title=Special:UserLogin"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2-- $r2 = Do-Action $loginRef "click"- if ($r2.success -or ($r2.recovery -ne $null)) {- Pass "Wikipedia Login click: action executed (recovery=$($r2.recovery -ne $null))"- } else {- Fail "Wikipedia login button action failed" "$($r2.error)"- }- } else {- Fail "Expected username+password+button on Wikipedia login"- }-} else { Fail "Navigate to Wikipedia login failed" }--# --- 8.3 : DuckDuckGo - search box + button recovery-Write-Section "8.3 DuckDuckGo - search form recovery"-$r = Navigate "https://duckduckgo.com" 3-if ($r.tabId) {- Pass "Navigated to DuckDuckGo"-- $ddgSearch = Find-Element "search input box"- $ddgBtn = Find-Element "search button"- if ($ddgSearch.best_ref -and $ddgBtn.best_ref) {- Pass "Found search input (ref=$($ddgSearch.best_ref)) + button (ref=$($ddgBtn.best_ref))"- $ddgBtnRef = $ddgBtn.best_ref-- # Reload + stale ref- Invoke-Api POST "/navigate" @{ url = "https://duckduckgo.com"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2-- $r2 = Do-Action $ddgBtnRef "click"- if ($r2.success -or $r2.recovery -ne $null) {- Pass "DuckDuckGo search button click handled (recovery=$($r2.recovery -ne $null))"- } else {- Fail "DuckDuckGo search button action failed" "$($r2.error)"- }- } else {- Pass "Search box found=$($ddgSearch.best_ref -ne '') btn found=$($ddgBtn.best_ref -ne '') - minimal DDG markup is normal"- }-} else { Fail "Navigate to DuckDuckGo failed" }--# --- 8.4 : GitHub repo page - star button (common agent use-case)-Write-Section "8.4 GitHub pinchtab repo - Star button recovery"-$r = Navigate "https://github.com/pinchtab/pinchtab" 3-if ($r.tabId) {- Pass "Navigated to GitHub pinchtab repo"-- $starFind = Find-Element "Star this repository button"- if ($starFind.best_ref) {- Pass "Found Star button (ref=$($starFind.best_ref), score=$([math]::Round($starFind.score,3)))"- $starRef = $starFind.best_ref-- Invoke-Api POST "/navigate" @{ url = "https://github.com/pinchtab/pinchtab"; tabId = $TAB } | Out-Null- Start-Sleep -Seconds 2-- $r2 = Do-Action $starRef "click"- if ($r2.success -or $r2.recovery -ne $null) {- Pass "GitHub Star button action executed after reload (recovery=$($r2.recovery -ne $null))"- } else {- Skip "Star button click failed - likely needs authentication" "expected for unauthenticated user"- }- } else {- Pass "Star button not accessible (normal when unauthenticated) - score=$($starFind.score)"- }-} else { Fail "Navigate to GitHub repo failed" }--# --- 8.5 : MDN Web Docs - navigation menu (large, complex DOM)-Write-Section "8.5 MDN Web Docs - complex DOM navigation"-$r = Navigate "https://developer.mozilla.org/en-US/docs/Web/JavaScript" 4-if ($r.tabId) {- Pass "Navigated to MDN JavaScript docs"-- $menuFind = Find-Element "open navigation menu"- if ($menuFind.best_ref) {- Pass "Found navigation menu (ref=$($menuFind.best_ref), conf=$($menuFind.confidence), elements=$($menuFind.element_count))"- } else {- $anyFind = Find-Element "search documentation"- if ($anyFind.best_ref) { Pass "Found search on MDN (ref=$($anyFind.best_ref))" }- else { Fail "Should find navigation or search on MDN" }- }-- # Test explain on a complex page- $r2 = Find-Element "feedback button" @{ explain = $true; topK = 5 }- $hasExplain = $r2.matches | Where-Object { $_.explain -ne $null }- if ($hasExplain) { Pass "explain field populated on large-DOM page (MDN)" }- else { Pass "No match above threshold on MDN - explain not triggered (acceptable)" }-} else { Fail "Navigate to MDN failed" }--} # end if -not $SkipRealSites--# =============================================================================-# SECTION 9 - Recovery Response Contract (Structure Enforcement)-# =============================================================================-Write-Header "Section 9: Recovery Response Contract"--Write-Section "9.1 recovery field is absent when no recovery was tried"-# When ref resolves correctly (fresh snapshot + fresh action), no recovery block-if ($TAB) {- $r = Navigate "https://example.com" 2- $lf = Find-Element "more information"- if ($lf.best_ref) {- $r2 = Do-Action $lf.best_ref "click"- if ($r2.success -and -not $r2.recovery) {- Pass "recovery field absent in response when no recovery needed"- } elseif ($r2.success -and $r2.recovery) {- Pass "recovery field present but not null - recovery was attempted (also valid)"- } else {- Fail "Action failed on fresh ref" "$($r2.error)"- }- } else { Skip "9.1" "no link found on example.com" }-} else { Skip "9.1" "no active tab" }--Write-Section "9.2 /find response: score is float in [0,1]"-if ($TAB) {- $r = Navigate "https://example.com" 2- $r2 = Find-Element "example" @{ topK = 3; threshold = 0.01 }- $badScore = $r2.matches | Where-Object { $_.score -lt 0 -or $_.score -gt 1 }- if ($badScore) { Fail "Scores out of [0,1] range: $($badScore.score -join ', ')" }- else { Pass "/find scores all within [0, 1] range" }-} else { Skip "9.2" "no active tab" }--Write-Section "9.3 strategy field is non-empty"-if ($TAB) {- $r2 = Find-Element "link"- if ($r2.strategy -and $r2.strategy.Length -gt 0) {- Pass "strategy field non-empty: '$($r2.strategy)'"- } else { Fail "strategy field should be non-empty" }-} else { Skip "9.3" "no active tab" }--Write-Section "9.4 matches array always present (even on no-result query)"-if ($TAB) {- $r2 = Find-Element "ZQ97XNOBODYWILLFINDTHIS" @{ threshold = 0.99 }- if ($r2.PSObject.Properties.Name -contains "matches") {- Pass "matches is present even when empty (count=$($r2.matches.Count))"- } else { Fail "matches array should always be present" }-} else { Skip "9.4" "no active tab" }--# =============================================================================-# SUMMARY-# =============================================================================-Write-Host ""-Write-Host ("=" * 72) -ForegroundColor Cyan-Write-Host " TEST SUMMARY" -ForegroundColor Cyan-Write-Host ("=" * 72) -ForegroundColor Cyan-Write-Host ""-Write-Host (" Total: " + ($PASS + $FAIL + $SKIP))-Write-Host (" PASS : $PASS") -ForegroundColor Green-if ($FAIL -gt 0) {- Write-Host (" FAIL : $FAIL") -ForegroundColor Red-} else {- Write-Host (" FAIL : $FAIL") -ForegroundColor Green-}-Write-Host (" SKIP : $SKIP") -ForegroundColor DarkYellow-Write-Host ""--if ($FAIL -gt 0) {- Write-Host " Result: FAILED ($FAIL test(s) failed)" -ForegroundColor Red- exit 1-} else {- Write-Host " Result: PASSED" -ForegroundColor Green- exit 0-}diff --git a/tests/performance/speed.md b/tests/performance/speed.mddeleted file mode 100644index 1f56f0da..00000000--- a/tests/performance/speed.md+++ /dev/null@@ -1,147 +0,0 @@-# Speed Performance Testing--**Goal:** Measure and track endpoint latency so we know where Pinchtab is fast, where it's slow, and whether regressions creep in.-------## Methodology--### How to Measure--Use `curl` timing or the benchmark script below. All times in milliseconds.--```bash-# Single endpoint timing-curl -o /dev/null -s -w "%{time_total}" localhost:9867/snapshot | awk '{printf "%.0fms\n", $1*1000}'--# With breakdown (DNS, connect, TTFB, total)-curl -o /dev/null -s -w "connect:%{time_connect}s ttfb:%{time_starttransfer}s total:%{time_total}s\n" localhost:9867/snapshot-```--### What to Measure--| Endpoint | Notes |-|----------|-------|-| `GET /health` | Baseline β should be < 1ms |-| `GET /snapshot` | Primary interface β most latency-sensitive |-| `GET /snapshot?filter=interactive` | Should be similar to full snapshot |-| `GET /snapshot?format=text` | Formatting overhead |-| `GET /text` | Includes readability extraction time |-| `GET /screenshot` | Render + encode time |-| `GET /screenshot?raw=true` | Without base64 |-| `POST /action {"kind":"click","ref":"eN"}` | Action execution time |-| `POST /navigate {"url":"..."}` | Includes page load wait |-| `GET /tabs` | Should be instant |-| `GET /cookies` | CDP call overhead |--### Test Conditions--Always document:-- **Headless vs headed** (headless is typically faster)-- **Page state** (what's loaded when measuring snapshot/text)-- **Machine specs** (CPU, RAM, OS)-- **Chrome version**-- **Number of open tabs** (affects memory pressure)-------## Benchmark Script--```bash-#!/bin/bash-# speed-benchmark.sh β Measure endpoint latency-# Usage: ./speed-benchmark.sh [port] [iterations]--PORT=${1:-9867}-ITERS=${2:-10}-BASE="http://localhost:$PORT"--echo "Pinchtab Speed Benchmark β $ITERS iterations per endpoint"-echo "Port: $PORT"-echo ""--# Navigate to a standard page first-curl -s -X POST "$BASE/navigate" -d '{"url":"https://example.com"}' > /dev/null-sleep 2--endpoints=(- "GET /health"- "GET /tabs"- "GET /snapshot"- "GET /snapshot?filter=interactive"- "GET /snapshot?format=text"- "GET /text"- "GET /screenshot?raw=true"-)--echo "| Endpoint | Min | Avg | Max | P95 |"-echo "|----------|-----|-----|-----|-----|"--for ep in "${endpoints[@]}"; do- method=$(echo "$ep" | cut -d' ' -f1)- path=$(echo "$ep" | cut -d' ' -f2)-- times=()- for i in $(seq 1 $ITERS); do- ms=$(curl -o /dev/null -s -w "%{time_total}" "$BASE$path" | awk '{printf "%.0f", $1*1000}')- times+=("$ms")- done-- # Sort and compute stats- sorted=($(printf '%s\n' "${times[@]}" | sort -n))- min=${sorted[0]}- max=${sorted[-1]}- sum=0; for t in "${times[@]}"; do sum=$((sum + t)); done- avg=$((sum / ITERS))- p95_idx=$(( (ITERS * 95 / 100) - 1 ))- [ $p95_idx -lt 0 ] && p95_idx=0- p95=${sorted[$p95_idx]}-- echo "| $path | ${min}ms | ${avg}ms | ${max}ms | ${p95}ms |"-done--# Action timing (needs a ref from snapshot)-echo ""-echo "Action timing (click on example.com link):"-ref=$(curl -s "$BASE/snapshot?filter=interactive" | python3 -c "import sys,json; nodes=json.load(sys.stdin).get('nodes',[]); print(nodes[0]['ref'] if nodes else 'e0')" 2>/dev/null || echo "e0")-for i in $(seq 1 $ITERS); do- ms=$(curl -o /dev/null -s -w "%{time_total}" -X POST "$BASE/action" -d "{\"kind\":\"click\",\"ref\":\"$ref\"}" | awk '{printf "%.0f", $1*1000}')- echo " click: ${ms}ms"-done-```-------## Baseline Expectations--From previous benchmarks (v0.2.0, headless, MacBook Pro M-series):--| Endpoint | Expected Latency |-|----------|-----------------|-| `/health` | < 1ms |-| `/tabs` | < 5ms |-| `/snapshot` | 20-30ms |-| `/snapshot?filter=interactive` | 20-30ms |-| `/text` | 5-10ms |-| `/screenshot` | 150-250ms |-| `/action` (click) | 5-10ms |-| `/navigate` | 1-5s (page load dependent) |--### Regression Thresholds--Flag a regression if any endpoint is **> 2x** the baseline for the same page/conditions.-------## Performance Targets--| Metric | Target |-|--------|--------|-| Snapshot latency (simple page) | < 50ms |-| Snapshot latency (complex page) | < 200ms |-| Text extraction | < 50ms |-| Screenshot | < 300ms |-| Action (click/type) | < 20ms |-| Startup to first request | < 5s |-| Memory (idle, 1 tab) | < 200MB |-| Memory (3 tabs, active) | < 500MB |diff --git a/tests/performance/tokens.md b/tests/performance/tokens.mddeleted file mode 100644index 3f61a63b..00000000--- a/tests/performance/tokens.md+++ /dev/null@@ -1,120 +0,0 @@-# Token Performance Testing--**Goal:** Measure and track how many LLM tokens Pinchtab endpoints consume per page, so we can optimize for cost.-------## Methodology--### How to Measure Tokens--Tokens β bytes / 4 (rough estimate for English text). For precise counts, pipe output through a tokenizer (e.g. `tiktoken` for OpenAI, or just use byte count / 4).--```bash-# Measure snapshot tokens (approximate)-curl -s localhost:9867/snapshot | wc -c | awk '{print int($1/4)" tokens"}'--# Measure text tokens-curl -s localhost:9867/text | wc -c | awk '{print int($1/4)" tokens"}'--# Measure interactive-only snapshot-curl -s "localhost:9867/snapshot?filter=interactive" | wc -c | awk '{print int($1/4)" tokens"}'--# Measure text format snapshot-curl -s "localhost:9867/snapshot?format=text" | wc -c | awk '{print int($1/4)" tokens"}'-```--### Test Sites (standard set)--Use these consistently across versions for comparable results:--| Site | Type | Why |-|------|------|-----|-| `https://example.com` | Minimal static | Baseline / sanity check |-| `https://www.google.com` | Search engine | Common use case, forms |-| `https://github.com` | Web app | Auth, dynamic content |-| `https://www.bbc.co.uk` | News site | Heavy content, lots of nav |-| `https://en.wikipedia.org/wiki/Go_(programming_language)` | Reference | Long-form content |-| `https://news.ycombinator.com` | Link list | Repetitive structure |-| `https://x.com` | SPA | Client-rendered, auth-gated |--### Endpoints to Measure--For each site, record tokens for:--| Endpoint | What it measures |-|----------|-----------------|-| `GET /snapshot` | Full accessibility tree (JSON) |-| `GET /snapshot?filter=interactive` | Interactive elements only |-| `GET /snapshot?format=text` | Text format (indented tree) |-| `GET /text` | Readability extraction |-| `GET /text?mode=raw` | Raw innerText |-------## Test Script--```bash-#!/bin/bash-# token-benchmark.sh β Run against a live Pinchtab instance-# Usage: ./token-benchmark.sh [port]--PORT=${1:-9867}-BASE="http://localhost:$PORT"--SITES=(- "https://example.com"- "https://www.google.com"- "https://github.com"- "https://www.bbc.co.uk"- "https://en.wikipedia.org/wiki/Go_(programming_language)"- "https://news.ycombinator.com"-)--echo "| Site | /snapshot | ?filter=interactive | ?format=text | /text | /text?mode=raw |"-echo "|------|----------|---------------------|-------------|-------|----------------|"--for site in "${SITES[@]}"; do- # Navigate- curl -s -X POST "$BASE/navigate" -d "{\"url\":\"$site\"}" > /dev/null- sleep 3-- # Measure each endpoint- snap=$(curl -s "$BASE/snapshot" | wc -c | awk '{print int($1/4)}')- interactive=$(curl -s "$BASE/snapshot?filter=interactive" | wc -c | awk '{print int($1/4)}')- text_fmt=$(curl -s "$BASE/snapshot?format=text" | wc -c | awk '{print int($1/4)}')- text=$(curl -s "$BASE/text" | wc -c | awk '{print int($1/4)}')- raw=$(curl -s "$BASE/text?mode=raw" | wc -c | awk '{print int($1/4)}')-- name=$(echo "$site" | sed 's|https://||' | sed 's|www.||' | cut -d'/' -f1)- echo "| $name | ~${snap} | ~${interactive} | ~${text_fmt} | ~${text} | ~${raw} |"-done-```-------## What to Track Per Version--For each release, record:--1. **Token counts per endpoint per site** (the table above)-2. **Comparison vs previous version** (regression or improvement)-3. **Snapshot JSON node count** β `curl -s /snapshot | jq '.nodes | length'`-4. **Text format vs JSON ratio** β how much cheaper is `?format=text`-------## Optimization Targets--| Metric | Current (v0.3.0) | Target |-|--------|-------------------|--------|-| `/text` on news site | ~3,500 tokens | < 3,000 |-| `/snapshot` vs OpenClaw aria | 3-4x larger | < 2x larger |-| `?filter=interactive` vs full | ~60-75% reduction | maintain |-| `?format=text` vs JSON | ~40-60% reduction | maintain |--### Known Optimization Opportunities--- **Snapshot JSON is verbose** β each node has full property objects. A compact format could halve tokens.-- **`/text` on content-heavy sites** β readability extraction is good but still includes some boilerplate.-- **`?format=text` indentation** β uses spaces; could use minimal indentation to save bytes.diff --git a/tests/performance/v0.4.0-token-performance.md b/tests/performance/v0.4.0-token-performance.mddeleted file mode 100644index 3b52ef51..00000000--- a/tests/performance/v0.4.0-token-performance.md+++ /dev/null@@ -1,62 +0,0 @@-# Token Performance β v0.4.0 (autorun branch)--**Date:** 2026-02-17 08:52 UTC-**Run by:** Mario (manual)-**Instance:** headless, clean profile, BRIDGE_NO_RESTORE=true-------## Results--| Site | /snapshot | ?filter=interactive | ?format=text | /text | /text?mode=raw | Nodes |-|------|----------|---------------------|-------------|-------|----------------|-------|-| example.com | ~187 | ~36 | ~100 | ~47 | ~49 | 8 |-| google.com | ~1,938 | ~564 | ~1,292 | ~764 | ~407 | 87 |-| github.com | ~9,835 | ~2,160 | ~7,189 | ~1,249 | ~1,570 | 445 |-| bbc.co.uk | ~23,112 | ~4,848 | ~19,706 | ~3,118 | ~3,621 | 996 |-| wikipedia (Go) | ~142,154 | ~20,246 | ~97,637 | ~15,676 | ~15,058 | 7,090 |-| news.ycombinator.com | ~18,643 | ~4,287 | ~12,062 | ~971 | ~1,076 | 966 |--## Reduction Ratios--| Site | interactive vs full | text fmt vs full | /text vs full |-|------|-------------------|-----------------|--------------|-| example.com | -81% | -47% | -75% |-| google.com | -71% | -33% | -61% |-| github.com | -78% | -27% | -87% |-| bbc.co.uk | -79% | -15% | -87% |-| wikipedia | -86% | -31% | -89% |-| HN | -77% | -35% | -95% |--## Analysis--- **`?filter=interactive`** is the best option for agents that need to interact β 71-86% reduction across all sites-- **`/text`** is cheapest for content reading β 61-95% reduction, ideal for scraping/reading-- **`?format=text`** underperforms β only 15-47% reduction vs JSON, not worth the tradeoff-- **Wikipedia is an outlier** β 142K tokens / 7,090 nodes; needs `maxTokens` or `selector` to be usable-- **HN shows ideal `/text` efficiency** β 971 tokens for a full page of links--## Cost Estimates (Claude Sonnet, $3/M input)--| Site | Full snapshot | Interactive | /text |-|------|-------------|-------------|-------|-| example.com | $0.001 | $0.000 | $0.000 |-| google.com | $0.006 | $0.002 | $0.002 |-| github.com | $0.030 | $0.006 | $0.004 |-| bbc.co.uk | $0.069 | $0.015 | $0.009 |-| wikipedia | $0.427 | $0.061 | $0.047 |-| HN | $0.056 | $0.013 | $0.003 |--## Optimization Opportunities--1. **`maxTokens` param** β Truncate snapshot at N tokens. Biggest win for large pages.-2. **`selector` param** β Scope a11y tree to CSS selector (`#content`, `article`). Eliminates nav/footer noise.-3. **`exclude` patterns** β Auto-strip nav, footer, cookie banners. Sensible defaults.-4. **Compact JSON format** β Current nodes are verbose objects. A flat format could halve tokens.-5. **Viewport scoping** β Only return visible nodes. Below-fold content usually irrelevant.--## Methodology--- Tokens β bytes / 4 (rough estimate for English text)-- Each site navigated fresh, 4s wait before measurement-- All endpoints measured sequentially on same page loaddiff --git a/tests/token-efficiency-corriere.md b/tests/token-efficiency-corriere.mddeleted file mode 100644index 9aa99d82..00000000--- a/tests/token-efficiency-corriere.md+++ /dev/null@@ -1,228 +0,0 @@-# Token Efficiency Test: Corriere.it News Extraction--**Goal:** Extract news titles from corriere.it homepage and measure token cost efficiency.--**Test Date:** [Run date]-**Tester:** [Agent name]-**Environment:** Pinchtab running on localhost:9867--> **Based on:** [docs/agent-optimization.md](../../docs/agent-optimization.md) β Feb 2026 validation showing **93% token savings** with pattern-driven approach.->-> **Known Results:** Corriere.it has ~2,645 accessibility nodes; pattern extracts 30 headlines in ~272 tokens (vs 3,842 exploratory)-------## Prerequisites--1. Pinchtab server running:- ```bash- pinchtab &- ```--2. `jq` installed (for JSON parsing + token counting):- ```bash- which jq || echo "Install jq: brew install jq"- ```--3. Token counter script (estimate OpenAI tokens):- ```bash- # Rough estimation: ~1 token per 4 chars or 1 token per ~0.75 words- # For exact counts, use tiktoken (Python) or check OpenAI tokenizer- ```-------## Test Steps--### Step 1: Navigate to Corriere.it-```bash-curl -X POST http://localhost:9867/navigate \- -H "Content-Type: application/json" \- -d '{"url": "https://www.corriere.it"}'-```--Expected: `{"tabId": "...", "status": "ok"}`--### Step 2: Get News Titles β Method A (Full Snapshot)-```bash-curl http://localhost:9867/snapshot | jq '.nodes | map(select(.role == "heading")) | .[0:5]' > /tmp/corriere-snapshot-full.json-```--**Capture output:**-```bash-curl http://localhost:9867/snapshot > /tmp/corriere-snapshot-full.json-echo "Full snapshot size:"-wc -c < /tmp/corriere-snapshot-full.json-echo "Estimated tokens:"-stat -f "%.0f" /tmp/corriere-snapshot-full.json | awk '{printf("~%.0f tokens (4 chars per token)\n", $1/4)}'-```--### Step 3: Get News Titles β Method B (Compact Snapshot)-```bash-curl "http://localhost:9867/snapshot?format=compact&filter=interactive" > /tmp/corriere-snapshot-compact.json-echo "Compact snapshot size:"-wc -c < /tmp/corriere-snapshot-compact.json-echo "Estimated tokens:"-stat -f "%.0f" /tmp/corriere-snapshot-compact.json | awk '{printf("~%.0f tokens\n", $1/4)}'-```--### Step 4: Get News Titles β Method C (Text Only)-```bash-curl http://localhost:9867/text | jq '.text' > /tmp/corriere-text.txt-echo "Text extraction size:"-wc -c < /tmp/corriere-text.txt-echo "Estimated tokens:"-stat -f "%.0f" /tmp/corriere-text.txt | awk '{printf("~%.0f tokens\n", $1/4)}'-```--### Step 5: Get Specific Headlines with CSS Selector-```bash-curl "http://localhost:9867/snapshot?selector=.article-headline" | jq '.nodes[] | select(.name | length > 10) | {ref: .ref, title: .name}' > /tmp/corriere-headlines.json-wc -c < /tmp/corriere-headlines.json-```--### Step 6: Pattern-Driven Curl (Validated Optimal)-```bash-# This is the exact pattern from docs/agent-optimization.md-# Achieves 93% token savings-curl -X POST http://localhost:9867/navigate \- -H "Content-Type: application/json" \- -d '{"url": "https://www.corriere.it"}' && \-sleep 3 && \-curl http://localhost:9867/snapshot | \-jq '.nodes[] | select(.name | length > 15) | .name' | \-head -30 | tee /tmp/corriere-headlines.txt--# Measure tokens-echo "Headlines output size:"-wc -c < /tmp/corriere-headlines.txt-```-------## Analysis Template--| Method | Bytes | Est. Tokens | Time | Notes |-|--------|-------|-------------|------|-------|-| Full snapshot | ? | ? | ? | Baseline (2,645 nodes) |-| Compact + filter | ? | ? | ? | ~60% fewer tokens |-| Text only | ? | ? | ? | ~75-80% savings |-| **Pattern-driven curl + jq** | **~1,100** | **~262** | **2-3s** | **β OPTIMAL (93% savings)** |--**Expected for Corriere.it:**-- Full snapshot: ~3,700 tokens-- Pattern-driven: ~262 tokens (difference: 3,438 tokens saved)-------## Expected Results--**Based on actual Feb 2026 testing with Corriere.it:**--| Method | Token Cost | Notes |-|--------|------------|-------|-| Full `/snapshot` (all 2,645 nodes) | ~3,700 tokens | Baseline (exploratory approach) |-| Pattern-driven curl + jq | ~272 tokens | **93% savings** β |-| `/snapshot?format=compact&filter=interactive` | ~1,500β2,000 tokens | 50β70% savings |-| `/text` (readability) | ~800β1,200 tokens | 75β80% savings |--**Key Finding:** Pattern-driven (exact instructions) vs. Exploratory (agent figuring out) = **14.2x difference**-- Exploratory: 142 tokens (input) + 3,700 tokens (output) = 3,842 tokens-- Pattern-driven: 10 tokens (input) + 262 tokens (output) = **272 tokens**-------## Replication for Other Agents--**To run this test as another agent:**--1. **Clone or copy this file** to your workspace-2. **Ensure Pinchtab is running:** `pinchtab &` (or ask host to start it)-3. **Run each step sequentially:**- ```bash- bash -x token-efficiency-corriere.md # Won't work, but shows intent- ```- Or manually run each curl command--4. **Compare results:**- - Save all outputs to `/tmp/corriere-*`- - Compare file sizes- - Calculate token savings--5. **Report format:**- ```- **Token Efficiency Test: corriere.it**- - Full snapshot: 4,250 bytes (~1,062 tokens)- - Compact snapshot: 1,850 bytes (~462 tokens)- - Text only: 925 bytes (~231 tokens)- - Savings with compact: 56% fewer tokens- - Recommended method: /text for reading, /snapshot?format=compact for interaction- ```-------## Docker / Remote Setup--If pinchtab isn't local:--```bash-# Replace localhost:9867 with actual host-PINCHTAB_URL="http://pinchtab-server:9867"--curl -X POST $PINCHTAB_URL/navigate \- -H "Content-Type: application/json" \- -d '{"url": "https://www.corriere.it"}'-```-------## Reference: Optimization Guide--**Full documentation:** See [docs/agent-optimization.md](../../docs/agent-optimization.md)--Key insights from the validation:-- **3-second wait is critical** β Chrome accessibility tree takes time to populate-- **jq filter `length > 15`** β Filters out UI chrome, keeps headlines-- **Pattern-driven is 14.2x better** β Clear instructions beat exploration-- **Works universally** β Same pattern works on BBC News, Corriere.it, etc.--### System Prompt for Agents--```-When extracting headlines from a website:-1. Use EXACTLY this curl pattern (do not deviate):- curl -X POST http://localhost:9867/navigate \- -H "Content-Type: application/json" \- -d '{"url": "TARGET_URL"}' && \- sleep 3 && \- curl http://localhost:9867/snapshot | \- jq '.nodes[] | select(.name | length > 15) | .name' | \- head -30-2. Report only the headlines (limit to 20 items)-3. Do NOT try alternative filters or explanations-```-------## Notes--- **Token estimation:** `bytes / 4` is rough. Use tiktoken (Python) for exact counts:- ```python- import tiktoken- enc = tiktoken.encoding_for_model("gpt-4")- tokens = enc.encode(text)- print(len(tokens))- ```--- **Page load time:** Always wait 3+ seconds after navigate before snapshot-- **Caching:** Snapshot refs are stable within a session; re-use them for actions-- **Stealth:** Test with/without `?displayHeaderFooter=false` for cleaner output-------## Success Criteria--β Agent can extract headlines from corriere.it-β Agent can measure token cost difference between methods-β Agent demonstrates 50%+ token savings with optimized approach-β Results reproducible across multiple runs