Skip to content

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

chore: refine e2e runner boundary and humanized input

Luigi Agosti9b5fe5055bb4
diff --git a/TESTING.md b/TESTING.md
index ef157820..058a227f 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -47,6 +47,23 @@ End-to-end tests launch a real pinchtab server with Chrome and run e2e-level tes
- **cli** — CLI command tests
- **infra** — System, network, security, stealth, orchestration
+### E2E Boundary
+
+The Go runner is the execution boundary for E2E. `go run ./tests/tools/runner e2e ...` owns suite expansion, scenario discovery, manifest metadata, compose service selection, readiness waits, container arguments, host Docker smoke checks, logs, reports, failure accounting, and GitHub Actions outputs. Scenario files and helpers own the actual assertions and API or CLI interactions.
+
+`tests/e2e/scenarios/manifest.json` is metadata, not a scenario list. It only overrides tier, helper, required compose services, readiness targets, and tags. Filename suffixes provide the default tier: `*-basic.sh` is `basic`, `*-smoke.sh` is `smoke`, and every other scenario is `extended`.
+
+Tier meanings:
+- `basic` is the fast PR happy path
+- `extended` is deeper coverage and includes matching `basic` scenarios
+- `smoke` is separate high-setup coverage and does not include `basic` or `extended`
+
+Add new scenarios under `tests/e2e/scenarios/<group>/`, choose the tier by filename, add manifest metadata only for non-default service/readiness/helper/tags, and verify selection with `go run ./tests/tools/runner e2e --suite <suite> --filter <name> --dry-run`.
+
+`--filter` is a case-sensitive scenario selector over file name, manifest key, group, tier, helper, and tags. It runs before compose planning, so unmatched suites are skipped and only required services start. `--test` is narrower: it runs one matching `start_test` block inside the already-selected scenarios.
+
+CI uses `.github/workflows/reusable-e2e.yml` and `.github/workflows/reusable-smoke.yml`, both calling the Go runner directly. The workflow layer decides when to run; the Go layer decides what to run and how to report it.
+
### Basic Suites
```bash
@@ -164,7 +181,7 @@ The runner clears the target suite files before each run so stale results do not
## Writing New E2E Tests
-Add new coverage directly to a grouped entrypoint in `tests/e2e/scenarios/api/`, `tests/e2e/scenarios/cli/`, or `tests/e2e/scenarios/infra/`. Keep `*-basic.sh` focused on the happy path and put the extra and edge-case coverage in the matching `*-extended.sh`.
+Add new coverage directly to a grouped entrypoint in `tests/e2e/scenarios/api/`, `tests/e2e/scenarios/cli/`, `tests/e2e/scenarios/infra/`, or `tests/e2e/scenarios/plugin/`. Keep `*-basic.sh` focused on the PR happy path, put deeper coverage in the matching `*-extended.sh`, and put slow/high-setup checks in `*-smoke.sh`. Add manifest metadata only when the scenario needs non-default services, readiness targets, helper, tier, or tags.
### Example: Grouped API Entrypoint
diff --git a/dev b/dev
index fe1eb0f6..12105113 100755
--- a/dev
+++ b/dev
@@ -29,11 +29,11 @@ COMMANDS=(
" basic:🐳:Basic suite (api + cli + infra)"
" extended:🐳:Extended suite (all extended)"
" smoke:🐳:Smoke suite"
- " docker:🐳:Docker smoke suite"
+ " smoke-docker:🐳:Host Docker smoke checks only"
" api:🐳:API basic tests"
" cli:🐳:CLI basic tests"
" infra:🐳:Infra basic tests"
- " plugin:🐳:Plugin smoke tests"
+ " plugin:🐳:Plugin tests"
" api-extended:🐳:API extended (multi-instance)"
" cli-extended:🐳:CLI extended tests"
" infra-extended:🐳:Infra extended (multi-instance)"
@@ -229,26 +229,6 @@ run_command() {
echo ""
exec bash scripts/test.sh system
;;
- "e2e docker")
- echo " ${ACCENT}${BOLD}💨 Docker smoke test${NC}"
- echo ""
- run_e2e_runner smoke-docker
- ;;
- "e2e docker "*)
- local docker_args="${target#e2e docker }"
- if [[ "$docker_args" == --* || "$docker_args" == *=* ]]; then
- echo " ${ACCENT}${BOLD}💨 Docker smoke test${NC}"
- echo ""
- read -r -a e2e_docker_args <<< "$docker_args"
- run_e2e_runner smoke-docker "${e2e_docker_args[@]}"
- else
- local image="$docker_args"
- echo " ${ACCENT}${BOLD}💨 Docker smoke test${NC}"
- echo ""
- export PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE="$image"
- run_e2e_runner smoke-docker --filter release
- fi
- ;;
"opt")
echo " ${ACCENT}${BOLD}⚡ Optimization${NC}"
echo ""
@@ -418,17 +398,6 @@ if [ $# -gt 0 ]; then
echo ""
exec env E2E_LOGS="${E2E_LOGS:-show}" bash scripts/dev-e2e.sh "$3"
fi
- if [ "${2:-}" = "docker" ]; then
- if [ $# -gt 2 ]; then
- if [[ "${3:-}" == --* || "${3:-}" == *=* ]]; then
- run_e2e_runner smoke-docker "${@:3}"
- else
- export PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE="$3"
- run_e2e_runner smoke-docker --filter release "${@:4}"
- fi
- fi
- run_e2e_runner smoke-docker
- fi
run_e2e_runner "${@:2}"
;;
binary)
diff --git a/docs/commands.md b/docs/commands.md
index 41b63dc3..48f03e22 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -32,6 +32,8 @@ pinchtab forward # Go forward in the active tab
pinchtab reload # Reload the active tab
```
+Use `--tab <id>` when you intend to replace an existing tab's URL. Unscoped reads and actions use the current tracked tab, but unscoped `nav` intentionally opens a new tab to avoid replacing active work by accident.
+
Hidden aliases: `goto`, `navigate`, `open`
## Tabs
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 81a79b7b..de3c5caa 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -182,6 +182,16 @@ Action targeting fields:
- `deltaX` and `deltaY`
- `waitNav`
- `dialogAction` and `dialogText`
+- `humanize`
+
+`humanize` is a per-action override for input style. When omitted, actions use `instanceDefaults.humanize`, which defaults to `false`. Use `kind:"click"` or `kind:"type"` with `humanize:true` when a page needs the slower human-like pointer or typing path.
+
+Pointer fallback behavior:
+
+- `mouse-move` first attempts a real CDP `mouseMoved` event.
+- If headless Chromium stalls that move waiting for renderer acknowledgement, PinchTab falls back to DOM `mouseover`/`mouseenter`/`mousemove` events at the same target so hover-style checks remain responsive.
+- Non-timeout CDP errors and caller context cancellation are not hidden by the fallback.
+- `mouse-wheel` dispatches a DOM `WheelEvent` at the target point and scrolls the window when the event is not cancelled.
Selector lookup is limited to the current frame scope. The default scope is `main`. Use `/frame` or `/tabs/{id}/frame` before selector-based iframe actions. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.
diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md
index 62c6b8a4..2f9d74e4 100644
--- a/docs/guides/contributing.md
+++ b/docs/guides/contributing.md
@@ -245,9 +245,10 @@ go test ./... # Unit tests only
go test ./... -v # Verbose
go test ./... -v -coverprofile=coverage.out
go tool cover -html=coverage.out # View coverage
-./dev e2e # Run the default E2E release suite
-./dev e2e docker # Build the local image and run Docker smoke
-./dev e2e pr # Run API + CLI + Infra basic tests
+./dev e2e # Run the default extended E2E suite
+./dev e2e basic # Run API + CLI + Infra basic tests
+./dev e2e smoke # Run smoke scenarios + host Docker smoke checks
+./dev e2e smoke-docker # Run host Docker smoke checks only
./dev e2e api # Run API basic tests
./dev e2e cli # Run CLI basic tests
./dev e2e infra # Run Infra basic tests
@@ -282,16 +283,16 @@ All dev scripts are accessible through `./dev`:
| `test` | Run all tests |
| `test unit` | Unit tests only |
| `test dashboard` | Dashboard tests only |
-| `e2e` | Run the default E2E release suite (all extended tests) |
-| `e2e docker` | Build the local image and run the Docker smoke test |
-| `e2e pr` | Run the PR E2E suite (`api` + `cli` + `infra` basic tests) |
+| `e2e` | Run the default extended E2E suite |
+| `e2e basic` | Run the PR E2E suite (`api` + `cli` + `infra` basic tests) |
+| `e2e smoke` | Run smoke scenarios plus host Docker smoke checks |
+| `e2e smoke-docker` | Run only host Docker smoke checks |
| `e2e api` | Run API basic tests |
| `e2e cli` | Run CLI basic tests |
| `e2e infra` | Run Infra basic tests |
| `e2e api-extended` | Run API extended tests (multi-instance) |
| `e2e cli-extended` | Run CLI extended tests |
| `e2e infra-extended` | Run Infra extended tests (multi-instance) |
-| `e2e release` | Run the release E2E meta-suite (all extended) |
| `build` | Build the application |
| `dev` | Build and run the application |
| `run` | Run the application |
@@ -373,7 +374,7 @@ Run automatically on pull requests and/or push to `main`:
| **CI / Dashboard** | PR + push (dashboard paths) | TypeScript, ESLint, Prettier, tests, build |
| **CI / Docs** | PR + push (docs paths) | docs.json reference validation |
| **CI / npm** | PR (npm paths) + tag push | npm package verification |
-| **CI / E2E** | PR (fast suites) + manual (full suites) | Docker-based end-to-end tests |
+| **CI / E2E** | PR basic suites + manual extended/smoke suites | Docker-based end-to-end tests |
| **CI / Branch Naming** | PR | Branch name convention enforcement |
### Release Pipeline
@@ -383,7 +384,7 @@ Run automatically on pull requests and/or push to `main`:
| **Release** | Manual | Runs all checks + E2E → manual approval gate → creates tag → publishes binaries, npm, Docker, and skill |
| **Release / Manual Publish** | Manual | Publishes an existing tag as a recovery path |
-In **Release**, E2E and Docker smoke failures are non-blocking — they surface
+In **Release**, E2E and smoke failures are non-blocking — they surface
in the approval summary so you can decide whether to proceed. Core checks (Go, Dashboard,
Docs, npm, publish dry-run) must pass for the approval gate to appear.
diff --git a/docs/reference/click.md b/docs/reference/click.md
index 027b1249..65260289 100644
--- a/docs/reference/click.md
+++ b/docs/reference/click.md
@@ -47,6 +47,7 @@ pinchtab click --x 100 --y 200 # Click at coordinates
- Use [`/frame`](./frame.md) before selector-based iframe actions
- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) first for dynamic UI
- The API also accepts `selector` field: `{"kind":"click","selector":"#login"}`
+- Raw input is the default. To opt a click into the slower humanized path for a page that needs it, pass `humanize:true` in the action JSON or set `instanceDefaults.humanize:true`.
## Related Pages
diff --git a/docs/reference/config.md b/docs/reference/config.md
index 0e31cb00..4be1f488 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -172,6 +172,7 @@ Current nested file-config shape:
"maxParallelTabs": 0,
"userAgent": "",
"noAnimations": false,
+ "humanize": false,
"stealthLevel": "light",
"tabEvictionPolicy": "close_lru",
"tabPolicy": {
@@ -368,6 +369,17 @@ You can change or clear that default with `browser.extensionPaths`.
`instanceDefaults.tabEvictionPolicy` is still accepted for compatibility. New configs should use `instanceDefaults.tabPolicy.eviction`.
+### Humanized Input
+
+`instanceDefaults.humanize` controls whether click and typing actions use the slower humanized path by default. The default is `false`, which keeps automation fast and deterministic by using raw CDP input.
+
+Callers can override the instance default per action with the JSON field `humanize`:
+
+- `{"kind":"click","selector":"#submit","humanize":true}` opts a single action into bezier mouse movement and human-like delays.
+- `{"kind":"type","selector":"#name","text":"Ada","humanize":true}` opts a single type action into the slower per-character path.
+
+Rationale: humanized input is useful for compatibility with pages that react poorly to raw input, but it adds sleeps and multi-step pointer movement. Keeping it opt-in prevents accidental seconds of overhead in default E2E and agent runs.
+
## Sections
| Section | Purpose |
diff --git a/docs/reference/mouse.md b/docs/reference/mouse.md
index c11daf36..278c499d 100644
--- a/docs/reference/mouse.md
+++ b/docs/reference/mouse.md
@@ -47,6 +47,7 @@ Notes:
- `mouse wheel` accepts either a delta form (`<dy> [--dx <n>]`) or an optional selector. Without a selector, it uses the current pointer position.
- `drag <from> <to>` accepts selector/ref targets or `x,y` coordinate pairs.
- `button` supports `left`, `right`, and `middle`.
+- Pointer move uses a bounded CDP `mouseMoved` dispatch first. If headless Chromium stalls that dispatch, PinchTab falls back to DOM mouse events so hover and mouse-move flows remain responsive.
## HTTP API
@@ -124,8 +125,12 @@ curl -X POST http://localhost:9867/tabs/<tabId>/action \
- POST coordinate bodies work with plain `x` and `y`; no extra `hasXY` flag is required.
- `mouse-down`, `mouse-up`, and `mouse-wheel` use per-tab current-pointer state when you omit a fresh target.
-- If no current pointer position is known yet, `mouse-down`, `mouse-up`, and `mouse-wheel` fail with a clear error. Use `mouse-move` first or pass an explicit target.
+- If no current pointer position is known yet, `mouse-down` and `mouse-up` fail with a clear error. Use `mouse-move` first or pass an explicit target.
+- If no current pointer position is known yet, `mouse-wheel` and page `scroll` use the viewport center as a deterministic fallback.
- `mouse-wheel` defaults to vertical scrolling when only `deltaY` is provided.
+- The CDP-to-DOM move fallback only handles renderer acknowledgement timeouts. Other CDP errors and caller cancellation are returned to the caller.
+
+Rationale: low-level pointer actions are often used in hover menus, drag handles, and canvas-like controls where a five-second headless mouse-move stall makes a simple check look like a suite timeout. The fallback keeps these flows fast, while still surfacing real CDP errors.
## Related Pages
diff --git a/docs/reference/navigate.md b/docs/reference/navigate.md
index 98f6bc90..465edadd 100644
--- a/docs/reference/navigate.md
+++ b/docs/reference/navigate.md
@@ -48,6 +48,15 @@ pinchtab nav https://example.com --block-images # Skip images
| `waitFor` | Wait condition |
| `waitSelector` | Wait for selector |
+## Behavior
+
+- Top-level `POST /navigate` and `pinchtab nav <url>` open a new tab when no `tabId` or `--tab` is provided.
+- `POST /tabs/{id}/navigate`, `POST /navigate` with `tabId`, and `pinchtab nav <url> --tab <id>` reuse the specified tab and make it the current tab for later unscoped operations.
+- `--new-tab` and `newTab:true` force a new tab even if another tab is current.
+- Commands that operate without `--tab` use the current tracked tab. Focusing or using a tab updates that current-tab pointer; if the pointer is stale, PinchTab falls back to the most recently used tracked tab.
+
+Rationale: unscoped navigation should not accidentally replace the user or agent's active work surface. Reuse is explicit through `--tab`/`tabId`, while later unscoped read/action commands still have predictable current-tab behavior.
+
## Related Pages
- [Snapshot](./snapshot.md)
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index b9287a45..a22747dc 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -114,6 +114,10 @@ pinchtab tab close 8f9c7d4e1234... # close tab
Numeric arguments are resolved as 1-based indices against `GET /tabs`. Non-numeric arguments are treated as tab IDs.
+Focusing, creating, navigating, or otherwise accessing a tracked tab marks it as the current tab. Unscoped commands use that current tab; if the recorded current tab has gone stale, PinchTab falls back to the most recently used tracked tab.
+
+Top-level navigation is intentionally different from unscoped reads/actions: `pinchtab nav <url>` opens a new tab unless you pass `--tab <id>`. This keeps new navigations from replacing an existing work surface by accident.
+
## Operate On An Existing Tab
Use the tab-scoped HTTP route or the top-level CLI command with `--tab`.
diff --git a/docs/reference/type.md b/docs/reference/type.md
index ac56a76b..119d56a8 100644
--- a/docs/reference/type.md
+++ b/docs/reference/type.md
@@ -27,6 +27,7 @@ OK
- Use [`/frame`](./frame.md) before iframe typing
- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) for async fields
- For typing into focused element, use `keyboard type`
+- Raw keyboard input is the default. To opt a type action into the slower humanized per-character path, pass `humanize:true` in the action JSON or set `instanceDefaults.humanize:true`.
## Related Pages
diff --git a/go-e2e.md b/go-e2e.md
index 0f939aea..4c7f80ed 100644
--- a/go-e2e.md
+++ b/go-e2e.md
@@ -1,5 +1,8 @@
# Go E2E Runner Plan
+> Historical implementation plan. The canonical operating contract now lives in
+> `TESTING.md` and `tests/e2e/README.md`.
+
## Goal
Extend `tests/tools/runner` so one Go command can support both the existing benchmark/optimization runner and a deterministic e2e runner.
@@ -15,7 +18,7 @@ Implemented through host orchestration and explicit scenario selection:
- `internal/e2e` owns suite parsing, Docker Compose lifecycle, suite matrix, log mode, captured output logs, summary/report generation, failure artifacts, and exact scenario file selection.
- `tests/e2e/run.sh` accepts explicit `scenario=<file>` arguments and acts as the in-container executor. It has no scenario discovery, filter fallback, or durable report writing.
- The old `scripts/e2e.sh` host dispatcher and e2e aliases are removed.
-- Smoke suites are wired through the Go runner. Initial infra smoke coverage lives in `orchestrator-smoke.sh` and `security-smoke.sh`; lifecycle/docker smoke splits remain follow-up work.
+- Smoke suites are wired through the Go runner. Infra smoke coverage includes orchestrator, security, autosolver, dashboard, lifecycle, and host Docker smoke checks.
## Target Commands
diff --git a/internal/bridge/action_pointer.go b/internal/bridge/action_pointer.go
index 8eed8547..65bf8da9 100644
--- a/internal/bridge/action_pointer.go
+++ b/internal/bridge/action_pointer.go
@@ -23,11 +23,8 @@ var mouseUpByCoordinateAction = MouseUpByCoordinate
// 2. Per-instance default: bridge Config.Humanize
// 3. Built-in default: false
//
-// The action kind is intentionally NOT consulted — both click/type and
-// humanClick/humanType honour the same resolution. This means
-// `kind: humanClick` defaults to raw input unless config.humanize=true
-// or the request explicitly sets humanize:true; callers who relied on
-// the legacy auto-humanizing behaviour need to opt in.
+// The action kind is intentionally NOT consulted. The public API uses
+// click/type with humanize=true instead of separate humanized action names.
func (b *Bridge) effectiveHumanize(req ActionRequest) bool {
if req.Humanize != nil {
return *req.Humanize
@@ -108,10 +105,9 @@ func submitFormIfButton(ctx context.Context, selector string) (bool, error) {
func (b *Bridge) actionClick(ctx context.Context, req ActionRequest) (map[string]any, error) {
// Promote to the humanized click path when the caller (or instance
- // config) opted in via humanize=true. The guard on req.Kind avoids
- // ping-ponging when actionHumanClick has already delegated here.
- if req.Kind != ActionHumanClick && b.effectiveHumanize(req) {
- return b.actionHumanClick(ctx, req)
+ // config) opted in via humanize=true.
+ if b.effectiveHumanize(req) {
+ return b.actionHumanizedClick(ctx, req)
}
// Arm a one-shot dialog auto-handler if the caller expects the click
@@ -463,15 +459,7 @@ func (b *Bridge) actionDrag(ctx context.Context, req ActionRequest) (map[string]
return nil, fmt.Errorf("need selector, ref, or nodeId")
}
-func (b *Bridge) actionHumanClick(ctx context.Context, req ActionRequest) (map[string]any, error) {
- // Fall through to the raw click path when humanization is disabled.
- // `kind: humanClick` is preserved as an action name for back-compat,
- // but its bezier+sleeps semantics now require humanize=true (either
- // per-request or via instance config).
- if !b.effectiveHumanize(req) {
- return b.actionClick(ctx, req)
- }
-
+func (b *Bridge) actionHumanizedClick(ctx context.Context, req ActionRequest) (map[string]any, error) {
var backendNodeID cdp.BackendNodeID
switch {
case req.NodeID > 0:
@@ -486,7 +474,7 @@ func (b *Bridge) actionHumanClick(ctx context.Context, req ActionRequest) (map[s
return nil, fmt.Errorf("need selector, ref, or nodeId")
}
- // Run the multi-step humanClick (bezier mouse-move + press + release) in
+ // Run the multi-step humanized click (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.
diff --git a/internal/bridge/action_registry.go b/internal/bridge/action_registry.go
index ed4d48b3..ab684239 100644
--- a/internal/bridge/action_registry.go
+++ b/internal/bridge/action_registry.go
@@ -15,8 +15,6 @@ const (
ActionMouseUp = "mouse-up"
ActionMouseWheel = "mouse-wheel"
ActionDrag = "drag"
- ActionHumanClick = "humanClick"
- ActionHumanType = "humanType"
ActionCheck = "check"
ActionUncheck = "uncheck"
ActionKeyboardType = "keyboard-type"
@@ -42,8 +40,6 @@ func (b *Bridge) InitActionRegistry() {
ActionMouseUp: b.actionMouseUp,
ActionMouseWheel: b.actionMouseWheel,
ActionDrag: b.actionDrag,
- ActionHumanClick: b.actionHumanClick,
- ActionHumanType: b.actionHumanType,
ActionCheck: b.actionCheck,
ActionUncheck: b.actionUncheck,
ActionKeyboardType: b.actionKeyboardType,
diff --git a/internal/bridge/action_text.go b/internal/bridge/action_text.go
index aee37970..9d9137eb 100644
--- a/internal/bridge/action_text.go
+++ b/internal/bridge/action_text.go
@@ -11,6 +11,9 @@ func (b *Bridge) actionType(ctx context.Context, req ActionRequest) (map[string]
if req.Text == "" {
return nil, fmt.Errorf("text required for type")
}
+ if b.effectiveHumanize(req) {
+ return b.actionHumanizedType(ctx, req)
+ }
if req.Selector != "" {
return map[string]any{"typed": req.Text}, chromedp.Run(ctx,
chromedp.Click(req.Selector, chromedp.ByQuery),
@@ -47,15 +50,9 @@ func (b *Bridge) actionPress(ctx context.Context, req ActionRequest) (map[string
return map[string]any{"pressed": req.Key}, DispatchNamedKey(ctx, req.Key)
}
-func (b *Bridge) actionHumanType(ctx context.Context, req ActionRequest) (map[string]any, error) {
+func (b *Bridge) actionHumanizedType(ctx context.Context, req ActionRequest) (map[string]any, error) {
if req.Text == "" {
- return nil, fmt.Errorf("text required for humanType")
- }
-
- // Fall through to the raw keyboard path when humanization is disabled.
- // Mirrors the actionHumanClick → actionClick fallback.
- if !b.effectiveHumanize(req) {
- return b.actionKeyboardType(ctx, req)
+ return nil, fmt.Errorf("text required for type")
}
if req.Selector != "" {
@@ -63,7 +60,7 @@ func (b *Bridge) actionHumanType(ctx context.Context, req ActionRequest) (map[st
return nil, err
}
} else if req.NodeID > 0 {
- // req.NodeID is a BackendNodeID from the accessibility tree (same as humanClick).
+ // req.NodeID is a BackendNodeID from the accessibility tree.
// Must use DOM.focus with backendNodeId, not dom.Focus().WithNodeID() which
// expects a DOM NodeID — a different ID space. Using the wrong type causes
// "Could not find node with given id (-32000)". See issue #226.
@@ -92,11 +89,9 @@ func (b *Bridge) actionKeyboardType(ctx context.Context, req ActionRequest) (map
return nil, fmt.Errorf("text required for keyboard-type")
}
- // Promote to the humanized typing path when humanize=true was opted
- // into. Guard on req.Kind so actionHumanType's delegation doesn't
- // bounce back here.
- if req.Kind != ActionHumanType && b.effectiveHumanize(req) {
- return b.actionHumanType(ctx, req)
+ // Promote to the humanized typing path when humanize=true was opted into.
+ if b.effectiveHumanize(req) {
+ return b.actionHumanizedType(ctx, req)
}
// For long strings, use insertText to avoid timeout (issue #413).
diff --git a/internal/bridge/actions_test.go b/internal/bridge/actions_test.go
index 88749222..c462b30f 100644
--- a/internal/bridge/actions_test.go
+++ b/internal/bridge/actions_test.go
@@ -277,6 +277,145 @@ func TestActionRequestUnmarshal_UsesCanonicalMouseFields(t *testing.T) {
}
}
+func boolPtr(v bool) *bool {
+ return &v
+}
+
+func TestEffectiveHumanizePrecedence(t *testing.T) {
+ tests := []struct {
+ name string
+ config *config.RuntimeConfig
+ req ActionRequest
+ want bool
+ justifying string
+ }{
+ {
+ name: "default false",
+ config: &config.RuntimeConfig{},
+ want: false,
+ justifying: "raw input remains the fast default",
+ },
+ {
+ name: "config true",
+ config: &config.RuntimeConfig{Humanize: true},
+ want: true,
+ justifying: "instance default opt-in enables humanized input",
+ },
+ {
+ name: "request true overrides config false",
+ config: &config.RuntimeConfig{Humanize: false},
+ req: ActionRequest{Humanize: boolPtr(true)},
+ want: true,
+ justifying: "per-request override can opt in",
+ },
+ {
+ name: "request false overrides config true",
+ config: &config.RuntimeConfig{Humanize: true},
+ req: ActionRequest{Humanize: boolPtr(false)},
+ want: false,
+ justifying: "per-request override can force raw input",
+ },
+ {
+ name: "nil bridge config defaults false",
+ config: nil,
+ want: false,
+ justifying: "nil config stays safe and fast",
+ },
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ b := &Bridge{Config: tc.config}
+ if got := b.effectiveHumanize(tc.req); got != tc.want {
+ t.Fatalf("effectiveHumanize = %v, want %v (%s)", got, tc.want, tc.justifying)
+ }
+ })
+ }
+}
+
+func TestRemovedHumanActionKindsAreUnknown(t *testing.T) {
+ b := New(context.TODO(), nil, &config.RuntimeConfig{})
+
+ for _, kind := range []string{"humanClick", "humanType"} {
+ t.Run(kind, func(t *testing.T) {
+ _, err := b.ExecuteAction(context.Background(), kind, ActionRequest{Kind: kind, Text: "hi"})
+ if err == nil {
+ t.Fatalf("expected %s to be rejected", kind)
+ }
+ if !strings.Contains(err.Error(), "unknown action") {
+ t.Fatalf("expected unknown action error for %s, got: %v", kind, err)
+ }
+ })
+ }
+}
+
+func TestClickAction_HumanizeOptInUsesHumanizedPath(t *testing.T) {
+ raw := New(context.TODO(), nil, &config.RuntimeConfig{Humanize: true})
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+
+ _, err := raw.Actions[ActionClick](ctx, ActionRequest{
+ Kind: ActionClick,
+ Humanize: boolPtr(false),
+ HasXY: true,
+ X: 10,
+ Y: 20,
+ })
+ if err == nil {
+ t.Fatal("expected cancelled raw coordinate click to fail")
+ }
+ if strings.Contains(err.Error(), "need selector") {
+ t.Fatalf("humanize=false should force raw click coordinate path, got: %v", err)
+ }
+
+ humanized := New(context.TODO(), nil, &config.RuntimeConfig{})
+ _, err = humanized.Actions[ActionClick](context.Background(), ActionRequest{
+ Kind: ActionClick,
+ Humanize: boolPtr(true),
+ HasXY: true,
+ X: 10,
+ Y: 20,
+ })
+ if err == nil {
+ t.Fatal("expected humanized coordinate-only click to fail")
+ }
+ if !strings.Contains(err.Error(), "need selector") {
+ t.Fatalf("humanized click should require selector/ref/nodeId, got: %v", err)
+ }
+}
+
+func TestTypeAction_HumanizeOptInUsesHumanizedPath(t *testing.T) {
+ raw := New(context.TODO(), nil, &config.RuntimeConfig{Humanize: true})
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+
+ _, err := raw.Actions[ActionType](ctx, ActionRequest{
+ Kind: ActionType,
+ Selector: "#name",
+ Text: "hi",
+ Humanize: boolPtr(false),
+ })
+ if err == nil {
+ t.Fatal("expected cancelled raw type to fail")
+ }
+ if strings.Contains(err.Error(), "need selector") {
+ t.Fatalf("humanize=false should force raw type path, got: %v", err)
+ }
+
+ humanized := New(context.TODO(), nil, &config.RuntimeConfig{})
+ _, err = humanized.Actions[ActionType](context.Background(), ActionRequest{
+ Kind: ActionType,
+ Text: "hi",
+ Humanize: boolPtr(true),
+ })
+ if err == nil {
+ t.Fatal("expected humanized targetless type to fail")
+ }
+ if !strings.Contains(err.Error(), "need selector, ref, or nodeId") {
+ t.Fatalf("humanized type should require selector/ref/nodeId, got: %v", err)
+ }
+}
+
func TestScrollAction_UsesCoordinateWheelPath(t *testing.T) {
b := New(context.TODO(), nil, &config.RuntimeConfig{})
diff --git a/internal/bridge/bridge_test.go b/internal/bridge/bridge_test.go
index ac41913e..45ee8be5 100644
--- a/internal/bridge/bridge_test.go
+++ b/internal/bridge/bridge_test.go
@@ -271,6 +271,39 @@ func TestTabContext_EmptyID_UsesCurrentTrackedTab(t *testing.T) {
}
}
+func TestSelectCurrentTrackedTabFallsBackToMostRecentlyUsed(t *testing.T) {
+ tm := NewTabManager(context.Background(), &config.RuntimeConfig{}, nil, nil, nil)
+ now := time.Now()
+
+ tm.tabs["older"] = &TabEntry{Ctx: context.Background(), CreatedAt: now.Add(-3 * time.Minute), LastUsed: now.Add(-2 * time.Minute)}
+ tm.tabs["newer"] = &TabEntry{Ctx: context.Background(), CreatedAt: now.Add(-2 * time.Minute), LastUsed: now.Add(-1 * time.Minute)}
+ tm.currentTab = "stale-tab-id"
+
+ if got := tm.selectCurrentTrackedTab(); got != "newer" {
+ t.Fatalf("selectCurrentTrackedTab = %q, want most recently used tab", got)
+ }
+}
+
+func TestMarkAccessedUpdatesCurrentTabAndLastUsed(t *testing.T) {
+ tm := NewTabManager(context.Background(), &config.RuntimeConfig{}, nil, nil, nil)
+ oldTime := time.Now().Add(-1 * time.Hour)
+ tm.tabs["tab1"] = &TabEntry{Ctx: context.Background(), CreatedAt: oldTime, LastUsed: oldTime}
+ tm.tabs["tab2"] = &TabEntry{Ctx: context.Background(), CreatedAt: oldTime, LastUsed: oldTime}
+ tm.currentTab = "tab1"
+
+ tm.markAccessed("tab2")
+
+ if tm.currentTab != "tab2" {
+ t.Fatalf("currentTab = %q, want tab2", tm.currentTab)
+ }
+ if !tm.accessed["tab2"] {
+ t.Fatal("expected tab2 to be marked accessed")
+ }
+ if !tm.tabs["tab2"].LastUsed.After(oldTime) {
+ t.Fatalf("tab2 LastUsed = %v, want after %v", tm.tabs["tab2"].LastUsed, oldTime)
+ }
+}
+
func TestCloseTab_PreventsLastTabClose(t *testing.T) {
// CloseTab should fail when attempting to close the last remaining tab
// This prevents Chrome from exiting and crashing the server
diff --git a/internal/bridge/cdpops/pointer.go b/internal/bridge/cdpops/pointer.go
index e48f7c04..e04ba9c4 100644
--- a/internal/bridge/cdpops/pointer.go
+++ b/internal/bridge/cdpops/pointer.go
@@ -54,8 +54,14 @@ func dispatchRealMouseMove(ctx context.Context, x, y float64, button input.Mouse
}))
}
+var (
+ dispatchRealMouseMoveFunc = dispatchRealMouseMove
+ dispatchSyntheticMouseMoveFunc = dispatchSyntheticMouseMove
+ dispatchSyntheticMouseMoveOnNodeFunc = dispatchSyntheticMouseMoveOnNode
+)
+
func dispatchMouseMove(ctx context.Context, x, y float64, button input.MouseButton, buttons int64) error {
- err := dispatchRealMouseMove(ctx, x, y, button, buttons)
+ err := dispatchRealMouseMoveFunc(ctx, x, y, button, buttons)
if err == nil {
return nil
}
@@ -65,11 +71,11 @@ func dispatchMouseMove(ctx context.Context, x, y float64, button input.MouseButt
if !errors.Is(err, context.DeadlineExceeded) {
return err
}
- return dispatchSyntheticMouseMove(ctx, x, y, button, buttons)
+ return dispatchSyntheticMouseMoveFunc(ctx, x, y, button, buttons)
}
func dispatchMouseMoveToNode(ctx context.Context, nodeID int64, x, y float64, button input.MouseButton, buttons int64) error {
- err := dispatchRealMouseMove(ctx, x, y, button, buttons)
+ err := dispatchRealMouseMoveFunc(ctx, x, y, button, buttons)
if err == nil {
return nil
}
@@ -79,7 +85,7 @@ func dispatchMouseMoveToNode(ctx context.Context, nodeID int64, x, y float64, bu
if !errors.Is(err, context.DeadlineExceeded) {
return err
}
- return dispatchSyntheticMouseMoveOnNode(ctx, nodeID, button, buttons)
+ return dispatchSyntheticMouseMoveOnNodeFunc(ctx, nodeID, button, buttons)
}
func dispatchSyntheticMouseMove(ctx context.Context, x, y float64, button input.MouseButton, buttons int64) error {
diff --git a/internal/bridge/cdpops/pointer_test.go b/internal/bridge/cdpops/pointer_test.go
new file mode 100644
index 00000000..5e2723c7
--- /dev/null
+++ b/internal/bridge/cdpops/pointer_test.go
@@ -0,0 +1,119 @@
+package cdpops
+
+import (
+ "context"
+ "errors"
+ "testing"
+
+ "github.com/chromedp/cdproto/input"
+)
+
+func TestDispatchMouseMoveFallsBackToSyntheticOnDeadline(t *testing.T) {
+ origReal := dispatchRealMouseMoveFunc
+ origSynthetic := dispatchSyntheticMouseMoveFunc
+ t.Cleanup(func() {
+ dispatchRealMouseMoveFunc = origReal
+ dispatchSyntheticMouseMoveFunc = origSynthetic
+ })
+
+ dispatchRealMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ return context.DeadlineExceeded
+ }
+
+ called := false
+ dispatchSyntheticMouseMoveFunc = func(_ context.Context, x, y float64, button input.MouseButton, buttons int64) error {
+ called = true
+ if x != 12 || y != 34 {
+ t.Fatalf("synthetic move coordinates = (%v, %v), want (12, 34)", x, y)
+ }
+ if button != input.Left || buttons != 1 {
+ t.Fatalf("synthetic move button state = (%v, %d), want (%v, 1)", button, buttons, input.Left)
+ }
+ return nil
+ }
+
+ if err := dispatchMouseMove(context.Background(), 12, 34, input.Left, 1); err != nil {
+ t.Fatalf("dispatchMouseMove returned error: %v", err)
+ }
+ if !called {
+ t.Fatal("expected synthetic fallback to run")
+ }
+}
+
+func TestDispatchMouseMoveDoesNotFallbackOnNonDeadlineError(t *testing.T) {
+ origReal := dispatchRealMouseMoveFunc
+ origSynthetic := dispatchSyntheticMouseMoveFunc
+ t.Cleanup(func() {
+ dispatchRealMouseMoveFunc = origReal
+ dispatchSyntheticMouseMoveFunc = origSynthetic
+ })
+
+ want := errors.New("cdp failed")
+ dispatchRealMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ return want
+ }
+ dispatchSyntheticMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ t.Fatal("synthetic fallback should not run for non-timeout CDP errors")
+ return nil
+ }
+
+ if err := dispatchMouseMove(context.Background(), 12, 34, input.None, 0); !errors.Is(err, want) {
+ t.Fatalf("dispatchMouseMove error = %v, want %v", err, want)
+ }
+}
+
+func TestDispatchMouseMoveContextCancellationWinsOverFallback(t *testing.T) {
+ origReal := dispatchRealMouseMoveFunc
+ origSynthetic := dispatchSyntheticMouseMoveFunc
+ t.Cleanup(func() {
+ dispatchRealMouseMoveFunc = origReal
+ dispatchSyntheticMouseMoveFunc = origSynthetic
+ })
+
+ dispatchRealMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ return context.DeadlineExceeded
+ }
+ dispatchSyntheticMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ t.Fatal("synthetic fallback should not run after caller context cancellation")
+ return nil
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+
+ if err := dispatchMouseMove(ctx, 12, 34, input.None, 0); !errors.Is(err, context.Canceled) {
+ t.Fatalf("dispatchMouseMove error = %v, want context.Canceled", err)
+ }
+}
+
+func TestDispatchMouseMoveToNodeFallsBackToSyntheticNodeMove(t *testing.T) {
+ origReal := dispatchRealMouseMoveFunc
+ origSyntheticNode := dispatchSyntheticMouseMoveOnNodeFunc
+ t.Cleanup(func() {
+ dispatchRealMouseMoveFunc = origReal
+ dispatchSyntheticMouseMoveOnNodeFunc = origSyntheticNode
+ })
+
+ dispatchRealMouseMoveFunc = func(context.Context, float64, float64, input.MouseButton, int64) error {
+ return context.DeadlineExceeded
+ }
+
+ called := false
+ dispatchSyntheticMouseMoveOnNodeFunc = func(_ context.Context, nodeID int64, button input.MouseButton, buttons int64) error {
+ called = true
+ if nodeID != 42 {
+ t.Fatalf("nodeID = %d, want 42", nodeID)
+ }
+ if button != input.Right || buttons != 2 {
+ t.Fatalf("button state = (%v, %d), want (%v, 2)", button, buttons, input.Right)
+ }
+ return nil
+ }
+
+ if err := dispatchMouseMoveToNode(context.Background(), 42, 12, 34, input.Right, 2); err != nil {
+ t.Fatalf("dispatchMouseMoveToNode returned error: %v", err)
+ }
+ if !called {
+ t.Fatal("expected synthetic node fallback to run")
+ }
+}
diff --git a/internal/bridge/input_human.go b/internal/bridge/input_human.go
index d44ed980..737b20f5 100644
--- a/internal/bridge/input_human.go
+++ b/internal/bridge/input_human.go
@@ -142,12 +142,12 @@ func Click(ctx context.Context, x, y float64) error {
if ctx.Err() != nil {
return ctx.Err()
}
- slog.Debug("humanClick initial-move stalled, skipping bezier", "err", err)
+ slog.Debug("humanized click 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)
+ slog.Debug("humanized click bezier trail failed, proceeding to click", "err", err)
}
}
diff --git a/internal/handlers/actions.go b/internal/handlers/actions.go
index 52c20515..85b50b82 100644
--- a/internal/handlers/actions.go
+++ b/internal/handlers/actions.go
@@ -137,7 +137,7 @@ func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {
return
}
h.recordActionRequest(r, req)
- if !h.shouldUseLiteAction(req.Kind) {
+ if !h.shouldUseLiteAction(req) {
if available := h.Bridge.AvailableActions(); len(available) > 0 {
known := false
for _, k := range available {
@@ -154,7 +154,7 @@ func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {
}
// Resolve tab — skip for lite actions (lite engine manages its own tabs)
- useLiteAction := h.shouldUseLiteAction(req.Kind)
+ useLiteAction := h.shouldUseLiteAction(req)
var resolvedTabID string
var ctx context.Context
if useLiteAction {
@@ -529,8 +529,16 @@ func (h *Handlers) HandleTabActions(w http.ResponseWriter, r *http.Request) {
// handleActionsBatch processes a batch of actions (used by both single and batch endpoints)
func (h *Handlers) handleActionsBatch(w http.ResponseWriter, r *http.Request, req actionsRequest) {
- // Check if the first action is lite-routable to decide tab resolution strategy
+ // Use lite tab resolution only when every action can stay on the lite path.
allLite := h.Router != nil && h.Router.Mode() == engine.ModeLite
+ if allLite {
+ for _, action := range req.Actions {
+ if !h.shouldUseLiteAction(action) {
+ allLite = false
+ break
+ }
+ }
+ }
var ctx context.Context
var resolvedTabID string
owner := resolveOwner(r, req.Owner)
@@ -589,7 +597,7 @@ func (h *Handlers) handleActionsBatch(w http.ResponseWriter, r *http.Request, re
}
tCtx, tCancel := context.WithTimeout(ctx, h.Config.ActionTimeout)
- useLiteAction := h.shouldUseLiteAction(action.Kind)
+ useLiteAction := h.shouldUseLiteAction(action)
// Unified selector resolution for batch actions.
action.NormalizeSelector()
@@ -870,6 +878,14 @@ func (h *Handlers) HandleMacro(w http.ResponseWriter, r *http.Request) {
}
allLiteMacro := h.Router != nil && h.Router.Mode() == engine.ModeLite
+ if allLiteMacro {
+ for _, step := range req.Steps {
+ if !h.shouldUseLiteAction(step) {
+ allLiteMacro = false
+ break
+ }
+ }
+ }
var ctx context.Context
var resolvedTabID string
if allLiteMacro {
@@ -905,7 +921,7 @@ func (h *Handlers) HandleMacro(w http.ResponseWriter, r *http.Request) {
continue
}
}
- useLiteAction := h.shouldUseLiteAction(step.Kind)
+ useLiteAction := h.shouldUseLiteAction(step)
// Unified selector resolution for macro steps (mirrors HandleAction).
step.NormalizeSelector()
stepRefMissing := false
@@ -1178,7 +1194,7 @@ func (h *Handlers) cacheActionIntent(tabID string, req bridge.ActionRequest) {
func (h *Handlers) executeAction(ctx context.Context, req bridge.ActionRequest) (map[string]any, string, error) {
req.Kind = bridge.CanonicalActionKind(req.Kind)
- if h.shouldUseLiteAction(req.Kind) {
+ if h.shouldUseLiteAction(req) {
return h.executeLiteAction(ctx, req)
}
@@ -1189,8 +1205,11 @@ func (h *Handlers) executeAction(ctx context.Context, req bridge.ActionRequest)
return result, "", err
}
-func (h *Handlers) shouldUseLiteAction(kind string) bool {
- kind = bridge.CanonicalActionKind(kind)
+func (h *Handlers) shouldUseLiteAction(req bridge.ActionRequest) bool {
+ kind := bridge.CanonicalActionKind(req.Kind)
+ if h.effectiveActionHumanize(req) && (kind == bridge.ActionClick || kind == bridge.ActionType || kind == bridge.ActionKeyboardType) {
+ return false
+ }
capability, ok := actionCapability(kind)
if !ok {
return h.Router != nil && h.Router.Mode() == engine.ModeLite
@@ -1198,6 +1217,16 @@ func (h *Handlers) shouldUseLiteAction(kind string) bool {
return h.useLite(capability, "")
}
+func (h *Handlers) effectiveActionHumanize(req bridge.ActionRequest) bool {
+ if req.Humanize != nil {
+ return *req.Humanize
+ }
+ if h != nil && h.Config != nil {
+ return h.Config.Humanize
+ }
+ return false
+}
+
func (h *Handlers) executeLiteAction(ctx context.Context, req bridge.ActionRequest) (map[string]any, string, error) {
if h.Router == nil || h.Router.Lite() == nil {
return nil, "", fmt.Errorf("lite engine unavailable")
diff --git a/scripts/README.md b/scripts/README.md
index db918692..eb1339c0 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -25,7 +25,8 @@ Development and CI scripts for PinchTab.
| `build-dashboard.sh` | Generate TS types (tygo) + build React dashboard + copy to Go embed |
| `autosolver-realworld-smoke.sh` | Smoke-test real-world autosolver flow against an external detection page |
| `dev.sh` | Full build (dashboard + Go) and run |
-| `docker-smoke.sh` | Smoke-test a Docker image bootstrap path (defaults to `pinchtab-local:test`) |
+| `dev-e2e.sh` | Lookup wrapper for `./dev e2e test`; delegates execution to the Go E2E runner |
+| `docker-smoke.sh` | Host Docker smoke helper invoked by the Go E2E runner |
| `npm-dev-binary.sh` | Build the canonical `./pinchtab-dev` binary for source-checkout npm-package testing |
| `run.sh` | Run the existing `./pinchtab` binary |
@@ -46,5 +47,5 @@ Development and CI scripts for PinchTab.
## `./dev` shortcuts
- `./dev e2e smoke` runs the smoke tier through the Go e2e runner, including host Docker smoke checks.
-- `./dev e2e docker` runs only the host Docker smoke suite through the Go e2e runner.
-- `./dev e2e docker <image>` skips the release-image build and runs the release-image Docker smoke checks against the specified image tag.
+- `./dev e2e smoke-docker` runs only the host Docker smoke suite through the Go e2e runner.
+- `PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE=<image> ./dev e2e smoke-docker --filter release` skips the release-image build and runs the release-image Docker smoke checks against the specified image tag.
diff --git a/scripts/dev-e2e.sh b/scripts/dev-e2e.sh
index 906f8d98..9fa8b36e 100755
--- a/scripts/dev-e2e.sh
+++ b/scripts/dev-e2e.sh
@@ -1,14 +1,14 @@
#!/usr/bin/env bash
-# dev-e2e.sh — run a single E2E test by name, with a fresh build.
+# dev-e2e.sh — locate one start_test block, then delegate to the Go E2E runner.
#
# Usage:
# scripts/dev-e2e.sh "<test name substring>"
-# scripts/dev-e2e.sh "humanClick: click input by ref"
+# scripts/dev-e2e.sh "click with humanize"
# 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 the Go e2e runner
-# with the right filter+test arguments.
+# This script is a convenience lookup wrapper, not an execution boundary. The
+# Go runner still owns suite planning, compose services, logs, reports, and
+# scenario execution.
set -euo pipefail
@@ -57,9 +57,11 @@ case "${scenario_dir}" in
;;
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
+# Smoke is a separate tier across groups; the smoke meta-suite plus the
+# scenario filename filter selects the matching group.
+if [[ "${scenario_file}" == *-smoke.sh ]]; then
+ dispatch="smoke"
+elif [ "${suite}" != "plugin" ] && [[ "${scenario_file}" == *-extended.sh ]]; then
dispatch="${suite}-extended"
else
dispatch="${suite}"
diff --git a/smoke-e2e.md b/smoke-e2e.md
index 260f327b..2fc54eea 100644
--- a/smoke-e2e.md
+++ b/smoke-e2e.md
@@ -1,5 +1,8 @@
# Smoke E2E Plan
+> Historical implementation plan. The canonical operating contract now lives in
+> `TESTING.md` and `tests/e2e/README.md`.
+
## Goal
Create a proper slow smoke lane so default e2e stays fast, while expensive topology and lifecycle tests remain easy to run deliberately.
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
index 85317694..f5b2cc24 100644
--- a/tests/e2e/README.md
+++ b/tests/e2e/README.md
@@ -30,6 +30,75 @@ go run ./tests/tools/runner e2e --suite smoke-docker
go run ./tests/tools/runner e2e --suite infra-extended --filter orchestrator
```
+## E2E System Boundary
+
+The E2E system has three layers with separate responsibilities. Keep this boundary explicit when adding scenarios or refactoring the runner.
+
+### Go Runner
+
+`go run ./tests/tools/runner e2e ...` is the host-side orchestrator. It owns:
+
+- Suite normalization and expansion (`basic`, `extended`, `smoke`, group suites, and filtered smoke suites)
+- Scenario discovery from `tests/e2e/scenarios/*/*.sh`
+- Applying `tests/e2e/scenarios/manifest.json` metadata
+- Selecting the compose stack, compose services, and readiness targets
+- Passing explicit `scenario=<file>` arguments into the container executor
+- Host Docker smoke checks and their required image build steps
+- Log capture, result cleanup, summaries, markdown reports, failure accounting, GitHub Actions outputs, and GitHub Actions summaries
+
+The runner does not own test assertions, endpoint request details, or CLI command behavior inside a scenario. Those stay in scenario files and helpers.
+
+### Manifest
+
+`tests/e2e/scenarios/manifest.json` is metadata, not the test list. Shell files are still discovered from disk. The manifest only controls per-scenario overrides:
+
+- `tier`: `basic`, `extended`, or `smoke`
+- `helper`: `api` or `cli`
+- `services`: compose services required by the scenario
+- `ready`: readiness targets required before the scenario runs
+- `tags`: filter labels
+
+By default, tier comes from the filename suffix: `*-basic.sh` is `basic`, `*-smoke.sh` is `smoke`, and every other scenario is `extended`. The default helper is `cli` for `scenarios/cli/` and `api` for the other groups. The default services are `pinchtab` and `fixtures`.
+
+### Tiers
+
+- `basic` is the PR happy path: fast, representative coverage with small setup. `./dev e2e basic` runs the API, CLI, and Infra basic suites.
+- `extended` is deeper coverage: edge cases, detailed interaction checks, and tests that are useful before release. Extended suites include the matching `basic` scenarios plus `extended` scenarios for that group.
+- `smoke` is independent high-setup coverage: lifecycle, multi-instance, host Docker, and production-like checks that do not belong in PR flow. `./dev e2e smoke` runs only `*-smoke.sh` scenarios plus host Docker smoke checks; it does not include `basic` or `extended`.
+
+### Adding A Scenario
+
+1. Add or update a grouped entrypoint under `tests/e2e/scenarios/api/`, `tests/e2e/scenarios/cli/`, `tests/e2e/scenarios/infra/`, or `tests/e2e/scenarios/plugin/`.
+2. Pick the tier by filename: `feature-basic.sh`, `feature-extended.sh`, or `feature-smoke.sh`.
+3. Source the local helper, usually `../../helpers/api.sh` or `../../helpers/cli.sh`.
+4. Add a manifest entry only when the scenario needs non-default services, readiness targets, helper, tier, or tags.
+5. Check the plan before running the full suite:
+
+```bash
+go run ./tests/tools/runner e2e --suite basic --dry-run
+go run ./tests/tools/runner e2e --suite extended --filter feature --dry-run
+go run ./tests/tools/runner e2e --suite smoke --filter feature --dry-run
+```
+
+### Filtering
+
+`--filter TEXT` selects scenario files before compose planning. It is a case-sensitive substring match against the scenario file name, manifest key, group, tier, helper, and tags. Suites with no matching scenarios are skipped, and the runner only starts services required by the remaining scenarios.
+
+For host Docker smoke checks, `--filter` matches the smoke step name or tags; required image build steps are included automatically when a filtered step depends on them.
+
+`--test TEXT` is different: it does not select scenario files or compose services. It passes `E2E_TEST_FILTER` into the container so `run.sh` can run one matching `start_test` block inside the already-selected scenarios.
+
+### CI Path
+
+CI uses the Go runner directly:
+
+- `.github/workflows/reusable-e2e.yml` runs `go run ./tests/tools/runner e2e --suite <suite> --logs hide`
+- `.github/workflows/reusable-smoke.yml` runs `go run ./tests/tools/runner e2e --suite smoke --logs hide`
+- `.github/workflows/ci-e2e.yml` chooses PR, extended-on-touch, manual, and smoke jobs, then delegates execution to the reusable workflows
+- `.github/workflows/ci-smoke.yml` is the manual smoke entrypoint
+
+Workflow YAML should stay thin: it decides when to run suites, while scenario selection, services, logs, reports, failure summaries, and GitHub Actions outputs stay in the Go layer.
+
## Architecture
```
@@ -138,10 +207,12 @@ Compose usage:
## Adding Tests
-1. Add or update a grouped entrypoint such as `tabs-basic.sh` or `tabs-extended.sh`
+1. Add or update a grouped entrypoint such as `tabs-basic.sh`, `tabs-extended.sh`, or `tabs-smoke.sh`
2. Source `../../helpers/api.sh` or `../../helpers/cli.sh`
-3. Put the happy path in `*-basic.sh` and the extra/edge cases in `*-extended.sh`
-4. Use the assertion helpers:
+3. Put PR happy-path coverage in `*-basic.sh`, deeper coverage in `*-extended.sh`, and slow/high-setup checks in `*-smoke.sh`
+4. Add or update `scenarios/manifest.json` only when the scenario needs non-default services, readiness targets, helper, tier, or tags
+5. Verify selection and service scope with `go run ./tests/tools/runner e2e --suite <suite> --filter <name> --dry-run`
+6. Use the assertion helpers:
```bash
#!/bin/bash
@@ -225,8 +296,9 @@ docker compose -f tests/e2e/docker-compose.yml run runner-cli bash
### Run specific scenario
```bash
-docker compose -f tests/e2e/docker-compose.yml run runner-api /bin/bash /e2e/scenarios/api/tabs-basic.sh
-docker compose -f tests/e2e/docker-compose-multi.yml run runner-api /bin/bash /e2e/scenarios/api/tabs-extended.sh
+go run ./tests/tools/runner e2e --suite api --filter tabs-basic
+go run ./tests/tools/runner e2e --suite api-extended --filter tabs-extended
+go run ./tests/tools/runner e2e --suite api-extended --filter tabs-extended --test "tab-scoped snapshot"
```
### Orchestrator Coverage
diff --git a/tests/e2e/helpers/api-actions.sh b/tests/e2e/helpers/api-actions.sh
index 7c7a4728..c2a366dd 100644
--- a/tests/e2e/helpers/api-actions.sh
+++ b/tests/e2e/helpers/api-actions.sh
@@ -1,5 +1,5 @@
#!/bin/bash
-# api-actions.sh — Action helpers (click, type, humanClick, humanType)
+# api-actions.sh — Action helpers for click/type variants.
#
# Higher-level wrappers around pt_post /action for readable tests.
@@ -28,33 +28,30 @@ action_type() {
assert_ok "type '$text' into ref=$ref"
}
-# Human-like click by ref (uses mouse events).
-# Sets humanize=true explicitly: with the new opt-in default, kind=humanClick
-# alone falls through to a raw click. These helpers exist specifically to
-# exercise the bezier+jitter+pre-press-sleep path, so we always opt in.
-# Usage: action_human_click "$ref"
-action_human_click() {
+# Humanized click by ref (uses mouse events).
+# Usage: action_click_humanized "$ref"
+action_click_humanized() {
local ref="$1"
- pt_post /action -d "{\"kind\":\"humanClick\",\"ref\":\"$ref\",\"humanize\":true}" > /dev/null
- assert_ok "humanClick ref=$ref"
+ pt_post /action -d "{\"kind\":\"click\",\"ref\":\"$ref\",\"humanize\":true}" > /dev/null
+ assert_ok "humanized click ref=$ref"
}
-# Human-like type by ref (character-by-character key events).
-# Usage: action_human_type "$ref" "hello"
-action_human_type() {
+# Humanized type by ref (character-by-character key events).
+# Usage: action_type_humanized "$ref" "hello"
+action_type_humanized() {
local ref="$1"
local text="$2"
- pt_post /action -d "{\"kind\":\"humanType\",\"ref\":\"$ref\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
- assert_ok "humanType '$text' into ref=$ref"
+ pt_post /action -d "{\"kind\":\"type\",\"ref\":\"$ref\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
+ assert_ok "humanized type '$text' into ref=$ref"
}
-# Human-like type by CSS selector.
-# Usage: action_human_type_selector "#email" "hello"
-action_human_type_selector() {
+# Humanized type by CSS selector.
+# Usage: action_type_humanized_selector "#email" "hello"
+action_type_humanized_selector() {
local selector="$1"
local text="$2"
- pt_post /action -d "{\"kind\":\"humanType\",\"selector\":\"$selector\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
- assert_ok "humanType '$text' into $selector"
+ pt_post /action -d "{\"kind\":\"type\",\"selector\":\"$selector\",\"text\":\"$text\",\"humanize\":true}" > /dev/null
+ assert_ok "humanized type '$text' into $selector"
}
# Navigate to a fixture page and wait for load.
diff --git a/tests/e2e/nginx/default.conf b/tests/e2e/nginx/default.conf
index 740d2815..f35c347a 100644
--- a/tests/e2e/nginx/default.conf
+++ b/tests/e2e/nginx/default.conf
@@ -27,7 +27,7 @@ server {
}
# SSRF test target: always redirects to a private/internal IP. Used by
- # files-basic / files-full "redirected internal target blocked" tests
+ # files-basic / files-extended "redirected internal target blocked" tests
# to verify the download handler blocks redirects to internal hosts
# without needing a parameterized target (which would require nginx
# to URL-decode query args, something stock nginx can't do).
diff --git a/tests/e2e/run.sh b/tests/e2e/run.sh
index 8ee3a43a..a99f2b23 100644
--- a/tests/e2e/run.sh
+++ b/tests/e2e/run.sh
@@ -1,5 +1,5 @@
#!/bin/bash
-# run.sh - Run grouped E2E scenarios for a suite directory.
+# run.sh - Container executor for explicit E2E scenario files.
set -uo pipefail
diff --git a/tests/e2e/scenarios/api/actions-extended.sh b/tests/e2e/scenarios/api/actions-extended.sh
index 1be1fd8f..518c5e43 100644
--- a/tests/e2e/scenarios/api/actions-extended.sh
+++ b/tests/e2e/scenarios/api/actions-extended.sh
@@ -142,22 +142,22 @@ assert_json_contains "$RESULT" '.result' 'mouseup' "sequence includes mouseup"
end_test
# ─────────────────────────────────────────────────────────────────
-start_test "humanClick: click input by ref"
+start_test "click with humanize: click input by ref"
navigate_fixture "human-type.html"
fresh_snapshot
require_ref "textbox" "Email" EMAIL_REF && \
- action_human_click "$EMAIL_REF"
+ action_click_humanized "$EMAIL_REF"
end_test
# ─────────────────────────────────────────────────────────────────
-start_test "humanType: type into input by ref"
+start_test "type with humanize: type into input by ref"
fresh_snapshot
require_ref "textbox" "Email" EMAIL_REF && {
- action_human_type "$EMAIL_REF" "[email protected]"
+ action_type_humanized "$EMAIL_REF" "[email protected]"
fresh_snapshot
assert_value "textbox" "Email" "[email protected]"
@@ -166,11 +166,11 @@ require_ref "textbox" "Email" EMAIL_REF && {
end_test
# ─────────────────────────────────────────────────────────────────
-start_test "humanType: type into second input by ref"
+start_test "type with humanize: type into second input by ref"
fresh_snapshot
require_ref "textbox" "Name" NAME_REF && {
- action_human_type "$NAME_REF" "John Doe"
+ action_type_humanized "$NAME_REF" "John Doe"
fresh_snapshot
assert_value "textbox" "Name" "John Doe"
@@ -179,9 +179,9 @@ require_ref "textbox" "Name" NAME_REF && {
end_test
# ─────────────────────────────────────────────────────────────────
-start_test "humanType: type with CSS selector"
+start_test "type with humanize: type with CSS selector"
-action_human_type_selector "#name" " Jr."
+action_type_humanized_selector "#name" " Jr."
end_test
diff --git a/tests/e2e/scenarios/infra/network-extended.sh b/tests/e2e/scenarios/infra/network-extended.sh
index f95cdb55..30a2d11a 100755
--- a/tests/e2e/scenarios/infra/network-extended.sh
+++ b/tests/e2e/scenarios/infra/network-extended.sh
@@ -382,7 +382,7 @@ fi
end_test
# ─────────────────────────────────────────────────────────────────
-# Network basics (moved from browser-full for grouping)
+# Network basics kept with network coverage for grouping
# ─────────────────────────────────────────────────────────────────
start_test "GET /network: list entries with filters"
diff --git a/tests/e2e/scenarios/infra/stealth-basic.sh b/tests/e2e/scenarios/infra/stealth-basic.sh
index 321dc2c6..41458a4d 100644
--- a/tests/e2e/scenarios/infra/stealth-basic.sh
+++ b/tests/e2e/scenarios/infra/stealth-basic.sh
@@ -121,7 +121,7 @@ assert_eval_poll "window.innerHeight === ${ROTATE_HEIGHT}" "true" "rotated viewp
end_test
# Tests the core stealth invariants from GitHub issue #275.
-# This is the API fast-suite bot scenario.
+# This is the basic-suite bot scenario.
start_test "bot-detect: navigate to test page"