Implementation:Teamcapybara Capybara Selenium Scroll
| Knowledge Sources | |
|---|---|
| Domains | Testing, Browser_Interaction |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for scrolling elements and windows to specific positions, provided by Capybara::Selenium::Scroll.
Description
Capybara::Selenium::Scroll is a module mixed into the Selenium driver's element handling to support programmatic scrolling of both scrollable elements and the browser window.
scroll_by(x, y) scrolls the element by the given pixel offsets. It executes JavaScript that calls el.scrollBy if available, falling back to manual scrollTop/scrollLeft adjustment for older browsers.
scroll_to(element, location, position) dispatches to one of three private methods based on the arguments. When element is a Capybara::Selenium::Node, scroll_element_to_location uses scrollIntoView with a location parameter of :top (true), :bottom (false), or :center ({ behavior: 'instant', block: 'center' }). When location is a Symbol (:top, :bottom, :center), scroll_to_location scrolls the container element itself using scrollTo (or direct scrollTop assignment) with positions defined in the SCROLL_POSITIONS constant. Otherwise, scroll_to_coords(x, y) scrolls to absolute pixel coordinates.
The SCROLL_POSITIONS constant maps location symbols to JavaScript expressions: :top maps to 0, :bottom maps to arguments[0].scrollHeight, and :center maps to (arguments[0].scrollHeight - arguments[0].clientHeight)/2.
Usage
Called by Capybara's Element#scroll_to method. Supports scrolling to named positions (:top, :bottom, :center), to specific elements, or to absolute coordinates.
Code Reference
Source Location
- Repository: capybara
- File: lib/capybara/selenium/extensions/scroll.rb
- Lines: 76
Signature
module Capybara::Selenium::Scroll
def scroll_by(x, y)
# @param x [Integer] Horizontal scroll offset in pixels
# @param y [Integer] Vertical scroll offset in pixels
end
def scroll_to(element, location, position = nil)
# @param element [Capybara::Selenium::Node, Symbol] Element to scroll into view, or ignored when location is a Symbol
# @param location [Symbol, Object] :top, :bottom, :center for named positions
# @param position [Array(Integer, Integer), nil] Absolute [x, y] coordinates
# @return [self]
end
SCROLL_POSITIONS = {
top: '0',
bottom: 'arguments[0].scrollHeight',
center: '(arguments[0].scrollHeight - arguments[0].clientHeight)/2'
}.freeze
end
Import
require 'capybara/selenium/extensions/scroll'
# Automatically mixed into Selenium node handling
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| x | Integer | Yes (scroll_by) | Horizontal scroll offset in pixels |
| y | Integer | Yes (scroll_by) | Vertical scroll offset in pixels |
| element | Capybara::Selenium::Node/Symbol | Yes (scroll_to) | Element to scroll into view, or unused when scrolling by location |
| location | Symbol | Yes (scroll_to) | Named position: :top, :bottom, or :center |
| position | Array(Integer, Integer) | No | Absolute [x, y] coordinates for coordinate-based scrolling |
Outputs
| Name | Type | Description |
|---|---|---|
| self (scroll_to) | Capybara::Selenium::Node | Returns self for method chaining |
| (scroll_by) | nil | Scrolls the element; no meaningful return value |
Usage Examples
Scrolling by Offset
element = page.find('#scrollable-container')
# Scroll down by 200 pixels
element.scroll_by(0, 200)
# Scroll right by 100 pixels
element.scroll_by(100, 0)
Scrolling to Named Positions
# Scroll the page to the top
page.scroll_to(:top)
# Scroll to the bottom
page.scroll_to(:bottom)
# Scroll to center
page.scroll_to(:center)
Scrolling an Element into View
target = page.find('#off-screen-element')
# Scroll so element is at the top of the viewport
page.scroll_to(target, :top)
# Scroll so element is centered in the viewport
page.scroll_to(target, :center)
Scrolling to Coordinates
# Scroll to absolute pixel coordinates
page.scroll_to(0, 500)