High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: chromium headless=new compatibility and single-test runner
Luigi Agosti19c8e7ee58d3
diff --git a/Dockerfile b/Dockerfileindex a4b0f284..fbb3162a 100644--- a/Dockerfile+++ b/Dockerfile@@ -30,7 +30,7 @@ RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab# - Container provides isolation via cgroups, seccomp, dropped capabilities,# read-only filesystem, and non-root user# - This matches best practices for headless Chrome in containerized environments-FROM alpine:3.21+FROM alpine:3.23LABEL org.opencontainers.image.source="https://github.com/pinchtab/pinchtab"LABEL org.opencontainers.image.description="High-performance browser automation bridge"diff --git a/dev b/devindex f74a436a..1e084bf0 100755--- a/dev+++ b/dev@@ -36,6 +36,7 @@ COMMANDS=(" api-extended:π³:API extended (multi-instance)"" cli-extended:π³:CLI extended tests"" infra-extended:π³:Infra extended (multi-instance)"+ " test <name>:π³:Run a single E2E test by start_test name""opt:β‘:Optimization baseline"" baseline:β‘:Run optimization baseline lane""bench:π:Benchmark lanes"@@ -204,6 +205,16 @@ run_command() {local bench_args="${target#bench }"exec bash scripts/dev-bench.sh ${bench_args};;+ "e2e test")+ echo " ${ERROR}Missing test name. Usage: dev e2e test \"<name substring>\"${NC}"+ exit 1+ ;;+ "e2e test "*)+ local test_name="${target#e2e test }"+ echo " ${ACCENT}${BOLD}π― Single E2E test${NC}"+ echo ""+ exec env E2E_LOGS="${E2E_LOGS:-show}" bash scripts/dev-e2e.sh "$test_name"+ ;;"e2e"*)local suite="release"local filter=""@@ -339,6 +350,16 @@ if [ $# -gt 0 ]; thenfi;;e2e)+ if [ "${2:-}" = "test" ]; then+ if [ $# -lt 3 ] || [ -z "${3:-}" ]; then+ echo " ${ERROR}Missing test name. Usage: dev e2e test \"<name substring>\"${NC}" >&2+ exit 1+ fi+ echo ""+ echo " ${ACCENT}${BOLD}π― Single E2E test${NC}"+ echo ""+ exec env E2E_LOGS="${E2E_LOGS:-show}" bash scripts/dev-e2e.sh "$3"+ fiif [ $# -eq 1 ] || [[ "${2:-}" == *=* ]]; thenexec env E2E_LOGS="${E2E_LOGS:-hide}" bash scripts/e2e.sh release "${@:2}"fidiff --git a/internal/assets/stealth.js b/internal/assets/stealth.jsindex 96f8013a..59b6f56d 100644--- a/internal/assets/stealth.js+++ b/internal/assets/stealth.js@@ -302,13 +302,24 @@ if (navigator.connection) {const screenHeight = Math.max(outerHeight + 80, 768);const chromeHeight = Math.max(screenHeight - outerHeight, 32);const availHeight = Math.max(outerHeight, screenHeight - chromeHeight);-+Object.defineProperty(screen, 'width', { get: () => screenWidth, configurable: true });Object.defineProperty(screen, 'height', { get: () => screenHeight, configurable: true });Object.defineProperty(screen, 'availWidth', { get: () => screenWidth, configurable: true });Object.defineProperty(screen, 'availHeight', { get: () => availHeight, configurable: true });Object.defineProperty(screen, 'colorDepth', { get: () => 24, configurable: true });Object.defineProperty(screen, 'pixelDepth', { get: () => 24, configurable: true });++ // Chromium --headless=new returns outerWidth/outerHeight = 0 by default,+ // which is a strong bot signal (real browsers always have non-zero outer+ // dims). Backfill them only when missing β full-level stealth replaces+ // these with more sophisticated values further down.+ if (!(window.outerWidth > 0)) {+ try { Object.defineProperty(window, 'outerWidth', { get: () => outerWidth, configurable: true }); } catch (e) {}+ }+ if (!(window.outerHeight > 0)) {+ try { Object.defineProperty(window, 'outerHeight', { get: () => outerHeight, configurable: true }); } catch (e) {}+ }})();if (!(window.devicePixelRatio > 0)) {diff --git a/internal/bridge/action_pointer.go b/internal/bridge/action_pointer.goindex f358cfc4..c4c4d55e 100644--- a/internal/bridge/action_pointer.go+++ b/internal/bridge/action_pointer.go@@ -435,25 +435,66 @@ func (b *Bridge) actionDrag(ctx context.Context, req ActionRequest) (map[string]}func (b *Bridge) actionHumanClick(ctx context.Context, req ActionRequest) (map[string]any, error) {- if req.NodeID > 0 {- // req.NodeID is a backendDOMNodeId from the accessibility tree- if err := ClickElement(ctx, cdp.BackendNodeID(req.NodeID)); err != nil {- return nil, err- }- return map[string]any{"clicked": true, "human": true}, nil- }- if req.Selector != "" {+ var backendNodeID cdp.BackendNodeID+ switch {+ case req.NodeID > 0:+ backendNodeID = cdp.BackendNodeID(req.NodeID)+ case req.Selector != "":node, err := firstNodeBySelector(ctx, req.Selector)if err != nil {return nil, err}- // Use BackendNodeID from the DOM node- if err := ClickElement(ctx, node.BackendNodeID); err != nil {- return nil, err+ backendNodeID = node.BackendNodeID+ default:+ return nil, fmt.Errorf("need selector, ref, or nodeId")+ }++ // Run the multi-step humanClick (bezier mouse-move + press + release) in+ // a goroutine and poll for blocking dialogs. Without this, a dialog or+ // dialog-like popup opened by the click would hang the renderer for the+ // full action timeout. Mirrors the wrapping used by actionClick.+ dm := b.GetDialogManager()+ detectDialog := req.TabID != "" && dm != nil+ clickCtx := ctx+ var clickCancel context.CancelFunc+ if detectDialog {+ clickCtx, clickCancel = context.WithCancel(ctx)+ defer clickCancel()+ }++ resultCh := make(chan error, 1)+ go func() {+ resultCh <- ClickElement(clickCtx, backendNodeID)+ }()++ if detectDialog {+ ticker := time.NewTicker(dialogAutoHandlePollInterval)+ defer ticker.Stop()+ for {+ select {+ case err := <-resultCh:+ if err != nil {+ return nil, err+ }+ return map[string]any{"clicked": true, "human": true}, nil+ case <-ticker.C:+ if pending := dm.GetPending(req.TabID); pending != nil {+ clickCancel()+ return nil, &ErrDialogBlocking{+ DialogType: pending.Type,+ DialogMessage: pending.Message,+ }+ }+ case <-ctx.Done():+ return nil, ctx.Err()+ }}- return map[string]any{"clicked": true, "human": true}, nil}- return nil, fmt.Errorf("need selector, ref, or nodeId")++ if err := <-resultCh; err != nil {+ return nil, err+ }+ return map[string]any{"clicked": true, "human": true}, nil}func (b *Bridge) actionScrollIntoView(ctx context.Context, req ActionRequest) (map[string]any, error) {diff --git a/internal/bridge/cdpops/pointer.go b/internal/bridge/cdpops/pointer.goindex 5dc4b7d1..630644af 100644--- a/internal/bridge/cdpops/pointer.go+++ b/internal/bridge/cdpops/pointer.go@@ -75,24 +75,24 @@ func MouseWheelByCoordinate(ctx context.Context, x, y float64, deltaX, deltaY inreturn err}- return chromedp.Run(ctx,- chromedp.ActionFunc(func(ctx context.Context) error {- return chromedp.FromContext(ctx).Target.Execute(ctx, "Input.dispatchMouseEvent", map[string]any{- "type": "mouseMoved",- "x": x,- "y": y,- }, nil)- }),- chromedp.ActionFunc(func(ctx context.Context) error {- return chromedp.FromContext(ctx).Target.Execute(ctx, "Input.dispatchMouseEvent", map[string]any{- "type": "mouseWheel",- "x": x,- "y": y,- "deltaX": deltaX,- "deltaY": deltaY,- }, nil)- }),- )+ // Synthetic Input.dispatchMouseEvent(mouseWheel) in --headless=new no+ // longer reliably fires `wheel` JS listeners and can stall on the+ // compositor ack chain. Dispatch a real WheelEvent at the point under+ // the cursor so listeners run, then scroll the window if no listener+ // called preventDefault().+ expr := fmt.Sprintf(`(function() {+ var dx = %d, dy = %d, cx = %f, cy = %f;+ var target = document.elementFromPoint(cx, cy) || document.documentElement;+ var ev = new WheelEvent('wheel', {+ deltaX: dx, deltaY: dy,+ clientX: cx, clientY: cy,+ bubbles: true, cancelable: true+ });+ if (target.dispatchEvent(ev)) {+ window.scrollBy(dx, dy);+ }+ })()`, deltaX, deltaY, x, y)+ return chromedp.Run(ctx, chromedp.Evaluate(expr, nil))}func ClickByCoordinate(ctx context.Context, x, y float64) error {diff --git a/internal/bridge/input_human.go b/internal/bridge/input_human.goindex 6cde1f4c..d44ed980 100644--- a/internal/bridge/input_human.go+++ b/internal/bridge/input_human.go@@ -3,6 +3,7 @@ package bridgeimport ("context""fmt"+ "log/slog""math""math/rand""time"@@ -13,6 +14,28 @@ import ("github.com/chromedp/chromedp")+// humanMouseStepTimeout caps each per-step Input.dispatchMouseEvent call in+// the bezier-interpolated mouse moves below. Synthetic mouse events through+// CDP can occasionally stall in --headless=new Chromium (the renderer ack+// chain doesn't always complete for fast bursts of synthesized events). A+// 30s outer ActionTimeout used to absorb the whole hang; this bound lets us+// abandon the bezier early and snap to the target so Press/Release still+// fires.+const humanMouseStepTimeout = 500 * time.Millisecond++// dispatchMouseMovedBounded runs Input.dispatchMouseEvent(mouseMoved, x, y)+// with humanMouseStepTimeout, returning ctx.Err() if the outer context was+// cancelled and a synthetic timeout error if just the step exceeded its bound.+func dispatchMouseMovedBounded(ctx context.Context, x, y float64) error {+ stepCtx, cancel := context.WithTimeout(ctx, humanMouseStepTimeout)+ defer cancel()+ return chromedp.Run(stepCtx,+ chromedp.ActionFunc(func(c context.Context) error {+ return input.DispatchMouseEvent(input.MouseMoved, x, y).Do(c)+ }),+ )+}+var humanRand = rand.New(rand.NewSource(time.Now().UnixNano()))func SetHumanRandSeed(seed int64) {@@ -69,12 +92,16 @@ func MouseMove(ctx context.Context, fromX, fromY, toX, toY float64) error {x += (humanRand.Float64() - 0.5) * 2y += (humanRand.Float64() - 0.5) * 2- if err := chromedp.Run(ctx,- chromedp.ActionFunc(func(ctx context.Context) error {- return input.DispatchMouseEvent(input.MouseMoved, x, y).Do(ctx)- }),- ); err != nil {- return err+ if err := dispatchMouseMovedBounded(ctx, x, y); err != nil {+ if ctx.Err() != nil {+ return ctx.Err()+ }+ // Bezier step stalled past the per-step bound. Abandon the+ // rest of the trail and snap to the target so the caller's+ // click can still proceed.+ slog.Debug("humanMove bezier step stalled, snapping to target",+ "step", i, "of", steps, "err", err)+ return dispatchMouseMovedBounded(ctx, toX, toY)}delay := time.Duration(16+humanRand.Intn(8)) * time.Millisecond@@ -85,12 +112,13 @@ func MouseMove(ctx context.Context, fromX, fromY, toX, toY float64) error {for i := 0; i < 2; i++ {jx := toX + (humanRand.Float64()-0.5)*1.2jy := toY + (humanRand.Float64()-0.5)*1.2- if err := chromedp.Run(ctx,- chromedp.ActionFunc(func(ctx context.Context) error {- return input.DispatchMouseEvent(input.MouseMoved, jx, jy).Do(ctx)- }),- ); err != nil {- return err+ if err := dispatchMouseMovedBounded(ctx, jx, jy); err != nil {+ if ctx.Err() != nil {+ return ctx.Err()+ }+ // Jitter stalled β outer ctx still good, just give up on+ // micro-jitter; the bezier already landed us at the target.+ return nil}time.Sleep(10 * time.Millisecond)}@@ -106,16 +134,20 @@ func Click(ctx context.Context, x, y float64) error {distance := math.Sqrt(startOffsetX*startOffsetX + startOffsetY*startOffsetY)if distance > 30 {- if err := chromedp.Run(ctx,- chromedp.ActionFunc(func(ctx context.Context) error {- return input.DispatchMouseEvent(input.MouseMoved, startX, startY).Do(ctx)- }),- ); err != nil {- return err- }-- if err := MouseMove(ctx, startX, startY, x, y); err != nil {- return err+ // Best-effort: the initial random-start move and bezier trail are+ // only there for human-trail realism. If they stall, log and+ // proceed β the subsequent MousePressed sets the cursor at (x,y)+ // explicitly, so the click still lands.+ if err := dispatchMouseMovedBounded(ctx, startX, startY); err != nil {+ if ctx.Err() != nil {+ return ctx.Err()+ }+ slog.Debug("humanClick initial-move stalled, skipping bezier", "err", err)+ } else if err := MouseMove(ctx, startX, startY, x, y); err != nil {+ if ctx.Err() != nil {+ return ctx.Err()+ }+ slog.Debug("humanClick bezier trail failed, proceeding to click", "err", err)}}diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.goindex 265a0e98..321ff632 100644--- a/internal/bridge/runtime/init.go+++ b/internal/bridge/runtime/init.go@@ -127,8 +127,24 @@ func setupAllocator(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooopts = append(opts, chromedp.Flag("hide-scrollbars", true))opts = append(opts, chromedp.Flag("mute-audio", true))opts = append(opts, chromedp.Flag("disable-vulkan", true))+ // Use swiftshader (software GPU) for compositing under --headless=new.+ // We deliberately do NOT pass --disable-gpu here: in new-headless+ // mode Page.captureScreenshot routes through the compositor, which+ // needs a GPU backend β disabling the GPU process leaves the+ // compositor with no backend and screenshot calls hang past the+ // action timeout.opts = append(opts, chromedp.Flag("use-angle", "swiftshader"))- opts = append(opts, chromedp.DisableGPU)+ // Chromium 121+ requires this opt-in to actually load the+ // swiftshader backend; without it, --use-angle=swiftshader is+ // silently ignored and the compositor has no backend, which+ // manifests as Page.captureScreenshot/printToPDF hanging.+ opts = append(opts, chromedp.Flag("enable-unsafe-swiftshader", true))+ // Collapse the GPU process into the browser process. Saves one+ // OS process and ~50-150MB per Chrome instance, and avoids the+ // GPU-process sandbox negotiation in our --no-sandbox containers.+ // Trade-off: a GPU code crash takes the browser with it, but the+ // always-on strategy restarts instances anyway.+ opts = append(opts, chromedp.Flag("in-process-gpu", true))} else {opts = append(opts, chromedp.Flag("headless", false))}diff --git a/scripts/dev-e2e.sh b/scripts/dev-e2e.shnew file mode 100755index 00000000..e402bdc0--- /dev/null+++ b/scripts/dev-e2e.sh@@ -0,0 +1,75 @@+#!/usr/bin/env bash+# dev-e2e.sh β run a single E2E test by name, with a fresh build.+#+# Usage:+# scripts/dev-e2e.sh "<test name substring>"+# scripts/dev-e2e.sh "humanClick: click input by ref"+# scripts/dev-e2e.sh "scroll (down)"+#+# Locates the matching scenario file, infers the suite (api/cli/infra/plugin)+# and whether it's an -extended scenario, then dispatches scripts/e2e.sh with+# the right filter+test arguments. Each compose run of e2e.sh already builds+# fresh images (--build flag), so there's no need for an explicit prune here.++set -euo pipefail++cd "$(dirname "$0")/.."++if [ "$#" -lt 1 ] || [ -z "$1" ]; then+ echo "usage: $0 \"<test name substring>\"" >&2+ echo " Locate a single E2E test by its start_test name and run only that one." >&2+ exit 2+fi++TEST_NAME="$1"++# Match `start_test "..."` lines whose quoted name contains the requested+# substring. fgrep keeps the user's input literal (no regex surprises).+matches=$(grep -rn -F -- "start_test" tests/e2e/scenarios \+ | grep -F -- "${TEST_NAME}" \+ | grep -E '^[^:]+:[0-9]+:[[:space:]]*start_test[[:space:]]+' || true)++if [ -z "${matches}" ]; then+ echo "no test name matches \"${TEST_NAME}\" in tests/e2e/scenarios" >&2+ exit 1+fi++# Use the first match; warn if there are several so the caller can disambiguate.+match_count=$(printf '%s\n' "${matches}" | wc -l | tr -d ' ')+if [ "${match_count}" -gt 1 ]; then+ echo "multiple tests matched \"${TEST_NAME}\":" >&2+ printf '%s\n' "${matches}" | sed 's/^/ /' >&2+ echo "" >&2+ echo "using the first one. Pass a longer/more-specific substring to pick a different test." >&2+ echo "" >&2+fi++scenario_path=$(printf '%s\n' "${matches}" | head -n1 | cut -d: -f1)+scenario_file=$(basename "${scenario_path}")+scenario_dir=$(basename "$(dirname "${scenario_path}")")+scenario_stem="${scenario_file%.sh}"++# Map scenario dir β suite. The scripts/e2e.sh dispatcher accepts api, cli,+# infra, plugin (and their -extended variants); see that file's case statement.+case "${scenario_dir}" in+ api|cli|infra|plugin) suite="${scenario_dir}" ;;+ *)+ echo "unrecognized scenario directory: ${scenario_dir}" >&2+ exit 1+ ;;+esac++# Plugin suite has no extended variant; basic/extended scenarios in api/cli/+# infra map to the corresponding -extended dispatcher entry.+if [ "${suite}" != "plugin" ] && [[ "${scenario_file}" == *-extended.sh ]]; then+ dispatch="${suite}-extended"+else+ dispatch="${suite}"+fi++echo "βΆ test: ${TEST_NAME}"+echo " scenario: ${scenario_path}"+echo " suite: ${dispatch}"+echo ""++exec bash scripts/e2e.sh "${dispatch}" "filter=${scenario_stem}" "test=${TEST_NAME}"diff --git a/scripts/e2e.sh b/scripts/e2e.shindex d57c8831..23b4e816 100755--- a/scripts/e2e.sh+++ b/scripts/e2e.sh@@ -12,6 +12,7 @@ NC=$'\033[0m'# Parse arguments after suiteE2E_FILTER=""+E2E_TEST_FILTER=""E2E_EXTRA=""E2E_LOGS="${E2E_LOGS:-show}"for arg in "${@:2}"; do@@ -19,6 +20,9 @@ for arg in "${@:2}"; dofilter=*)E2E_FILTER="${arg#filter=}";;+ test=*)+ E2E_TEST_FILTER="${arg#test=}"+ ;;extra=*)E2E_EXTRA="${arg#extra=}";;@@ -47,8 +51,13 @@ doneshow_filter_status() {- if [ -n "${E2E_FILTER}" ]; then- echo " ${MUTED}filter: ${E2E_FILTER}${NC}"+ if [ -n "${E2E_FILTER}" ] || [ -n "${E2E_TEST_FILTER}" ]; then+ if [ -n "${E2E_FILTER}" ]; then+ echo " ${MUTED}filter: ${E2E_FILTER}${NC}"+ fi+ if [ -n "${E2E_TEST_FILTER}" ]; then+ echo " ${MUTED}test: ${E2E_TEST_FILTER}${NC}"+ fireturnfi@@ -396,7 +405,7 @@ run_api() {[ -n "${E2E_FILTER}" ] && args+=("filter=${E2E_FILTER}")[ -n "${E2E_EXTRA}" ] && args+=("extra=${E2E_EXTRA}")if [ "${api_exit}" -eq 0 ]; then- run_logged_command "${output_file}" "${progress_file}" "running api suite" compose -f "${compose_file}" run --build --rm runner-api /bin/bash /e2e/run.sh api "${args[@]}"+ run_logged_command "${output_file}" "${progress_file}" "running api suite" compose -f "${compose_file}" run --build --rm -e E2E_TEST_FILTER="${E2E_TEST_FILTER}" runner-api /bin/bash /e2e/run.sh api "${args[@]}"api_exit=$?fiset -e@@ -429,7 +438,7 @@ run_api_extended() {run_logged_command "${output_file}" "" "building support images" build_support_images "${compose_file}"local api_exit=$?if [ "${api_exit}" -eq 0 ]; then- E2E_SUITE=api E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running api extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-api runner-api+ E2E_SUITE=api E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" E2E_TEST_FILTER="${E2E_TEST_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running api extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-api runner-apiapi_exit=$?fiset -e@@ -465,7 +474,7 @@ run_cli() {[ -n "${E2E_FILTER}" ] && args+=("filter=${E2E_FILTER}")[ -n "${E2E_EXTRA}" ] && args+=("extra=${E2E_EXTRA}")if [ "${cli_exit}" -eq 0 ]; then- run_logged_command "${output_file}" "${progress_file}" "running cli suite" compose -f "${compose_file}" run --build --rm runner-cli /bin/bash /e2e/run.sh cli "${args[@]}"+ run_logged_command "${output_file}" "${progress_file}" "running cli suite" compose -f "${compose_file}" run --build --rm -e E2E_TEST_FILTER="${E2E_TEST_FILTER}" runner-cli /bin/bash /e2e/run.sh cli "${args[@]}"cli_exit=$?fiset -e@@ -498,7 +507,7 @@ run_cli_extended() {run_logged_command "${output_file}" "" "building support images" build_support_images "${compose_file}"local cli_exit=$?if [ "${cli_exit}" -eq 0 ]; then- E2E_SUITE=cli E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running cli extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-cli runner-cli+ E2E_SUITE=cli E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" E2E_TEST_FILTER="${E2E_TEST_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running cli extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-cli runner-clicli_exit=$?fiset -e@@ -534,7 +543,7 @@ run_infra() {[ -n "${E2E_FILTER}" ] && args+=("filter=${E2E_FILTER}")[ -n "${E2E_EXTRA}" ] && args+=("extra=${E2E_EXTRA}")if [ "${infra_exit}" -eq 0 ]; then- run_logged_command "${output_file}" "${progress_file}" "running infra suite" compose -f "${compose_file}" run --build --rm runner-api /bin/bash /e2e/run.sh infra "${args[@]}"+ run_logged_command "${output_file}" "${progress_file}" "running infra suite" compose -f "${compose_file}" run --build --rm -e E2E_TEST_FILTER="${E2E_TEST_FILTER}" runner-api /bin/bash /e2e/run.sh infra "${args[@]}"infra_exit=$?fiset -e@@ -567,7 +576,7 @@ run_infra_extended() {run_logged_command "${output_file}" "" "building support images" build_support_images "${compose_file}"local infra_exit=$?if [ "${infra_exit}" -eq 0 ]; then- E2E_SUITE=infra E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running infra extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-api runner-api+ E2E_SUITE=infra E2E_EXTENDED=true E2E_SCENARIO_FILTER="${E2E_FILTER}" E2E_TEST_FILTER="${E2E_TEST_FILTER}" run_logged_command "${output_file}" "${progress_file}" "running infra extended suite" compose -f "${compose_file}" up --build --abort-on-container-exit --exit-code-from runner-api runner-apiinfra_exit=$?fiset -e@@ -648,7 +657,7 @@ run_plugin() {# Plugin suite ignores E2E_FILTER since it only has plugin-basic.sh# and filters like "api-extended" don't make sense for itif [ "${plugin_exit}" -eq 0 ]; then- run_logged_command "${output_file}" "${progress_file}" "running plugin suite" compose -f "${compose_file}" run --build --rm runner-api /bin/bash /e2e/run.sh plugin "${args[@]}"+ run_logged_command "${output_file}" "${progress_file}" "running plugin suite" compose -f "${compose_file}" run --build --rm -e E2E_TEST_FILTER="${E2E_TEST_FILTER}" runner-api /bin/bash /e2e/run.sh plugin "${args[@]}"plugin_exit=$?fiset -ediff --git a/skills/pinchtab-dev/SKILL.md b/skills/pinchtab-dev/SKILL.mdindex 90d3875c..1a43f795 100644--- a/skills/pinchtab-dev/SKILL.md+++ b/skills/pinchtab-dev/SKILL.md@@ -31,6 +31,7 @@ All development commands run via `./dev`:| `./dev e2e pr` | PR suite (api + cli + infra) || `./dev e2e release` | Release suite (all extended) || `./dev e2e docker` | Build local image and Docker smoke test |+| `./dev e2e test "<name>"` | Run a single E2E test by `start_test` name || `./dev doctor` | Setup dev environment |## Architecture@@ -131,9 +132,28 @@ go test ./internal/handlers # Specific package./dev e2e api clipboard # Run only clipboard-basic.sh./dev e2e api-extended "clipboard|console" # Run clipboard and console tests./dev e2e cli browser # Run browser-basic.sh in CLI suite++# Run a single test by its start_test name (fastest debug loop)+./dev e2e test "humanClick: click input by ref"+./dev e2e test "scroll (down)"+./dev e2e test "low-level mouse"```-The filter is a regex pattern matched against scenario filenames. Requires Docker daemon running.+The scenario filter is a substring matched against scenario filenames. Requires Docker daemon running.++#### Single-test mode (`dev e2e test "<name>"`)++Use this when iterating on one specific E2E failure. The runner:++1. Greps `tests/e2e/scenarios/**/*.sh` for `start_test "...<name substring>..."`.+2. Auto-picks the suite (`api`/`cli`/`infra`/`plugin`) and `-extended` variant from the matching scenario file's path.+3. Builds fresh images (`compose ... up --build`) and runs **only the matching `start_test`...`end_test` block** β the scenario preamble (helper sourcing, `FIXTURES_URL`, etc.) is preserved, every other test in the file is skipped.++Notes:+- The substring is literal (fgrep), so colons/parens/quotes in test names work without escaping.+- If multiple tests match, the runner uses the first and prints the others β pass a longer/more-specific substring to disambiguate.+- Logs stream to the terminal by default (unlike full suites which hide logs); helpful for debugging.+- Implemented by `scripts/dev-e2e.sh` + `E2E_TEST_FILTER` plumbing through `scripts/e2e.sh` and `tests/e2e/run.sh`.### Dashboard Tests```bashdiff --git a/tests/e2e/docker-compose-multi.yml b/tests/e2e/docker-compose-multi.ymlindex 757270cf..f4b4f685 100644--- a/tests/e2e/docker-compose-multi.yml+++ b/tests/e2e/docker-compose-multi.yml@@ -196,6 +196,7 @@ services:- E2E_BRIDGE_TOKEN=e2e-bridge-token- FIXTURES_URL=http://fixtures:80- E2E_SCENARIO_FILTER+ - E2E_TEST_FILTER- E2E_SUITE- E2E_EXTENDED- STEALTH_MATRIXdiff --git a/tests/e2e/docker-compose.yml b/tests/e2e/docker-compose.ymlindex bce60498..a2680464 100644--- a/tests/e2e/docker-compose.yml+++ b/tests/e2e/docker-compose.yml@@ -64,6 +64,7 @@ services:- E2E_SERVER_TOKEN=e2e-token- FIXTURES_URL=http://fixtures:80- E2E_SCENARIO_FILTER+ - E2E_TEST_FILTER- E2E_SUITE- STEALTH_MATRIXvolumes:@@ -85,6 +86,7 @@ services:- E2E_SERVER_TOKEN=e2e-token- FIXTURES_URL=http://fixtures:80- E2E_SCENARIO_FILTER+ - E2E_TEST_FILTER- E2E_SUITE- E2E_EXTENDEDvolumes:diff --git a/tests/e2e/run.sh b/tests/e2e/run.shindex d971b3c0..d11379ff 100644--- a/tests/e2e/run.sh+++ b/tests/e2e/run.sh@@ -218,6 +218,9 @@ if [ "$SUITE_KIND" = "api" ]; thenif [ -n "$SCENARIO_FILTER" ]; thenecho "FILTER: ${SCENARIO_FILTER}"fi+ if [ -n "${E2E_TEST_FILTER:-}" ]; then+ echo "TEST: ${E2E_TEST_FILTER}"+ fiif [ -n "$EXTRA_SCENARIOS" ]; thenecho "EXTRA: ${EXTRA_SCENARIOS}"fi@@ -255,6 +258,9 @@ elseif [ -n "$SCENARIO_FILTER" ]; thenecho " Filter: $SCENARIO_FILTER"fi+ if [ -n "${E2E_TEST_FILTER:-}" ]; then+ echo " Test: ${E2E_TEST_FILTER}"+ fiif [ -n "$EXTRA_SCENARIOS" ]; thenecho " Extra: $EXTRA_SCENARIOS"fi@@ -276,6 +282,53 @@ elseecho ""fi+# When E2E_TEST_FILTER is set, source only scenario preamble + matching+# start_test...end_test blocks. Lets a single test run end-to-end with the+# scenario's setup intact, no per-helper guards needed.+TEST_FILTER="${E2E_TEST_FILTER:-}"++source_filtered_scenario() {+ local script_path="$1"+ local pattern="$2"+ local script_dir+ script_dir="$(dirname "${script_path}")"+ # The scenarios dir may be read-only (runner mounts ./:/e2e:ro), so we+ # write the filtered tempfile to /tmp. Scenarios resolve helper paths+ # via `GROUP_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)`, which+ # would point at /tmp from the tempfile β so we strip that line and+ # pre-set GROUP_DIR to the original scenario directory instead.+ # BusyBox mktemp (Alpine) needs the XXXXXX at the end of TEMPLATE β no+ # trailing extension. Use an explicit /tmp path so behaviour is consistent+ # across GNU and BusyBox.+ local tmp+ tmp=$(mktemp /tmp/e2e-scenario.XXXXXX)+ printf 'GROUP_DIR=%q\n' "${script_dir}" > "${tmp}"+ awk -v want="${pattern}" '+ BEGIN { preamble=1; in_test=0; capture=0; matched=0 }+ /^[[:space:]]*GROUP_DIR=.*BASH_SOURCE/ { next }+ /^[[:space:]]*start_test[[:space:]]/ {+ preamble=0+ in_test=1+ name=$0+ sub(/^[[:space:]]*start_test[[:space:]]+/, "", name)+ gsub(/^["'\'']|["'\'']$/, "", name)+ if (index(name, want) > 0) { capture=1; matched=1 } else { capture=0 }+ }+ preamble || (in_test && capture) { print }+ /^[[:space:]]*end_test[[:space:]]*$/ && in_test { in_test=0; capture=0 }+ END { exit matched ? 0 : 2 }+ ' "${script_path}" >> "${tmp}"+ local awk_status=$?+ if [ "${awk_status}" -eq 2 ]; then+ rm -f "${tmp}"+ return 2+ fi+ # shellcheck disable=SC1090+ source "${tmp}"+ rm -f "${tmp}"+ return 0+}+# Run scenariosfor script_name in "${SCENARIO_GROUPS[@]}"; doscript_path="${GROUP_DIR}/${script_name}"@@ -291,7 +344,13 @@ for script_name in "${SCENARIO_GROUPS[@]}"; doecho -e "${YELLOW}Running: ${script_name}${NC}"echo ""CURRENT_SCENARIO_FILE="${script_name%.sh}"- source "${script_path}"+ if [ -n "${TEST_FILTER}" ]; then+ if ! source_filtered_scenario "${script_path}" "${TEST_FILTER}"; then+ echo -e "${MUTED} no matching test in ${script_name}${NC}"+ fi+ else+ source "${script_path}"+ fiecho ""if [ -d "${RESULTS_DIR:-}" ] && [ -n "${E2E_PROGRESS_FILE:-}" ]; thendiff --git a/tests/e2e/runner-api/Dockerfile b/tests/e2e/runner-api/Dockerfileindex 34a38a15..050f0e57 100644--- a/tests/e2e/runner-api/Dockerfile+++ b/tests/e2e/runner-api/Dockerfile@@ -1,4 +1,4 @@-FROM alpine:3.19+FROM alpine:3.23RUN apk add --no-cache \bash \diff --git a/tests/e2e/runner-cli/Dockerfile b/tests/e2e/runner-cli/Dockerfileindex f820d90b..75987b6b 100644--- a/tests/e2e/runner-cli/Dockerfile+++ b/tests/e2e/runner-cli/Dockerfile@@ -19,7 +19,7 @@ COPY . .RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/pinchtab ./cmd/pinchtab# ββ Runner image ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ-FROM alpine:3.21+FROM alpine:3.23RUN apk add --no-cache \bash \diff --git a/tests/e2e/scenarios/api/files-basic.sh b/tests/e2e/scenarios/api/files-basic.shindex 7fe0d1ad..3b593912 100644--- a/tests/e2e/scenarios/api/files-basic.sh+++ b/tests/e2e/scenarios/api/files-basic.sh@@ -26,6 +26,9 @@ end_test# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββstart_test "pinchtab screenshot --tab <id>"+pt_post /navigate -d "{\"url\":\"${FIXTURES_URL}/table.html\"}"+sleep 1+pt_get /tabsTAB_ID=$(get_first_tab)