Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteIn a Poltergeist-driven Capybara test, resize the active browser with page.driver.resize(1280, 900), scroll to a precise offset with page.driver.scroll_to(0, 1200), or use Capybara’s page.scroll_to for positions such as :bottom and target elements when your installed versions support it. Poltergeist is archived legacy infrastructure, so check the Capybara and driver versions in your suite before relying on newer semantic scrolling calls.
Resize the Poltergeist browser window
Poltergeist exposes a driver method for changing the active browser window size. Pass the width and height in pixels:
page.driver.resize(1280, 900)resize_window is an alias. This changes the browser window used by the current test; it does not change the dimensions of the machine or display running the test.
Set an initial size when registering the driver
If a suite should begin with a consistent viewport, pass window_size when registering Poltergeist with Capybara:
#1 Best Overall
Capybara.register_driver :poltergeist do |app|
Capybara::Poltergeist::Driver.new(
app,
window_size: [1280, 900]
)
endThe Poltergeist README documents [1024, 768] as the default window_size. Setting it explicitly can make tests easier to reason about than depending on a default, especially when a layout changes at responsive breakpoints. The option screen_size is different: it sets dimensions used by Window#maximize, and the documented value is [1366, 768]. Do not treat screen_size as another name for the active window’s window_size.
Check the effective viewport
To confirm what the page sees after a resize, ask the driver for the current window dimensions:
size = page.driver.window_size(page.current_window.handle)
puts size.inspectPoltergeist’s window_size reads window.innerWidth and window.innerHeight. That makes it useful for diagnosing a mismatch between the size requested by the test and the viewport reported by the page. If a test depends on a breakpoint, assert or log the measured size rather than assuming the requested value took effect.
Scroll the page with Poltergeist or Capybara
Choose the scrolling method by intent. Raw coordinates are direct and deterministic when the test needs a known offset; semantic scrolling describes a destination and is usually clearer when the destination is the top, bottom, center, or a particular element.
Recommended Free Tools
Scroll to exact coordinates
Poltergeist’s driver method accepts horizontal and vertical offsets:
page.driver.scroll_to(0, 1200)The first number is the left offset and the second is the top offset. Use this when the exact position matters, including horizontal scrolling. It is a low-level choice: if page content changes height, a fixed coordinate may no longer place the intended element in view.
Scroll to a named page position
Capybara’s node API provides semantic destinations in versions and drivers that implement the method:
page.scroll_to(:top)
page.scroll_to(:bottom)
page.scroll_to(:center)
page.scroll_to(:current):current represents the current position rather than a new named destination. For an element, pass the node and an alignment:
results = find('#results')
page.scroll_to(results, align: :center)The documented element alignments are :top, :bottom, and :center. A coordinate overload is also available in the documented API, and an offset can adjust the final position:
page.scroll_to(0, 1200)
page.scroll_to(:bottom, offset: [0, -80])For example, a negative vertical offset can leave space above a destination rather than aligning it flush to the viewport edge. Capybara’s driver support for this API is optional. Since Poltergeist is archived, verify that the particular Capybara/Poltergeist combination in the project supports the call before replacing a working driver-level or JavaScript approach.
Use JavaScript when you need a fallback or page-specific behavior
Poltergeist supports both evaluate_script and execute_script. Use the first when the test needs the script’s return value, and the second when the script is only meant to perform an action:
# Return the browser-reported viewport size
size = page.evaluate_script('[window.innerWidth, window.innerHeight]')
# Scroll the document to its current bottom
page.evaluate_script('window.scrollTo(0, document.body.scrollHeight)')
# Scroll a matching element into view
page.execute_script('document.querySelector("#results").scrollIntoView()')For an element-scoped Capybara script, this is bound to the element. This can avoid querying for the same node again:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →results = find('#results')
results.execute_script('this.scrollIntoView()')JavaScript is useful if the installed driver does not provide the semantic Capybara method, or when a test needs browser-native behavior. It is less descriptive than page.scroll_to(find(...)), so keep the intent clear in the surrounding test. Also distinguish document scrolling from scrolling an inner panel: window.scrollTo moves the document viewport, while a scrollable element may need its own scroll position adjusted. When the target lives inside a nested scrolling region, inspect that region and use a suitable element-level action instead of assuming the page itself is the scroller.
Capture screenshots and diagnose failed clicks
Poltergeist’s save_screenshot captures the visible viewport by default. Add full: true to render the whole document:
page.save_screenshot('page.png', full: true)A viewport screenshot is generally the more useful view when investigating whether a target is obscured at the moment of a click. A full-page image is useful for inspecting content beyond the current viewport, but it is not a record of a click’s hit-testing geometry at a particular scroll position.
Poltergeist performs clicks at real coordinates. It scrolls the target into view before calculating those coordinates, but another element covering the target can still cause a MouseEventFailed. If that happens, save a screenshot and inspect the driver’s debug output to see where the target and covering element are positioned. A click failure after scrolling is not necessarily evidence that scrolling failed; the target may be visible but overlapped.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
A practical sequence for a stable test
- Choose the viewport first. Set
window_sizeat driver registration for a consistent starting viewport, or callpage.driver.resize(width, height)where the test needs a different size. - Measure if layout matters. Read
page.driver.window_size(page.current_window.handle)or evaluatewindow.innerWidthandwindow.innerHeightso a responsive-layout failure is not mistaken for a scrolling issue. - Wait for the destination to exist. Find the target through Capybara before scrolling to it. For content that is added asynchronously, wait for the relevant element or state rather than issuing a scroll immediately and assuming the page is ready.
- Use the clearest scrolling level. Prefer
page.scroll_tofor semantic positions if available; usepage.driver.scroll_tofor a known offset; use JavaScript when necessary for a specific browser action or nested scroll behavior. - Verify the result at the interaction point. If a click fails, capture the viewport and inspect debug output. Check for overlays and whether the target is in the scrollable region you actually moved.
Common problems and fixes
page.scroll_tois undefined or unsupported: Capybara’s semantic scrolling support is optional and version-dependent. Check the installed Capybara and Poltergeist versions. Usepage.driver.scroll_to(left, top)or a JavaScript fallback if that API is unavailable.- The page is the wrong size after resizing: Query the effective dimensions with
window_sizeorwindow.innerWidth/window.innerHeight. Confirm the test is acting on the intended current window and that it is using the active-window resize method rather than confusingscreen_sizewithwindow_size. - Scrolling to the bottom does not reveal expected content: A fixed coordinate may not match the page’s current height. Use semantic
:bottomwhere supported, or calculate the document height at the time of the call. If content appears after the initial page load, wait for it before scrolling. - The target is found but the click raises
MouseEventFailed: Poltergeist uses real click coordinates and another element may cover the target. Save a viewport screenshot and inspect debug output; determine whether an overlay or another obstruction occupies the target area before changing the scroll offset. - Scrolling the document does not move a panel: The target may be inside an independently scrollable element. Identify the actual scrolling container and adjust or bring the target into view within that container rather than relying only on
window.scrollTo. - A scroll call works locally but not in another suite environment: Poltergeist was archived on November 27, 2020. Treat the stack as legacy, pin compatible versions in maintained test suites, and verify driver support for optional APIs in the exact environment where tests run.
Or skip the browser setup
If the job is to save a page image or PDF rather than exercise a Poltergeist interaction, ScreenshotNeo can capture from one GET request. It is not a replacement for a Capybara test that must scroll, click, or assert application behavior in its own browser session; use it when the desired output is a screenshot or PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is on every plan. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Does resizing with Poltergeist change a real monitor’s resolution?
No. It changes the browser window used by the test, not the host machine’s physical display resolution.
Can I use Poltergeist for a newly created test suite?
It is an archived project, not an actively maintained driver. If you must keep it, pin a compatible stack and verify the API behavior in your own suite; for a new suite, assess a currently maintained Capybara driver.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
