Skip to content

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/Dockerfile
index 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.23
LABEL org.opencontainers.image.source="https://github.com/pinchtab/pinchtab"
LABEL org.opencontainers.image.description="High-performance browser automation bridge"
diff --git a/dev b/dev
index 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 ]; then
fi
;;
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"
+ fi
if [ $# -eq 1 ] || [[ "${2:-}" == *=* ]]; then
exec env E2E_LOGS="${E2E_LOGS:-hide}" bash scripts/e2e.sh release "${@:2}"
fi
diff --git a/internal/assets/stealth.js b/internal/assets/stealth.js
index 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.go
index 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.go
index 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 in
return 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.go
index 6cde1f4c..d44ed980 100644
--- a/internal/bridge/input_human.go
+++ b/internal/bridge/input_human.go
@@ -3,6 +3,7 @@ package bridge
import (
"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) * 2
y += (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.2
jy := 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.go
index 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 Hoo
opts = 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.sh
new file mode 100755
index 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.sh
index d57c8831..23b4e816 100755
--- a/scripts/e2e.sh
+++ b/scripts/e2e.sh
@@ -12,6 +12,7 @@ NC=$'\033[0m'
# Parse arguments after suite
E2E_FILTER=""
+E2E_TEST_FILTER=""
E2E_EXTRA=""
E2E_LOGS="${E2E_LOGS:-show}"
for arg in "${@:2}"; do
@@ -19,6 +20,9 @@ for arg in "${@:2}"; do
filter=*)
E2E_FILTER="${arg#filter=}"
;;
+ test=*)
+ E2E_TEST_FILTER="${arg#test=}"
+ ;;
extra=*)
E2E_EXTRA="${arg#extra=}"
;;
@@ -47,8 +51,13 @@ done
show_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}"
+ fi
return
fi
@@ -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=$?
fi
set -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-api
api_exit=$?
fi
set -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=$?
fi
set -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-cli
cli_exit=$?
fi
set -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=$?
fi
set -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-api
infra_exit=$?
fi
set -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 it
if [ "${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=$?
fi
set -e
diff --git a/skills/pinchtab-dev/SKILL.md b/skills/pinchtab-dev/SKILL.md
index 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
```bash
diff --git a/tests/e2e/docker-compose-multi.yml b/tests/e2e/docker-compose-multi.yml
index 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_MATRIX
diff --git a/tests/e2e/docker-compose.yml b/tests/e2e/docker-compose.yml
index 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_MATRIX
volumes:
@@ -85,6 +86,7 @@ services:
- E2E_SERVER_TOKEN=e2e-token
- FIXTURES_URL=http://fixtures:80
- E2E_SCENARIO_FILTER
+ - E2E_TEST_FILTER
- E2E_SUITE
- E2E_EXTENDED
volumes:
diff --git a/tests/e2e/run.sh b/tests/e2e/run.sh
index d971b3c0..d11379ff 100644
--- a/tests/e2e/run.sh
+++ b/tests/e2e/run.sh
@@ -218,6 +218,9 @@ if [ "$SUITE_KIND" = "api" ]; then
if [ -n "$SCENARIO_FILTER" ]; then
echo "FILTER: ${SCENARIO_FILTER}"
fi
+ if [ -n "${E2E_TEST_FILTER:-}" ]; then
+ echo "TEST: ${E2E_TEST_FILTER}"
+ fi
if [ -n "$EXTRA_SCENARIOS" ]; then
echo "EXTRA: ${EXTRA_SCENARIOS}"
fi
@@ -255,6 +258,9 @@ else
if [ -n "$SCENARIO_FILTER" ]; then
echo " Filter: $SCENARIO_FILTER"
fi
+ if [ -n "${E2E_TEST_FILTER:-}" ]; then
+ echo " Test: ${E2E_TEST_FILTER}"
+ fi
if [ -n "$EXTRA_SCENARIOS" ]; then
echo " Extra: $EXTRA_SCENARIOS"
fi
@@ -276,6 +282,53 @@ else
echo ""
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 scenarios
for script_name in "${SCENARIO_GROUPS[@]}"; do
script_path="${GROUP_DIR}/${script_name}"
@@ -291,7 +344,13 @@ for script_name in "${SCENARIO_GROUPS[@]}"; do
echo -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}"
+ fi
echo ""
if [ -d "${RESULTS_DIR:-}" ] && [ -n "${E2E_PROGRESS_FILE:-}" ]; then
diff --git a/tests/e2e/runner-api/Dockerfile b/tests/e2e/runner-api/Dockerfile
index 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.23
RUN apk add --no-cache \
bash \
diff --git a/tests/e2e/runner-cli/Dockerfile b/tests/e2e/runner-cli/Dockerfile
index 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.23
RUN apk add --no-cache \
bash \
diff --git a/tests/e2e/scenarios/api/files-basic.sh b/tests/e2e/scenarios/api/files-basic.sh
index 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 /tabs
TAB_ID=$(get_first_tab)