Pointer and Key Sequences

## The class, and the shape of a chain Every pointer or keyboard gesture that is more than a plain click lives on `org.openqa.selenium.interactions.Actions` in Selenium 4. You construct it with the driver, chain the steps you want, and call `perform()`: ```java new Actions(driver).moveToElement(reportRow).contextClick().perform(); ``` On an expense-report approval list that one line hovers a report row so its inline toolbar renders, then opens the row's right-click menu. Every method on the chain returns the same `Actions` object, which is what makes the chaining read the way it does. ## The convenience methods You almost never build raw pointer primitives yourself. `Actions` wraps them: | Method | What it does | |---|---| | `moveToElement(el)` | Moves the pointer to the in-view centre of `el` - a hover | | `moveToElement(el, x, y)` | Moves to an offset from that centre point | | `contextClick(el)` | Moves to `el`, then presses and releases the right button | | `doubleClick(el)` | Moves to `el`, then presses and releases the left button twice | | `clickAndHold(el)` | Moves to `el` and presses the left button without releasing it | | `release(el)` | Moves to `el` and releases the left button | | `dragAndDrop(src, tgt)` | Hold on `src`, move to `tgt`, release | | `dragAndDropBy(src, x, y)` | Hold on `src`, move by an offset, release | | `keyDown(key)` / `keyUp(key)` | Presses or releases one modifier key | | `pause(Duration)` | Waits inside the sequence | The no-argument overloads - `contextClick()`, `doubleClick()`, `clickAndHold()`, `release()` - act **at the pointer's current position** rather than on an element. That is what lets you write a hand-built drag as `clickAndHold(row).moveToElement(bucket).release().perform()`, which is exactly what `dragAndDrop(row, bucket)` does for you. A few details are worth carrying around: - Every one of these methods expands into **pointer primitives** - a `pointerMove`, a `pointerDown`, a `pointerUp` - so `doubleClick(el)` is one move followed by two press-and-release pairs. - `moveToElement(el, x, y)` measures its offset from the element's **in-view centre point**, not from its top left corner, so `(0, 0)` is the centre. - `dragAndDropBy(src, x, y)` moves by an offset **from where the pointer already is** after the press, so the numbers are relative, not page coordinates. - `keyDown(el, key)` and `keyUp(el, key)` click the element first to focus it, then press or release the key on the keyboard device. - `pause(long)` and `pause(Duration)` both exist and wait **inside** the sequence, so the driver paces the gesture rather than your test thread. ## perform() is not optional The single most common beginner mistake with this API is building a chain and never running it: ```java Actions actions = new Actions(driver); actions.moveToElement(reportRow).contextClick(); // nothing happened ``` `Actions` collects steps in memory; nothing reaches the browser until `perform()` (or `build()` followed by performing the returned `Action`). Because no request was ever made, the test does not throw - it simply carries on and fails later, on the assertion that expected the context menu. So when a gesture "does nothing", work through this order: 1. Check that the chain ends in `perform()`. 2. Check that this `Actions` object has not already been performed once. 3. Only then start suspecting the page. There is a second, quieter version of the same trap. `build()` empties the builder as it snapshots the sequences, and `perform()` calls `build()`, so running the same `Actions` object twice does **not** repeat the gesture: the second call sends an empty action set. Build a fresh chain for each gesture. ## Drag and drop, and where it stops working `dragAndDrop(source, target)` is a convenience for four steps on the virtual pointer: move to the source, press, move to the target, release. That is a **pointer-level** gesture, and pages that implement dragging by listening to pointer or mouse movement respond to it normally. A page that instead implements dragging through the browser's native HTML5 drag-and-drop API is a different mechanism, and a synthesized pointer sequence may not drive it. The event model behind that API is a browser-platform subject rather than a Selenium one; the practical Selenium-side point is only that `dragAndDrop` failing on a list that a human can clearly drag is a known shape of problem, not a mistake in your chain. Confirm which mechanism the approval list uses before you spend an afternoon tuning offsets. ## Element-targeted versus current-position overloads Choosing between `contextClick(row)` and `moveToElement(row).contextClick()` is usually taste - they build the same interactions. The difference appears once you need something in between: - `moveToElement(row).pause(Duration.ofMillis(300)).contextClick().perform()` gives a hover-triggered menu time to render before the right-click lands. - `clickAndHold(row).moveByOffset(0, 40).moveToElement(bucket).release().perform()` nudges the pointer first, which some drag implementations need before they treat the gesture as a drag at all. Both are ordinary chains. What makes them work is that each step is queued, the whole queue is sent once, and the browser replays it in order.