How to Capture Screenshots of Web Pages with Selenium in Ruby

To capture a web page with Selenium in Ruby, navigate to it with a WebDriver instance and call driver.save_screenshot('screenshot.png'). This saves a PNG of the browser’s current visible viewport. For an element, locate it and call element.save_screenshot('element.png'). Full-page capture depends on driver support.

1. Set up Selenium WebDriver for Ruby

Install the Selenium Ruby gem in your project:

gem install selenium-webdriver

Or add it to a Bundler-managed project:

# Gemfile
gem 'selenium-webdriver'

bundle install

You also need a browser supported by your Selenium setup, such as Chrome. Selenium’s browser documentation shows the Ruby binding opening Chrome and saving a screenshot. Browser and driver availability can depend on your local environment, so consult the documentation for your installed Selenium version if driver startup fails.

2. Capture the visible viewport

This complete example opens a page, saves its current viewport as a PNG, and quits the browser even if navigation or capture raises an error:

require 'selenium-webdriver'

driver = Selenium::WebDriver.for :chrome

begin
  driver.get 'https://example.com/'
  driver.save_screenshot('screenshot.png')
ensure
  driver.quit
end

The screenshot is the viewport currently shown by the browser. It does not automatically include all content below the fold. Use a path writable by the process running the script, and keep the filename extension as .png.

3. Choose the screenshot type

Need	Ruby call	What to expect
Visible browser area	`driver.save_screenshot('page.png')`	PNG of the current viewport.
One page element	`element.save_screenshot('element.png')`	PNG of the selected element.
Full page	`driver.save_screenshot('page.png', full_page: true)`	Works only if the driver object supports full-page screenshots.
PNG bytes in memory	`driver.screenshot_as(:png)`	Returns PNG data rather than writing a file.
Base64 in memory	`driver.screenshot_as(:base64)`	Returns the screenshot as a Base64 string.

Capture one element

Find the element before saving its screenshot. This example captures the page’s first h1 element:

require 'selenium-webdriver'

driver = Selenium::WebDriver.for :chrome

begin
  driver.get 'https://example.com/'
  heading = driver.find_element(css: 'h1')
  heading.save_screenshot('heading.png')
ensure
  driver.quit
end

If the selector matches no element, Selenium cannot capture it; use a selector present on the page and account for pages that render content asynchronously.

Request a full-page screenshot

The Ruby API accepts full_page: false by default. You can request a full-page screenshot like this:

driver.save_screenshot('full-page.png', full_page: true)

This is conditional on support from the driver object. Unsupported objects raise Selenium::WebDriver::Error::UnsupportedOperationError. The Selenium Ruby API documentation does not establish a complete browser and version support matrix, so confirm this against the browser, driver, and Selenium versions in your environment. If the capability is unsupported, take a viewport screenshot or use a capture service that provides the output you need.

Use screenshot data without a file

Use screenshot_as(:png) when downstream Ruby code needs the image bytes, or screenshot_as(:base64) when a Base64 string is more convenient:

png_bytes = driver.screenshot_as(:png)
base64_image = driver.screenshot_as(:base64)

The Ruby API documents these return formats. Choose one representation and pass it to the next step in your application rather than writing a temporary file when no file is needed.

4. Make the capture repeatable

Use an explicit destination path when the working directory may vary, for example /tmp/page.png on a Unix-like system or a path constructed for your deployment environment.
Navigate to the exact page you intend to capture.
Wait for any page-specific content your workflow requires before capturing. Selenium screenshot calls capture the current browser state; the supplied API references do not prescribe a general wait strategy.
Choose viewport, element, or full-page capture based on the needed area.
Keep cleanup in an ensure block so the browser is quit after success or failure.
Check the resulting file or returned data in your application before relying on it downstream.

The Selenium screenshot API is a low-level capture capability, not a list of screenshot styling options. Do not assume options from other screenshot products, such as custom image formats or automatic banner removal, are part of this Ruby method.

5. Troubleshooting

Symptom	Likely cause	Fix
No screenshot at the expected location	The process working directory differs from what you expected, or the destination is not writable.	Use an explicit writable path and check the process working directory. The API logs the save location using `Dir.pwd` and the supplied path.
Warning about the filename extension	The screenshot is PNG data but the filename does not end in `.png`.	Use a `.png` filename. The save method writes PNG bytes regardless and warns when the extension does not match.
`UnsupportedOperationError` with `full_page: true`	The driver object does not support full-page screenshots.	Remove `full_page: true` to save the viewport, or verify support for your exact Selenium and driver setup before depending on full-page capture.
Element screenshot fails	The locator did not identify an element, or the element is not available in the current page state.	Verify the selector and ensure the page has reached the state where the element exists before locating it.
Screenshot methods change after a dependency update	The Ruby `TakesScreenshot` module is marked private in Selenium’s API docs.	Check behavior against your installed Selenium version and avoid treating this interface as a guaranteed stable public API.

6. Performance, reliability, and cost

A Selenium screenshot requires browser automation to start or use a browser, navigate to the page, and capture the current state. For repeated jobs, reuse a managed browser session where appropriate and always quit drivers when finished. The cited Selenium sources do not provide performance benchmarks or browser support guarantees for full-page capture, so measure your own workload and verify capability support in your environment.

With a local Selenium workflow, account for the browser runtime and the infrastructure that runs it. There is no Selenium screenshot API price specified in the research for this guide. Reliability depends on successful browser startup, page loading, and the availability of the requested capture capability.

7. Or skip the browser setup

If you need a screenshot without managing Selenium and a browser, ScreenshotNeo provides a website screenshot API. One GET request returns an image or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and 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, and failed loads are never billed, and responses identify page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

8. FAQ

Does `save_screenshot` save the whole page?

By default it captures the visible viewport. Full-page capture must be explicitly requested and is only available when the driver supports it.

Can I get a screenshot as data instead of a file?

Yes. The Ruby API provides PNG bytes with screenshot_as(:png) and a Base64 string with screenshot_as(:base64).

Is Selenium’s Ruby screenshot interface guaranteed to stay unchanged?

The Selenium Project labels the TakesScreenshot module as private and says it may be removed or changed. Check your installed version’s API documentation before depending on it.