In Selenium, how do Actions.scrollToElement() and Actions.scrollByAmount() differ, and which device do they drive?

## A third virtual device Selenium 4.2 added a **wheel input source** alongside the pointer and the keyboard, and `Actions` exposes it through three methods: `scrollToElement`, `scrollByAmount` and `scrollFromOrigin`. They build `WheelInput` scroll interactions, which the browser dispatches as real wheel events, and they travel in the same single actions request as any other chain step. The distinction between the first two is about **what you name**: a target element, or a distance. Three things follow from the wheel being a device of its own: - It has its own sequence, so a scroll and a pointer move can occupy the same tick and happen together. - All three methods return the builder, so scrolls chain freely with clicks and key presses in one sequence. - Nothing in your code is browser-specific; the driver turns the scroll interaction into the browser's own wheel events. ## scrollToElement - name the element `scrollToElement(WebElement)` scrolls the given element into the viewport if it is not already there, bringing the bottom of the element to the bottom of the viewport. You do not supply a distance; the driver works out what is needed. ```java WebElement row = driver.findElement(By.cssSelector("[data-report-id='EXP-4471']")); new Actions(driver).scrollToElement(row).perform(); ``` On a long expense-report approval list this is what you want when the goal is "make row EXP-4471 reachable" and you do not care how far down it is. If the element is already visible, the scroll is a no-op rather than a jump. ## scrollByAmount - name the distance `scrollByAmount(int deltaX, int deltaY)` scrolls by the given pixel deltas with the origin at the **top left corner of the viewport**. A positive `deltaY` scrolls down, a negative one scrolls up; a negative `deltaX` scrolls left. ```java new Actions(driver).scrollByAmount(0, 400).perform(); ``` Nothing here refers to an element, so this is the method for "move the page a screenful" rather than "reach this row". It is also the one people misuse: it scrolls the viewport, so if the approval list is itself a scrollable panel inside the page, `scrollByAmount` moves the page around the panel and leaves the list where it was. ## Comparing them | | `scrollToElement` | `scrollByAmount` | |---|---|---| | Argument | A `WebElement` | Pixel deltas `deltaX`, `deltaY` | | Origin | The element | Top left of the viewport | | Distance | Computed by the driver | Exactly what you pass | | Already-satisfied case | Does nothing if in view | Always scrolls by the deltas | | Typical use | Reach a specific report row | Advance the page by a known amount | ## scrollFromOrigin - name both The third method covers the case neither of the others does: scroll a **given distance** from a **given origin**. The origin is a `WheelInput.ScrollOrigin`, built either from an element or from the viewport, optionally with an offset: - `WheelInput.ScrollOrigin.fromElement(panel)` - the centre of `panel` - `WheelInput.ScrollOrigin.fromElement(panel, 0, -50)` - 50 pixels above that centre - `WheelInput.ScrollOrigin.fromViewport()` and `fromViewport(x, y)` - the viewport's top left, plus offsets ```java WheelInput.ScrollOrigin origin = WheelInput.ScrollOrigin.fromElement(listPanel); new Actions(driver).scrollFromOrigin(origin, 0, 400).perform(); ``` This is the one that scrolls a nested scrollable region: put the origin inside the approval list's own scroll container and the wheel events land there rather than on the document. If the element used as an origin is itself out of view, the driver first scrolls its bottom to the bottom of the viewport, exactly as `scrollToElement` would, and then applies the deltas. ## Timing and pointer position All three take their duration from the `Actions` constructor, which defaults to 250 ms and can be set with `new Actions(driver, Duration.ofMillis(50))`. Like a `pointerMove`, a scroll's duration counts towards the tick duration, so a chain of scrolls is paced rather than instantaneous. Scrolling does **not** move the virtual pointer. If a chain scrolls a row into view and then uses a no-argument `contextClick()`, the click lands wherever the pointer already was - which, after a scroll, is very often not over the row. Target the element explicitly, or `moveToElement(row)` first. ## When wheel scrolling is not the answer - The pointer convenience methods already scroll for you: `moveToElement`, `clickAndHold` and friends work against an element's in-view centre point, so an explicit scroll before them is usually redundant. - A wheel event is not a keyboard scroll. A list that only responds to Page Down needs keys, not `scrollByAmount`. - Deltas are pixels, not rows or pages. Hard-coded numbers tuned on one viewport size do not survive a different window, whereas `scrollToElement` does.