Skip to content

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

fix: the drag docs and comment name the step count as what fires dragstart, when the measured mechanism is the button held on the moves (PIN-130)

Luigi Agosti9764fba60333
diff --git a/docs/reference/mouse.md b/docs/reference/mouse.md
index fdf97cb4..4b4ecbf4 100644
--- a/docs/reference/mouse.md
+++ b/docs/reference/mouse.md
@@ -49,11 +49,12 @@ Notes:
- `drag <from> <to>` accepts selector/ref targets or `x,y` coordinate pairs on either side.
- `drag` has two forms and they differ only in how the end of the drag is expressed: a
target (`drag <from> <to>`, `toSelector`/`toX`/`toY`) or an offset (`--drag-x/--drag-y`,
- `dragX`/`dragY`). Both are one action that interpolates the pointer between the two
- points, which is what makes HTML5 drag-and-drop work — Chrome starts a drag only after
- sustained movement follows the press, so a single jump fires no `dragstart` at all.
- Assembling a drag yourself out of `mouse move`/`mouse down`/`mouse up` has that problem:
- use `drag` for anything with a `draggable` source.
+ `dragX`/`dragY`). Both are one action that moves the pointer with the button still held,
+ which is what makes HTML5 drag-and-drop work — Chrome enters the drag pipeline only on
+ movement that reports the pressed button. Each `mouse move` is its own request and knows
+ of no press, so a drag assembled out of `mouse move`/`mouse down`/`mouse up` fires no
+ `dragstart` however many small steps it takes; the step count is not the problem. Use
+ `drag` for anything with a `draggable` source.
- `button` supports `left`, `right`, and `middle`. Any other name is refused — the CLI
refuses it before sending, and the HTTP action body answers 400 naming the three. Omitting
`button` still means `left`; that is a default, whereas a name the server does not know
diff --git a/internal/bridge/action_pointer_drag_test.go b/internal/bridge/action_pointer_drag_test.go
index 41387a9e..05ad12f1 100644
--- a/internal/bridge/action_pointer_drag_test.go
+++ b/internal/bridge/action_pointer_drag_test.go
@@ -238,6 +238,56 @@ func TestThePointerPrimitivesStillDispatchOneJumpEach(t *testing.T) {
}
}
+// The reason `drag` has to own the sequence is the button, not the number of steps: every
+// `mouse move` is its own request and knows of no press, so its moves report no button held
+// and Chrome never enters the drag pipeline. Measured both ways — one interpolated move with
+// the button held completes the drop, while these twenty without it do not — so a caller who
+// reads the limitation as "one jump" and answers it with small steps still gets nothing.
+func TestManySmallHandAssembledStepsStillCompleteNoHTML5Drop(t *testing.T) {
+ f := newDragFixture(t)
+ const moves = 20
+
+ // The mouse pair first, so the negative below cannot pass by the sequence never landing:
+ // the same twenty steps DO complete a mouse-driven drop.
+ f.reload(t)
+ f.handAssembledDragInSteps(t, "#mouseSrc", "#mouseDst", moves)
+ if _, mouse := f.state(t); mouse != "DROPPED" {
+ t.Fatalf("%d hand-assembled moves did not complete even a mouse-driven drop (mouse=%q), so the HTML5 reading below would prove nothing", moves, mouse)
+ }
+
+ f.reload(t)
+ f.handAssembledDragInSteps(t, "#h5Src", "#h5Dst", moves)
+ if html5, _ := f.state(t); html5 != "no" {
+ t.Errorf("%d hand-assembled moves recorded h5=%q; if the primitives now complete an HTML5 drop, the docs' held-button explanation is obsolete", moves, html5)
+ }
+}
+
+func (f *dragFixture) handAssembledDragInSteps(t *testing.T, from, to string, moves int) {
+ t.Helper()
+
+ srcX, srcY := f.point(t, from)
+ dstX, dstY := f.point(t, to)
+ at := func(i int) ActionRequest {
+ p := float64(i) / float64(moves)
+ return ActionRequest{X: srcX + p*(dstX-srcX), Y: srcY + p*(dstY-srcY), HasXY: true}
+ }
+
+ if _, err := f.b.actionMouseMove(f.ctx, at(0)); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := f.b.actionMouseDown(f.ctx, at(0)); err != nil {
+ t.Fatal(err)
+ }
+ for i := 1; i <= moves; i++ {
+ if _, err := f.b.actionMouseMove(f.ctx, at(i)); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if _, err := f.b.actionMouseUp(f.ctx, at(moves)); err != nil {
+ t.Fatal(err)
+ }
+}
+
func (f *dragFixture) buttonRecord(t *testing.T) (pressed int, held int) {
t.Helper()
if err := chromedp.Run(f.ctx,
diff --git a/internal/bridge/cdpops/pointer.go b/internal/bridge/cdpops/pointer.go
index cb9c2e7b..2995cd1a 100644
--- a/internal/bridge/cdpops/pointer.go
+++ b/internal/bridge/cdpops/pointer.go
@@ -457,8 +457,8 @@ func heldButton(button string) (mouseButton, error) {
return row, nil
}
-// Chrome starts an HTML5 drag only after sustained movement follows the press, so the
-// interpolation is load-bearing: a single jump from source to destination fires no dragstart.
+// Chrome enters the HTML5 drag pipeline only on movement that reports the pressed button, so
+// the held mask on these moves is what fires dragstart, not how many of them there are.
func DragBetweenPoints(ctx context.Context, x, y, endX, endY float64, button string) error {
dx := endX - x
dy := endY - y