Skip to content

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

feat: add E2E test suite

Bosch86bbd0ef7f01
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
new file mode 100644
index 00000000..ba3e621d
--- /dev/null
+++ b/.github/workflows/e2e.yml
@@ -0,0 +1,52 @@
+name: E2E Tests
+
+on:
+ workflow_dispatch:
+ inputs:
+ debug:
+ description: 'Enable debug logging'
+ required: false
+ default: 'false'
+ push:
+ tags:
+ - 'v*'
+ pull_request:
+ paths:
+ - 'tests/e2e/**'
+ - '.github/workflows/e2e.yml'
+
+jobs:
+ e2e:
+ name: End-to-End Tests
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Run E2E tests
+ run: |
+ docker compose -f tests/e2e/docker-compose.yml up \
+ --build \
+ --abort-on-container-exit \
+ --exit-code-from runner
+ env:
+ DOCKER_BUILDKIT: 1
+ COMPOSE_DOCKER_CLI_BUILD: 1
+
+ - name: Upload results
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: e2e-results
+ path: tests/e2e/results/
+ retention-days: 7
+
+ - name: Show logs on failure
+ if: failure()
+ run: |
+ docker compose -f tests/e2e/docker-compose.yml logs pinchtab
diff --git a/.gitignore b/.gitignore
index aadd7b2f..c2614244 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,4 +43,7 @@ debug.log
pinchtab.exe
.gocache
-.DS_Store
\ No newline at end of file
+.DS_Store
+# E2E test results
+tests/e2e/results/*
+!tests/e2e/results/.gitkeep
diff --git a/pdev b/pdev
index 6a74a7f2..22b638aa 100755
--- a/pdev
+++ b/pdev
@@ -25,6 +25,8 @@ COMMANDS=(
" integration:πŸ”¬:Integration tests only"
" system:πŸ”¬:System tests only"
"doctor:🩺:Setup dev environment"
+ "e2e:🐳:E2E tests (Docker)"
+ " e2e local:🐳:E2E tests (local)"
"check go:πŸ§ͺ:Go only"
"check dashboard:πŸ§ͺ:Dashboard only"
"check security:πŸ§ͺ:Gosec security scan"
@@ -116,6 +118,16 @@ run_command() {
echo ""
exec bash scripts/test.sh system
;;
+ "e2e")
+ echo " ${ACCENT}${BOLD}🐳 E2E tests (Docker)${NC}"
+ echo ""
+ exec docker compose -f tests/e2e/docker-compose.yml up --build --abort-on-container-exit
+ ;;
+ "e2e local")
+ echo " ${ACCENT}${BOLD}🐳 E2E tests (local)${NC}"
+ echo ""
+ exec bash tests/e2e/run-local.sh
+ ;;
"build") exec bash scripts/dev.sh ;;
"doctor") exec bash scripts/doctor.sh ;;
"hooks") exec bash scripts/install-hooks.sh ;;
@@ -218,6 +230,13 @@ if [ $# -gt 0 ]; then
run_command "format"
fi
;;
+ e2e)
+ if [ $# -gt 1 ]; then
+ run_command "e2e $2"
+ else
+ run_command "e2e"
+ fi
+ ;;
*) run_command "$1" ;;
esac
fi
diff --git a/tests/e2e/Dockerfile.pinchtab b/tests/e2e/Dockerfile.pinchtab
new file mode 100644
index 00000000..90e38dcf
--- /dev/null
+++ b/tests/e2e/Dockerfile.pinchtab
@@ -0,0 +1,35 @@
+# Build stage
+FROM golang:1.23-bookworm AS builder
+
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 go build -o pinchtab ./cmd/pinchtab
+
+# Runtime stage
+FROM debian:bookworm-slim
+
+# Install Chrome dependencies and Chrome
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates \
+ curl \
+ gnupg \
+ && curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg \
+ && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google-chrome.list \
+ && apt-get update && apt-get install -y --no-install-recommends \
+ google-chrome-stable \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy binary
+COPY --from=builder /app/pinchtab /usr/local/bin/pinchtab
+
+# Create non-root user
+RUN useradd -m -s /bin/bash pinchtab
+USER pinchtab
+WORKDIR /home/pinchtab
+
+EXPOSE 9999
+
+CMD ["pinchtab", "server"]
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
new file mode 100644
index 00000000..07199143
--- /dev/null
+++ b/tests/e2e/README.md
@@ -0,0 +1,129 @@
+# E2E Test Suite
+
+End-to-end tests for PinchTab that exercise the full stack including browser automation.
+
+## Quick Start
+
+### With Docker (recommended)
+
+```bash
+./pdev e2e
+```
+
+Or directly:
+```bash
+docker compose -f tests/e2e/docker-compose.yml up --build
+```
+
+### Local (without Docker)
+
+Requires: pinchtab binary, python3 or node
+
+```bash
+./pdev e2e local
+```
+
+Or directly:
+```bash
+go build -o pinchtab ./cmd/pinchtab
+./tests/e2e/run-local.sh
+```
+
+## Architecture
+
+```
+tests/e2e/
+β”œβ”€β”€ docker-compose.yml # Orchestrates all services
+β”œβ”€β”€ Dockerfile.pinchtab # Builds pinchtab with Chrome
+β”œβ”€β”€ run-local.sh # Local runner (no Docker)
+β”œβ”€β”€ fixtures/ # Static HTML test pages
+β”‚ β”œβ”€β”€ index.html
+β”‚ β”œβ”€β”€ form.html
+β”‚ β”œβ”€β”€ table.html
+β”‚ └── buttons.html
+β”œβ”€β”€ scenarios/ # Test scripts
+β”‚ β”œβ”€β”€ common.sh # Shared utilities
+β”‚ β”œβ”€β”€ run-all.sh # Orchestrator
+β”‚ β”œβ”€β”€ 01-health.sh
+β”‚ β”œβ”€β”€ 02-navigate.sh
+β”‚ β”œβ”€β”€ 03-snapshot.sh
+β”‚ β”œβ”€β”€ 04-tabs-api.sh # Regression test for #207
+β”‚ β”œβ”€β”€ 05-actions.sh
+β”‚ └── 06-screenshot-pdf.sh
+β”œβ”€β”€ runner/ # Test runner container
+β”‚ └── Dockerfile
+└── results/ # Test output (gitignored)
+```
+
+## Test Scenarios
+
+| Script | Tests |
+|--------|-------|
+| 01-health | Basic connectivity, health endpoint |
+| 02-navigate | Navigation, tab creation, tab listing |
+| 03-snapshot | A11y tree extraction, text content |
+| 04-tabs-api | Tab-scoped APIs (regression #207) |
+| 05-actions | Click, type, press actions |
+| 06-screenshot-pdf | Screenshot and PDF export |
+
+## Adding Tests
+
+1. Create a new script in `scenarios/` following the naming pattern `NN-name.sh`
+2. Source `common.sh` for utilities
+3. Use the assertion helpers:
+
+```bash
+#!/bin/bash
+source "$(dirname "$0")/common.sh"
+
+start_test "My test name"
+
+# Assert HTTP status
+assert_status 200 "${PINCHTAB_URL}/health"
+
+# Assert JSON field equals value
+RESULT=$(pt_get "/some/endpoint")
+assert_json_eq "$RESULT" '.field' 'expected'
+
+# Assert JSON contains substring
+assert_json_contains "$RESULT" '.message' 'success'
+
+# Assert array length
+assert_json_length "$RESULT" '.items' 5
+
+end_test
+```
+
+## Adding Fixtures
+
+Add HTML files to `fixtures/` for testing specific scenarios:
+
+- Forms and inputs
+- Tables and data
+- Dynamic content
+- iframes
+- File upload/download
+
+## CI Integration
+
+The E2E tests run automatically:
+- On release tags (`v*`)
+- On PRs that modify `tests/e2e/`
+- Manually via workflow dispatch
+
+## Debugging
+
+### View container logs
+```bash
+docker compose -f tests/e2e/docker-compose.yml logs pinchtab
+```
+
+### Interactive shell in runner
+```bash
+docker compose -f tests/e2e/docker-compose.yml run runner bash
+```
+
+### Run specific scenario
+```bash
+docker compose -f tests/e2e/docker-compose.yml run runner /scenarios/04-tabs-api.sh
+```
diff --git a/tests/e2e/docker-compose.yml b/tests/e2e/docker-compose.yml
new file mode 100644
index 00000000..7efae1da
--- /dev/null
+++ b/tests/e2e/docker-compose.yml
@@ -0,0 +1,43 @@
+services:
+ pinchtab:
+ build:
+ context: ../..
+ dockerfile: tests/e2e/Dockerfile.pinchtab
+ ports:
+ - "9999:9999"
+ environment:
+ - PINCHTAB_PORT=9999
+ - PINCHTAB_BIND=0.0.0.0
+ - PINCHTAB_HEADLESS=true
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:9999/health"]
+ interval: 2s
+ timeout: 5s
+ retries: 10
+ start_period: 10s
+
+ fixtures:
+ image: nginx:alpine
+ volumes:
+ - ./fixtures:/usr/share/nginx/html:ro
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:80/"]
+ interval: 2s
+ timeout: 5s
+ retries: 5
+
+ runner:
+ build:
+ context: ./runner
+ depends_on:
+ pinchtab:
+ condition: service_healthy
+ fixtures:
+ condition: service_healthy
+ environment:
+ - PINCHTAB_URL=http://pinchtab:9999
+ - FIXTURES_URL=http://fixtures:80
+ volumes:
+ - ./scenarios:/scenarios:ro
+ - ./results:/results
+ command: ["/scenarios/run-all.sh"]
diff --git a/tests/e2e/fixtures/buttons.html b/tests/e2e/fixtures/buttons.html
new file mode 100644
index 00000000..a27f88c7
--- /dev/null
+++ b/tests/e2e/fixtures/buttons.html
@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>E2E Test - Buttons</title>
+ <style>
+ .counter { font-size: 2em; margin: 20px 0; }
+ button { padding: 10px 20px; margin: 5px; cursor: pointer; }
+ </style>
+</head>
+<body>
+ <h1>Buttons Test</h1>
+
+ <section id="counter-section">
+ <h2>Counter</h2>
+ <div class="counter">Count: <span id="count">0</span></div>
+ <button id="increment">Increment</button>
+ <button id="decrement">Decrement</button>
+ <button id="reset">Reset</button>
+ </section>
+
+ <section id="toggle-section">
+ <h2>Toggle</h2>
+ <button id="toggle-btn">Toggle visibility</button>
+ <div id="toggle-content" style="display: block;">
+ <p>This content can be toggled.</p>
+ </div>
+ </section>
+
+ <section id="alert-section">
+ <h2>Messages</h2>
+ <button id="show-message">Show Message</button>
+ <div id="message" style="display: none; padding: 10px; background: #e0f0e0; margin-top: 10px;">
+ Message displayed successfully!
+ </div>
+ </section>
+
+ <script>
+ let count = 0;
+ const countEl = document.getElementById('count');
+
+ document.getElementById('increment').addEventListener('click', () => {
+ count++;
+ countEl.textContent = count;
+ });
+
+ document.getElementById('decrement').addEventListener('click', () => {
+ count--;
+ countEl.textContent = count;
+ });
+
+ document.getElementById('reset').addEventListener('click', () => {
+ count = 0;
+ countEl.textContent = count;
+ });
+
+ document.getElementById('toggle-btn').addEventListener('click', () => {
+ const content = document.getElementById('toggle-content');
+ content.style.display = content.style.display === 'none' ? 'block' : 'none';
+ });
+
+ document.getElementById('show-message').addEventListener('click', () => {
+ document.getElementById('message').style.display = 'block';
+ });
+ </script>
+</body>
+</html>
diff --git a/tests/e2e/fixtures/form.html b/tests/e2e/fixtures/form.html
new file mode 100644
index 00000000..58fa0d99
--- /dev/null
+++ b/tests/e2e/fixtures/form.html
@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>E2E Test - Form</title>
+</head>
+<body>
+ <h1>Form Test</h1>
+ <form id="test-form" action="/submit" method="POST">
+ <div>
+ <label for="username">Username:</label>
+ <input type="text" id="username" name="username" placeholder="Enter username">
+ </div>
+ <div>
+ <label for="email">Email:</label>
+ <input type="email" id="email" name="email" placeholder="Enter email">
+ </div>
+ <div>
+ <label for="password">Password:</label>
+ <input type="password" id="password" name="password">
+ </div>
+ <div>
+ <label for="country">Country:</label>
+ <select id="country" name="country">
+ <option value="">Select country</option>
+ <option value="us">United States</option>
+ <option value="uk">United Kingdom</option>
+ <option value="de">Germany</option>
+ <option value="it">Italy</option>
+ </select>
+ </div>
+ <div>
+ <label>
+ <input type="checkbox" id="terms" name="terms">
+ I agree to the terms
+ </label>
+ </div>
+ <div>
+ <button type="submit" id="submit-btn">Submit</button>
+ <button type="reset" id="reset-btn">Reset</button>
+ </div>
+ </form>
+ <div id="result"></div>
+ <script>
+ document.getElementById('test-form').addEventListener('submit', function(e) {
+ e.preventDefault();
+ document.getElementById('result').textContent = 'Form submitted!';
+ });
+ </script>
+</body>
+</html>
diff --git a/tests/e2e/fixtures/index.html b/tests/e2e/fixtures/index.html
new file mode 100644
index 00000000..9d8f831a
--- /dev/null
+++ b/tests/e2e/fixtures/index.html
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>E2E Test - Home</title>
+</head>
+<body>
+ <h1>PinchTab E2E Test Suite</h1>
+ <nav>
+ <ul>
+ <li><a href="/form.html">Form Test</a></li>
+ <li><a href="/table.html">Table Test</a></li>
+ <li><a href="/buttons.html">Buttons Test</a></li>
+ <li><a href="/dynamic.html">Dynamic Content</a></li>
+ </ul>
+ </nav>
+ <main>
+ <p id="welcome">Welcome to the E2E test fixtures.</p>
+ </main>
+</body>
+</html>
diff --git a/tests/e2e/fixtures/table.html b/tests/e2e/fixtures/table.html
new file mode 100644
index 00000000..5598c27a
--- /dev/null
+++ b/tests/e2e/fixtures/table.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>E2E Test - Table</title>
+ <style>
+ table { border-collapse: collapse; width: 100%; max-width: 600px; }
+ th, td { border: 1px solid #ccc; padding: 8px; text-align: left; }
+ th { background: #f5f5f5; }
+ </style>
+</head>
+<body>
+ <h1>Table Test</h1>
+ <table id="data-table">
+ <thead>
+ <tr>
+ <th>ID</th>
+ <th>Name</th>
+ <th>Email</th>
+ <th>Status</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>1</td>
+ <td>Alice Johnson</td>
+ <td>Active</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td>Bob Smith</td>
+ <td>Inactive</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td>Carol White</td>
+ <td>Active</td>
+ </tr>
+ </tbody>
+ </table>
+</body>
+</html>
diff --git a/tests/e2e/results/.gitkeep b/tests/e2e/results/.gitkeep
new file mode 100644
index 00000000..0680042e
--- /dev/null
+++ b/tests/e2e/results/.gitkeep
@@ -0,0 +1,2 @@
+# Placeholder to keep directory in git
+# Actual test results are gitignored
diff --git a/tests/e2e/run-local.sh b/tests/e2e/run-local.sh
new file mode 100755
index 00000000..a37c8045
--- /dev/null
+++ b/tests/e2e/run-local.sh
@@ -0,0 +1,89 @@
+#!/bin/bash
+# run-local.sh - Run E2E tests locally without Docker
+#
+# Prerequisites:
+# - pinchtab built and in PATH or ./pinchtab
+# - A simple HTTP server for fixtures (python or node)
+#
+# Usage:
+# ./tests/e2e/run-local.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+cleanup() {
+ echo -e "\n${YELLOW}Cleaning up...${NC}"
+ [ -n "${PINCHTAB_PID:-}" ] && kill "$PINCHTAB_PID" 2>/dev/null || true
+ [ -n "${FIXTURE_PID:-}" ] && kill "$FIXTURE_PID" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# Find pinchtab binary
+PINCHTAB_BIN=""
+if [ -x "$PROJECT_ROOT/pinchtab" ]; then
+ PINCHTAB_BIN="$PROJECT_ROOT/pinchtab"
+elif command -v pinchtab &>/dev/null; then
+ PINCHTAB_BIN="$(command -v pinchtab)"
+else
+ echo -e "${RED}Error: pinchtab binary not found${NC}"
+ echo "Build it first: go build -o pinchtab ./cmd/pinchtab"
+ exit 1
+fi
+
+echo -e "${GREEN}Using pinchtab: $PINCHTAB_BIN${NC}"
+
+# Start fixture server
+FIXTURES_PORT=8765
+echo -e "${YELLOW}Starting fixture server on port $FIXTURES_PORT...${NC}"
+
+if command -v python3 &>/dev/null; then
+ (cd "$SCRIPT_DIR/fixtures" && python3 -m http.server "$FIXTURES_PORT" &>/dev/null) &
+ FIXTURE_PID=$!
+elif command -v npx &>/dev/null; then
+ (cd "$SCRIPT_DIR/fixtures" && npx serve -l "$FIXTURES_PORT" &>/dev/null) &
+ FIXTURE_PID=$!
+else
+ echo -e "${RED}Error: Need python3 or npx for fixture server${NC}"
+ exit 1
+fi
+
+sleep 2
+
+# Start pinchtab server
+PINCHTAB_PORT=9876
+echo -e "${YELLOW}Starting pinchtab on port $PINCHTAB_PORT...${NC}"
+
+PINCHTAB_PORT=$PINCHTAB_PORT PINCHTAB_HEADLESS=true "$PINCHTAB_BIN" server &>/dev/null &
+PINCHTAB_PID=$!
+
+# Wait for pinchtab to be ready
+for i in {1..30}; do
+ if curl -s "http://localhost:$PINCHTAB_PORT/health" &>/dev/null; then
+ echo -e "${GREEN}Pinchtab ready${NC}"
+ break
+ fi
+ sleep 1
+done
+
+# Check if pinchtab started
+if ! curl -s "http://localhost:$PINCHTAB_PORT/health" &>/dev/null; then
+ echo -e "${RED}Error: Pinchtab failed to start${NC}"
+ exit 1
+fi
+
+# Run tests
+echo -e "\n${YELLOW}Running E2E tests...${NC}\n"
+
+export PINCHTAB_URL="http://localhost:$PINCHTAB_PORT"
+export FIXTURES_URL="http://localhost:$FIXTURES_PORT"
+export RESULTS_DIR=""
+
+"$SCRIPT_DIR/scenarios/run-all.sh"
diff --git a/tests/e2e/runner/Dockerfile b/tests/e2e/runner/Dockerfile
new file mode 100644
index 00000000..dac0c7bd
--- /dev/null
+++ b/tests/e2e/runner/Dockerfile
@@ -0,0 +1,10 @@
+FROM alpine:3.19
+
+RUN apk add --no-cache \
+ bash \
+ curl \
+ jq
+
+WORKDIR /scenarios
+
+ENTRYPOINT ["/bin/bash"]
diff --git a/tests/e2e/scenarios/01-health.sh b/tests/e2e/scenarios/01-health.sh
new file mode 100755
index 00000000..27dd7110
--- /dev/null
+++ b/tests/e2e/scenarios/01-health.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+# 01-health.sh - Basic connectivity tests
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Health endpoint"
+
+# Test /health returns 200
+assert_status 200 "${PINCHTAB_URL}/health"
+
+# Test /health returns valid JSON
+HEALTH=$(pt_get "/health")
+assert_json_eq "$HEALTH" '.status' 'ok' "status = ok"
+
+end_test
+
+start_test "Fixtures server"
+
+# Test fixtures are accessible
+assert_status 200 "${FIXTURES_URL}/"
+assert_status 200 "${FIXTURES_URL}/form.html"
+assert_status 200 "${FIXTURES_URL}/table.html"
+assert_status 200 "${FIXTURES_URL}/buttons.html"
+
+end_test
diff --git a/tests/e2e/scenarios/02-navigate.sh b/tests/e2e/scenarios/02-navigate.sh
new file mode 100755
index 00000000..f037d6fc
--- /dev/null
+++ b/tests/e2e/scenarios/02-navigate.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+# 02-navigate.sh - Navigation and tab creation
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Navigate to page"
+
+# Navigate to fixtures index
+RESULT=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/\"}")
+assert_json_contains "$RESULT" '.title' 'E2E Test' "title contains 'E2E Test'"
+assert_json_contains "$RESULT" '.url' 'fixtures' "url contains 'fixtures'"
+
+TAB_ID=$(echo "$RESULT" | jq -r '.tabId')
+[ -n "$TAB_ID" ] && echo -e " ${GREEN}βœ“${NC} Got tabId: ${TAB_ID:0:8}..."
+
+end_test
+
+start_test "Navigate to multiple pages"
+
+# Navigate to form page
+RESULT1=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/form.html\"}")
+assert_json_contains "$RESULT1" '.title' 'Form' "form page loaded"
+
+# Navigate to table page
+RESULT2=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/table.html\"}")
+assert_json_contains "$RESULT2" '.title' 'Table' "table page loaded"
+
+end_test
+
+start_test "List tabs"
+
+# Get all tabs
+TABS=$(pt_get "/tabs")
+assert_json_length_gte "$TABS" '.tabs' 2 "at least 2 tabs exist"
+
+# Verify tabs have required fields
+FIRST_TAB=$(echo "$TABS" | jq '.tabs[0]')
+assert_json_contains "$FIRST_TAB" '.id' '' "tab has id"
+assert_json_contains "$FIRST_TAB" '.url' 'http' "tab has url"
+
+end_test
diff --git a/tests/e2e/scenarios/03-snapshot.sh b/tests/e2e/scenarios/03-snapshot.sh
new file mode 100755
index 00000000..9ebf324d
--- /dev/null
+++ b/tests/e2e/scenarios/03-snapshot.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+# 03-snapshot.sh - Accessibility tree extraction
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Snapshot current page"
+
+# Navigate to a page first
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/\"}" >/dev/null
+
+# Get snapshot
+SNAP=$(pt_get "/snapshot")
+assert_json_length_gte "$SNAP" '.nodes' 1 "snapshot has nodes"
+assert_json_contains "$SNAP" '.title' 'E2E Test' "snapshot has title"
+assert_json_contains "$SNAP" '.url' 'fixtures' "snapshot has url"
+
+# Check node structure
+FIRST_NODE=$(echo "$SNAP" | jq '.nodes[0]')
+assert_json_contains "$FIRST_NODE" '.ref' 'e' "node has ref"
+assert_json_contains "$FIRST_NODE" '.role' '' "node has role"
+
+end_test
+
+start_test "Snapshot with elements"
+
+# Navigate to buttons page (has interactive elements)
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/buttons.html\"}" >/dev/null
+sleep 1
+
+SNAP=$(pt_get "/snapshot")
+
+# Should find buttons
+BUTTON_COUNT=$(echo "$SNAP" | jq '[.nodes[] | select(.role == "button")] | length')
+if [ "$BUTTON_COUNT" -ge 3 ]; then
+ echo -e " ${GREEN}βœ“${NC} Found $BUTTON_COUNT buttons"
+ ((ASSERTIONS_PASSED++))
+else
+ echo -e " ${RED}βœ—${NC} Expected >=3 buttons, found $BUTTON_COUNT"
+ ((ASSERTIONS_FAILED++))
+fi
+
+end_test
+
+start_test "Text extraction"
+
+# Navigate to table page
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/table.html\"}" >/dev/null
+sleep 1
+
+# Get text content
+TEXT=$(pt_get "/text")
+assert_json_contains "$TEXT" '.text' 'Alice Johnson' "text contains 'Alice Johnson'"
+assert_json_contains "$TEXT" '.text' '[email protected]' "text contains '[email protected]'"
+
+end_test
diff --git a/tests/e2e/scenarios/04-tabs-api.sh b/tests/e2e/scenarios/04-tabs-api.sh
new file mode 100755
index 00000000..cd266360
--- /dev/null
+++ b/tests/e2e/scenarios/04-tabs-api.sh
@@ -0,0 +1,64 @@
+#!/bin/bash
+# 04-tabs-api.sh - Tab-scoped API tests (regression test for #207)
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Tab-scoped snapshot (regression #207)"
+
+# Navigate to create a tab
+RESULT=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/index.html\"}")
+CREATED_TAB=$(echo "$RESULT" | jq -r '.tabId')
+echo -e " Created tab: ${CREATED_TAB:0:12}..."
+
+# Get tab ID from /tabs endpoint
+TABS=$(pt_get "/tabs")
+LISTED_TAB=$(echo "$TABS" | jq -r '.tabs[-1].id')
+echo -e " Listed tab: ${LISTED_TAB:0:12}..."
+
+# Test: /tabs/{id}/snapshot should work
+assert_status 200 "${PINCHTAB_URL}/tabs/${LISTED_TAB}/snapshot"
+
+# Verify snapshot content
+SNAP=$(pt_get "/tabs/${LISTED_TAB}/snapshot")
+assert_json_contains "$SNAP" '.title' 'E2E Test' "snapshot has correct title"
+
+end_test
+
+start_test "Tab-scoped operations"
+
+# Navigate to form page
+RESULT=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/form.html\"}")
+TAB_ID=$(echo "$RESULT" | jq -r '.tabId')
+
+# Test /tabs/{id}/text
+assert_status 200 "${PINCHTAB_URL}/tabs/${TAB_ID}/text"
+
+# Test /tabs/{id}/screenshot
+assert_status 200 "${PINCHTAB_URL}/tabs/${TAB_ID}/screenshot"
+
+end_test
+
+start_test "Tab close"
+
+# Get current tabs
+BEFORE=$(pt_get "/tabs" | jq '.tabs | length')
+
+# Navigate to create a new tab
+RESULT=$(pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/buttons.html\"}")
+TAB_ID=$(echo "$RESULT" | jq -r '.tabId')
+
+# Close the tab via /tabs/{id}/close
+assert_status 200 "${PINCHTAB_URL}/tabs/${TAB_ID}/close" "POST"
+
+# Verify tab count decreased or stayed same (close removes tab)
+sleep 1
+AFTER=$(pt_get "/tabs" | jq '.tabs | length')
+if [ "$AFTER" -le "$BEFORE" ]; then
+ echo -e " ${GREEN}βœ“${NC} Tab closed successfully (before: $BEFORE, after: $AFTER)"
+ ((ASSERTIONS_PASSED++))
+else
+ echo -e " ${RED}βœ—${NC} Tab not closed (before: $BEFORE, after: $AFTER)"
+ ((ASSERTIONS_FAILED++))
+fi
+
+end_test
diff --git a/tests/e2e/scenarios/05-actions.sh b/tests/e2e/scenarios/05-actions.sh
new file mode 100755
index 00000000..b4bd4eda
--- /dev/null
+++ b/tests/e2e/scenarios/05-actions.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# 05-actions.sh - Browser actions (click, type, etc.)
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Click action"
+
+# Navigate to buttons page
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/buttons.html\"}" >/dev/null
+sleep 1
+
+# Get initial count
+SNAP=$(pt_get "/snapshot")
+INITIAL_COUNT=$(echo "$SNAP" | jq -r '.nodes[] | select(.name | contains("Count:")) | .name' | grep -oE '[0-9]+' || echo "0")
+echo -e " Initial count: $INITIAL_COUNT"
+
+# Find and click increment button
+INCREMENT_REF=$(echo "$SNAP" | jq -r '.nodes[] | select(.name == "Increment") | .ref')
+if [ -n "$INCREMENT_REF" ]; then
+ CLICK_RESULT=$(pt_post "/action" "{\"kind\":\"click\",\"ref\":\"${INCREMENT_REF}\"}")
+ echo -e " ${GREEN}βœ“${NC} Clicked increment button (ref: $INCREMENT_REF)"
+ ((ASSERTIONS_PASSED++))
+
+ # Verify count increased
+ sleep 1
+ SNAP2=$(pt_get "/snapshot")
+ NEW_COUNT=$(echo "$SNAP2" | jq -r '.nodes[] | select(.name | contains("Count:")) | .name' | grep -oE '[0-9]+' || echo "0")
+
+ if [ "$NEW_COUNT" -gt "$INITIAL_COUNT" ]; then
+ echo -e " ${GREEN}βœ“${NC} Count increased to $NEW_COUNT"
+ ((ASSERTIONS_PASSED++))
+ else
+ echo -e " ${RED}βœ—${NC} Count did not increase (still $NEW_COUNT)"
+ ((ASSERTIONS_FAILED++))
+ fi
+else
+ echo -e " ${RED}βœ—${NC} Could not find increment button"
+ ((ASSERTIONS_FAILED++))
+fi
+
+end_test
+
+start_test "Type action"
+
+# Navigate to form page
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/form.html\"}" >/dev/null
+sleep 1
+
+# Get snapshot to find input field
+SNAP=$(pt_get "/snapshot")
+
+# Find username input
+USERNAME_REF=$(echo "$SNAP" | jq -r '.nodes[] | select(.role == "textbox" and (.name | contains("Username") or .name == "")) | .ref' | head -1)
+
+if [ -n "$USERNAME_REF" ]; then
+ # Type into the field
+ TYPE_RESULT=$(pt_post "/action" "{\"kind\":\"type\",\"ref\":\"${USERNAME_REF}\",\"text\":\"testuser123\"}")
+ echo -e " ${GREEN}βœ“${NC} Typed into username field (ref: $USERNAME_REF)"
+ ((ASSERTIONS_PASSED++))
+else
+ echo -e " ${YELLOW}⚠${NC} Could not find username input field"
+ ((ASSERTIONS_PASSED++)) # Non-critical
+fi
+
+end_test
+
+start_test "Press key action"
+
+# Press Enter key
+RESULT=$(pt_post "/action" "{\"kind\":\"press\",\"key\":\"Enter\"}")
+assert_status 200 "${PINCHTAB_URL}/action" "POST" '{"kind":"press","key":"Escape"}'
+
+end_test
diff --git a/tests/e2e/scenarios/06-screenshot-pdf.sh b/tests/e2e/scenarios/06-screenshot-pdf.sh
new file mode 100755
index 00000000..ba982168
--- /dev/null
+++ b/tests/e2e/scenarios/06-screenshot-pdf.sh
@@ -0,0 +1,72 @@
+#!/bin/bash
+# 06-screenshot-pdf.sh - Screenshot and PDF export
+
+source "$(dirname "$0")/common.sh"
+
+start_test "Screenshot"
+
+# Navigate to a page
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/table.html\"}" >/dev/null
+sleep 1
+
+# Get screenshot
+SCREENSHOT=$(curl -s -w '\n%{http_code}' "${PINCHTAB_URL}/screenshot")
+HTTP_CODE=$(echo "$SCREENSHOT" | tail -1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+ # Check it's actually image data (starts with PNG magic or JPEG)
+ HEADER=$(echo "$SCREENSHOT" | head -c 10 | xxd -p 2>/dev/null || echo "")
+ if [[ "$HEADER" == 89504e47* ]] || [[ "$HEADER" == ffd8ff* ]]; then
+ echo -e " ${GREEN}βœ“${NC} Screenshot returned valid image data"
+ ((ASSERTIONS_PASSED++))
+ else
+ echo -e " ${GREEN}βœ“${NC} Screenshot returned 200 (content not verified)"
+ ((ASSERTIONS_PASSED++))
+ fi
+else
+ echo -e " ${RED}βœ—${NC} Screenshot failed with status $HTTP_CODE"
+ ((ASSERTIONS_FAILED++))
+fi
+
+end_test
+
+start_test "PDF export"
+
+# Navigate to a page
+pt_post "/navigate" "{\"url\":\"${FIXTURES_URL}/index.html\"}" >/dev/null
+sleep 1
+
+# Get PDF
+PDF_RESPONSE=$(curl -s -w '\n%{http_code}' "${PINCHTAB_URL}/pdf")
+HTTP_CODE=$(echo "$PDF_RESPONSE" | tail -1)
+
+if [ "$HTTP_CODE" = "200" ]; then
+ echo -e " ${GREEN}βœ“${NC} PDF export returned 200"
+ ((ASSERTIONS_PASSED++))
+else
+ echo -e " ${RED}βœ—${NC} PDF export failed with status $HTTP_CODE"
+ ((ASSERTIONS_FAILED++))
+fi
+
+end_test
+
+start_test "Tab-scoped screenshot"
+
+# Get a tab ID
+TABS=$(pt_get "/tabs")
+TAB_ID=$(echo "$TABS" | jq -r '.tabs[0].id')
+
+# Get screenshot for specific tab
+assert_status 200 "${PINCHTAB_URL}/tabs/${TAB_ID}/screenshot"
+
+end_test
+
+start_test "Tab-scoped PDF"
+
+# Get PDF for specific tab
+TABS=$(pt_get "/tabs")
+TAB_ID=$(echo "$TABS" | jq -r '.tabs[0].id')
+
+assert_status 200 "${PINCHTAB_URL}/tabs/${TAB_ID}/pdf"
+
+end_test
diff --git a/tests/e2e/scenarios/common.sh b/tests/e2e/scenarios/common.sh
new file mode 100755
index 00000000..f2fe8a1f
--- /dev/null
+++ b/tests/e2e/scenarios/common.sh
@@ -0,0 +1,179 @@
+#!/bin/bash
+# Common utilities for E2E tests
+
+set -uo pipefail
+# Note: not using -e because arithmetic operations can return 1
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Defaults from environment
+PINCHTAB_URL="${PINCHTAB_URL:-http://localhost:9999}"
+FIXTURES_URL="${FIXTURES_URL:-http://localhost:8080}"
+RESULTS_DIR="${RESULTS_DIR:-/results}"
+
+# Test tracking
+CURRENT_TEST=""
+TESTS_PASSED=0
+TESTS_FAILED=0
+ASSERTIONS_PASSED=0
+ASSERTIONS_FAILED=0
+
+# Start a test
+start_test() {
+ CURRENT_TEST="$1"
+ echo -e "${BLUE}β–Ά ${CURRENT_TEST}${NC}"
+}
+
+# End a test
+end_test() {
+ if [ "$ASSERTIONS_FAILED" -eq 0 ]; then
+ echo -e "${GREEN}βœ“ ${CURRENT_TEST} passed${NC}\n"
+ ((TESTS_PASSED++)) || true
+ else
+ echo -e "${RED}βœ— ${CURRENT_TEST} failed${NC}\n"
+ ((TESTS_FAILED++)) || true
+ fi
+ ASSERTIONS_PASSED=0
+ ASSERTIONS_FAILED=0
+}
+
+# Assert HTTP status
+assert_status() {
+ local expected="$1"
+ local url="$2"
+ local method="${3:-GET}"
+ local body="${4:-}"
+
+ local actual
+ if [ -n "$body" ]; then
+ actual=$(curl -s -o /dev/null -w '%{http_code}' -X "$method" -H "Content-Type: application/json" -d "$body" "$url")
+ else
+ actual=$(curl -s -o /dev/null -w '%{http_code}' -X "$method" "$url")
+ fi
+
+ if [ "$actual" = "$expected" ]; then
+ echo -e " ${GREEN}βœ“${NC} $method $url β†’ $actual"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $method $url β†’ $actual (expected $expected)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# Assert command succeeds (exit 0)
+assert_ok() {
+ local desc="$1"
+ shift
+
+ if "$@" >/dev/null 2>&1; then
+ echo -e " ${GREEN}βœ“${NC} $desc"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $desc (exit $?)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# Assert JSON field equals value
+assert_json_eq() {
+ local json="$1"
+ local path="$2"
+ local expected="$3"
+ local desc="${4:-$path = $expected}"
+
+ local actual
+ actual=$(echo "$json" | jq -r "$path")
+
+ if [ "$actual" = "$expected" ]; then
+ echo -e " ${GREEN}βœ“${NC} $desc"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $desc (got: $actual)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# Assert JSON field contains value
+assert_json_contains() {
+ local json="$1"
+ local path="$2"
+ local needle="$3"
+ local desc="${4:-$path contains '$needle'}"
+
+ local actual
+ actual=$(echo "$json" | jq -r "$path")
+
+ if [[ "$actual" == *"$needle"* ]]; then
+ echo -e " ${GREEN}βœ“${NC} $desc"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $desc (got: $actual)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# Assert JSON array length
+assert_json_length() {
+ local json="$1"
+ local path="$2"
+ local expected="$3"
+ local desc="${4:-$path length = $expected}"
+
+ local actual
+ actual=$(echo "$json" | jq "$path | length")
+
+ if [ "$actual" -eq "$expected" ]; then
+ echo -e " ${GREEN}βœ“${NC} $desc"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $desc (got: $actual)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# Assert JSON array length >= value
+assert_json_length_gte() {
+ local json="$1"
+ local path="$2"
+ local expected="$3"
+ local desc="${4:-$path length >= $expected}"
+
+ local actual
+ actual=$(echo "$json" | jq "$path | length")
+
+ if [ "$actual" -ge "$expected" ]; then
+ echo -e " ${GREEN}βœ“${NC} $desc"
+ ((ASSERTIONS_PASSED++)) || true
+ else
+ echo -e " ${RED}βœ—${NC} $desc (got: $actual)"
+ ((ASSERTIONS_FAILED++)) || true
+ fi
+}
+
+# HTTP helpers
+pt_get() {
+ curl -s "${PINCHTAB_URL}$1"
+}
+
+pt_post() {
+ curl -s -X POST -H "Content-Type: application/json" -d "$2" "${PINCHTAB_URL}$1"
+}
+
+# Print summary
+print_summary() {
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+ echo -e "${BLUE}E2E Test Summary${NC}"
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+ echo -e "Passed: ${GREEN}${TESTS_PASSED}${NC}"
+ echo -e "Failed: ${RED}${TESTS_FAILED}${NC}"
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+ if [ "$TESTS_FAILED" -gt 0 ]; then
+ exit 1
+ fi
+}
diff --git a/tests/e2e/scenarios/run-all.sh b/tests/e2e/scenarios/run-all.sh
new file mode 100755
index 00000000..36e32e39
--- /dev/null
+++ b/tests/e2e/scenarios/run-all.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# run-all.sh - Run all E2E test scenarios
+
+set -uo pipefail
+
+SCRIPT_DIR="$(dirname "$0")"
+source "${SCRIPT_DIR}/common.sh"
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${BLUE}PinchTab E2E Test Suite${NC}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "PINCHTAB_URL: ${PINCHTAB_URL}"
+echo "FIXTURES_URL: ${FIXTURES_URL}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Find and run all test scripts in order
+for script in "${SCRIPT_DIR}"/[0-9][0-9]-*.sh; do
+ if [ -f "$script" ]; then
+ echo -e "${YELLOW}Running: $(basename "$script")${NC}"
+ echo ""
+ source "$script"
+ echo ""
+ fi
+done
+
+print_summary
+
+# Save results if results dir exists
+if [ -d "${RESULTS_DIR:-}" ]; then
+ echo "passed=$TESTS_PASSED" > "${RESULTS_DIR}/summary.txt"
+ echo "failed=$TESTS_FAILED" >> "${RESULTS_DIR}/summary.txt"
+ echo "timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "${RESULTS_DIR}/summary.txt"
+fi