Wheel Actions for Virtualized Lists and Nested Scroll Containers

A Selenium wheel actions virtualized list test must synchronize two independent systems: browser scrolling and component rendering. The wheel input can complete correctly while the application is still fetching data, recycling rows, or deciding which nested container should consume the delta. Sleeping after every scroll only hides which system stalled.

Anchor the wheel over the intended scroll surface, dispatch one bounded delta, and wait for a stable row identity to change. Re-locate after every render and stop on either the target record, an explicit end state, or a diagnosed lack of progress.

Follow input through virtualization

Selenium's wheel actions documentation includes scrolling from an element origin. That origin determines where the browser dispatches the wheel input; the application then decides which visible rows exist after the resulting scroll.

The scroll command finishing is not a rendering assertion. Virtualized rows may update synchronously, after animation, or after a network response. The test must observe the component's meaningful progress.

Identify the actual scroll owner

A page can contain a document scroller, modal body, table viewport, and nested list. Wheel input is dispatched at a point, and the browser targets the element under that point. A scrollable ancestor may consume the delta; when it reaches an edge, scroll chaining can move an outer ancestor unless CSS prevents it.

Inspect overflow, dimensions, and scroll range during diagnosis. A container is potentially vertically scrollable when its scroll height exceeds its client height and its overflow behavior permits scrolling. Do not assume that the element with a scrollbar-shaped design is the DOM node that owns scrollTop.

Sticky headers and transparent loading masks also matter. An origin near the top center may hit a header rather than the rows. Choose an origin in a stable, unobstructed part of the viewport and verify that the intended container's scroll position or rendered boundary changes.

Dispatch one element-origin wheel step

Java's ScrollOrigin.fromElement keeps the gesture associated with the intended surface. Optional offsets are useful for avoiding a sticky child, but large offsets recreate viewport-boundary problems.

import org.openqa.selenium.By;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.interactions.WheelInput.ScrollOrigin;

By viewportBy = By.cssSelector("[data-testid='customer-list-viewport']");
WebElement viewport = driver.findElement(viewportBy);

ScrollOrigin origin = ScrollOrigin.fromElement(viewport, 0, 40);
new Actions(driver)
    .scrollFromOrigin(origin, 0, 520)
    .perform();

A positive vertical delta scrolls down, while a negative vertical delta scrolls up. Treat the numeric delta as input, not a promised final scrollTop. Scroll snap, event handlers, available range, and nested scrolling can change the resulting distance.

Use horizontal delta only for a genuine horizontal surface. Sending both axes to compensate for uncertain layout makes the expected gesture difficult to review and may trigger a different ancestor.

Synchronize on row identity

Virtualization frequently reuses a small pool of row nodes. A locator such as .row:last-child identifies a rendered position, not a business record. Read a stable key such as data-record-id, perform one step, then wait until the rendered boundary key changes.

import java.time.Duration;
import java.util.List;
import org.openqa.selenium.support.ui.WebDriverWait;

By rowsBy = By.cssSelector(
    "[data-testid='customer-list-viewport'] [data-record-id]"
);
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

String priorLastId = lastVisibleId(driver.findElements(rowsBy));

viewport = driver.findElement(viewportBy);
new Actions(driver)
    .scrollFromOrigin(ScrollOrigin.fromElement(viewport), 0, 520)
    .perform();

wait.until(current -> {
    List<WebElement> rows = current.findElements(rowsBy);
    return !rows.isEmpty() && !lastVisibleId(rows).equals(priorLastId);
});

lastVisibleId should filter displayed rows and return the final stable data-record-id. Resolve the list on every poll. Holding the old last row as a WebElement invites stale-element failures and, worse, can read a recycled node now representing another record.

If records can reorder because of live updates, use both boundary identity and target search. A changed last ID proves rendering progressed, while the target's own ID proves the test reached the right result.

Build a bounded search loop

Infinite scrolling is not infinite permission for the test to loop. Give the search a maximum number of steps, track every observed boundary, and recognize an explicit end marker. Fail immediately if one step produces neither a new boundary nor an end state.

String targetId = "CUS-9482";
for (int step = 1; step <= 20; step++) {
    List<WebElement> matches = driver.findElements(
        By.cssSelector("[data-record-id='" + targetId + "']")
    );
    if (!matches.isEmpty() && matches.get(0).isDisplayed()) {
        matches.get(0).click();
        break;
    }

    if (!driver.findElements(By.cssSelector("[data-testid='list-end']")).isEmpty()) {
        throw new AssertionError("Customer not present before list end: " + targetId);
    }

    scrollOneRenderedWindow(driver, viewportBy, rowsBy);

    if (step == 20) {
        throw new AssertionError("No target after 20 wheel steps: " + targetId);
    }
}

The helper should include the progress wait shown earlier and report the prior and current boundary IDs. A fixed step limit is an operational guard, not a claim about list size. Choose it from test data and expected pagination, and seed the target so its position is deterministic.

Handle asynchronous data loading

Some virtual lists render all known records while a sentinel triggers the next API request. In that design, a boundary may stop changing temporarily even though a loading row appears. Wait for one of three terminal observations: a new boundary ID, an explicit end marker, or a visible error state.

Do not wait only for a spinner to disappear. It can disappear after a failed request or never appear on a cached response. Combine lifecycle evidence with new record identity. Capture the request correlation ID or page token when the application exposes one in sanitized diagnostics.

Prevent duplicate loads from satisfying the wait. If the same IDs are appended twice, boundary change alone may pass before a later uniqueness assertion. Check that rendered business keys are unique when duplicate pagination is a known risk.

Work with nested containers and frames

Re-locate the scroll container after modal transitions or component rerenders. The original WebElement can become stale even if its selector remains stable. If the list is inside an iframe, switch into that frame before resolving the element origin; wheel input belongs to the active browsing context.

When an inner container reaches its end, an additional wheel delta may move the outer page. Assert the inner end state before sending more input. A test that accidentally scrolls the document can move the modal under a sticky overlay and produce an unrelated click failure later.

For bidirectional grids, separate horizontal column discovery from vertical record discovery. Each axis should have its own origin, progress signal, and limit. Diagonal wheel input makes it unclear which virtualizer caused the rerender.

Know when JavaScript changes the test

Assigning element.scrollTop can be a useful setup operation when the requirement concerns a state far down a large list and wheel behavior is irrelevant. It is not equivalent to wheel input: it bypasses hit testing, wheel listeners, delta handling, and scroll chaining.

Name the distinction in the helper. scrollListByWheel() validates user-like input; setListScrollPositionForSetup() arranges state. Do not fall back from the first to the second after a failure, because that converts an input defect into a passing test.

Browser-native scrolling also differs from calling scrollIntoView on a virtual row that does not yet exist. Virtualization means there may be no element to target until enough scroll progress has occurred.

Diagnose wheel failures with evidence

On failure capture the origin element rectangle, viewport size, its scrollTop, scrollHeight, and clientHeight, the requested deltas, the topmost element at the origin, and the observed first and last record IDs. Include whether a loading, end, or error marker was present.

If scrollTop changes but row identity does not, inspect virtualization thresholds and rendering. If neither changes, inspect origin hit testing and scrollability. If the outer document moves, the inner container may be at an edge or not own the event. If IDs change but the target never appears, inspect test data, sorting, filters, and duplicate-page responses.

Apply a virtual scrolling checklist

• Locate the DOM node that truly owns scrolling.
• Anchor the wheel within an unobstructed element region.
• Send one bounded axis-specific delta at a time.
• Treat delta as input, not a guaranteed final distance.
• Re-locate the container and rows after rerenders.
• Track stable record IDs instead of row indexes.
• Wait for new identity, end state, or explicit error.
• Bound every search loop and fail on no progress.
• Keep wheel validation separate from JavaScript setup.
• Report geometry, scroll metrics, and rendered IDs on failure.

Close on render progress

The stable unit of a virtualized scroll test is not pixels; it is one observed transition in record identity. Put the wheel over the right container, move by a controlled delta, wait for the component to expose a new business row, and stop decisively when progress ends. That contract survives DOM recycling because it follows data, not temporary nodes.