How to Take Full-Page Screenshots in Ruby with Ferrum and Cuprite

Use Ferrum with a local Chrome or Chromium browser, navigate to the page, and call page.screenshot(path: "full-page.png", full: true). The full: true option captures the document’s scrollable content rather than only the visible viewport. The option is documented for Ferrum 0.15; check the API for the gem version installed in your project before shipping the exact call.

What a full-page screenshot captures

A viewport screenshot records only the pixels currently visible in the browser window. A full-page screenshot asks the browser to render the page as one tall image containing its scrollable content, including sections below the fold. This is useful for visual regression files, documentation, page previews, audit records, and sharing a long landing page without stitching multiple images yourself.

#	Preview	Product	Price
1		The Ruby Programming Language: Everything You Need to Know	$17.76	Buy on Amazon
2		Programming Ruby 3.3: The Pragmatic Programmers' Guide (Pragmatic Programmers; Facets of Ruby)	$58.31	Buy on Amazon
3		The Little Book Of Ruby Programming: Learn To Program Ruby For Beginners (Little Programming Books)	$18.99	Buy on Amazon
4		The Well Grounded Rubyist	$41.47	Buy on Amazon
5		Eloquent Ruby (Addison-Wesley Professional Ruby Series)	$19.22	Buy on Amazon

“Full page” means the page’s scrollable document, not necessarily every pixel in an embedded frame, an open browser extension panel, or content that never loads. Lazy-loaded images, animations, consent dialogs, and pages protected by bot checks can still affect the result. The capture happens in a real Chrome/Chromium session, so page JavaScript and network behavior matter.

Choose the Ruby route that fits your project

Ferrum for a standalone Ruby script

Ferrum is a Ruby API for headless Chrome and Chromium. It is the most direct route when you want a script that opens a URL and writes an image without adopting a test framework. Its project documentation shows creating a browser, calling go_to, saving a screenshot by path, and quitting the browser. The Ferrum 0.15 API documents the full: true screenshot option.

#1 Best Overall

Sale

The Ruby Programming Language: Everything You Need to Know

• Used Book in Good Condition

$17.76

Buy on Amazon

Cuprite for a Capybara suite

Cuprite is a pure Ruby Capybara driver built on Ferrum. Use it when your application tests already use Capybara’s sessions, matchers, and JavaScript-driver conventions. You keep Capybara’s interface while Ferrum controls Chrome underneath. The browser executable and version still need to be compatible with the Cuprite/Ferrum versions in your bundle.

Why not copy a Playwright example into Ruby

Playwright’s documentation clearly defines a full-page capture, but the examples cited for that behavior use JavaScript. They do not establish a Ruby API. Do not paste Playwright JavaScript syntax into a Ruby program or assume that a Ruby binding has identical options. For a Ruby-native implementation, verify Ferrum or Cuprite against the versions you actually install.

Prerequisites and browser discovery

• Ruby and Bundler in the project where the script will run.
• A Chrome or Chromium executable available on PATH, or a path supplied through Ferrum’s BROWSER_PATH configuration.
• A Ferrum version whose screenshot API you have checked. The full: true reference in this article is specifically associated with Ferrum 0.15 documentation.
• Network access to the target URL, unless the page is served locally or from a test environment.

In containers, CI runners, and locked-down servers, browser startup is often the first failure. Install a compatible Chrome/Chromium package in the image and expose its executable path rather than assuming a developer laptop’s installation exists. Cuprite documentation shows a no-sandbox option for some Docker setups; apply such a flag only when your container security model requires it, and follow your environment’s browser guidance instead of copying deployment flags blindly.

Standalone Ferrum implementation

Install the gem

Add Ferrum to your Gemfile:

gem "ferrum"

Then run:

bundle install

You can also install the gem outside a Bundler project, but a Gemfile makes the browser automation version explicit and repeatable.

Minimal full-page capture

require "ferrum"

browser = Ferrum::Browser.new
begin
  browser.go_to("https://example.com")
  browser.screenshot(path: "full-page.png", full: true)
ensure
  browser.quit
end

The ensure block closes Chrome even when navigation or image writing raises an exception. The example follows the documented Ferrum operations: create a browser, navigate, save a screenshot, and quit. The combined path and full signature should be confirmed against the installed gem; the cited materials document those pieces separately rather than showing this exact line together.

Make the URL and output configurable

require "ferrum"

url = ARGV.fetch(0, "https://example.com")
output = ARGV.fetch(1, "full-page.png")

browser = Ferrum::Browser.new
begin
  browser.go_to(url)
  browser.screenshot(path: output, full: true)
  puts "Wrote #{output}"
ensure
  browser.quit
end

Run it with:

bundle exec ruby screenshot.rb https://example.com example.png

Use an absolute output path in CI if the working directory is uncertain. Ensure the destination directory already exists and is writable.

Controlling page state before capture

A full-page flag changes the captured height; it does not automatically make a page deterministic. For reliable visual files, navigate to a stable URL, wait for the content you need, and put the page into a known state before taking the image.

Rank #2

Sale

Programming Ruby 3.3: The Pragmatic Programmers' Guide (Pragmatic Programmers; Facets of Ruby)

$58.31

Buy on Amazon

Wait for navigation and application rendering

Single-page applications can finish the initial HTTP response before their meaningful content appears. Use the Ferrum APIs supported by your installed version to wait for a selector or other application-ready condition, then capture. If your page has an animation, freeze it with page CSS or wait until the animation has reached the state you want. Avoid claiming a screenshot is complete merely because go_to returned.

Lazy-loaded content

Some pages load images only after an element approaches the viewport. A full-page operation may or may not trigger every site’s lazy-loading strategy. If important images are missing, inspect the page’s loading behavior and explicitly scroll or otherwise trigger the application’s load mechanism before the final screenshot. Do not assume that increasing the image height alone downloads all resources.

Dynamic and private pages

For authenticated content, establish the session and cookies in the same browser before navigating to the final URL. For pages that vary by viewport, locale, timezone, or user agent, configure those values before the visit and record them with the output so later comparisons are meaningful. A CAPTCHA or bot challenge cannot be made into the intended page by a screenshot option; treat it as a failed page load and diagnose access separately.

Using Cuprite with Capybara

Add and select the driver

In a test group, add Cuprite:

group :test do
  gem "capybara"
  gem "cuprite"
end

In your test setup, require Capybara and Cuprite, then select the JavaScript driver:

require "capybara"
require "capybara/cuprite"

Capybara.javascript_driver = :cuprite

Cuprite’s documentation also shows registering a driver when you need custom browser options. Keep the registration local to your test setup and use the option names supported by your installed Cuprite release.

Capture a page through a Capybara session

session = Capybara::Session.new(:cuprite)
session.visit("https://example.com")

# Add a Capybara wait/assertion for content your page must render here.
session.page.save_screenshot("full-page.png", full: true)

Capybara’s session and page objects delegate browser work to Cuprite/Ferrum. Check the Cuprite and Ferrum versions in your bundle before relying on the keyword combination shown above; API compatibility can change between releases.

When Cuprite is the better fit

• Your existing suite already uses Capybara sessions and matchers.
• You want the same driver to exercise JavaScript and save visual artifacts.
• Your CI setup already provisions Chrome/Chromium for Capybara tests.

For a small utility with no Capybara dependency, Ferrum avoids the additional integration layer.

Rank #3

The Little Book Of Ruby Programming: Learn To Program Ruby For Beginners (Little Programming Books)

$18.99

Buy on Amazon

Image format, dimensions, and practical limits

A full-page image can become extremely tall. PNG preserves sharp text and transparency but can consume substantial disk space. JPEG is smaller for photographic pages but introduces compression artifacts and does not preserve transparency. WebP can provide a smaller modern image when your downstream tooling accepts it. Select the format and quality options exposed by your installed Ferrum version, and verify the resulting file in the consumer that will display it.

Very long pages can exceed operating-system, browser, image-library, or downstream viewer limits. If one giant image is impractical, capture logical sections or generate a PDF instead. A full-page screenshot is one raster surface; it is not a substitute for a paginated document when readers need printing, selectable text, or small files.

Run captures serially when memory is constrained, reuse one browser for a controlled batch, and always quit it at the end. A new browser per URL provides stronger isolation but adds startup time. Measure your own pages: heavy scripts, fonts, third-party requests, and image decoding dominate runtime more than the Ruby method call.

Troubleshooting checklist

“Browser not found” or startup failure

Cause: Chrome/Chromium is not installed, is not on PATH, or Ferrum is looking at a different executable. Fix: install a compatible browser, verify the executable from the same user account as the script, or set the browser path through the Ferrum configuration documented for your version, including BROWSER_PATH where supported.

The image is only viewport-sized

Cause: the installed Ferrum/Cuprite version may not support the option in the same form, or the call omitted full: true. Fix: inspect the installed gem’s API, confirm the option name and object receiving the call, and test with a page whose content clearly extends below the fold.

Blank, partial, or challenge page

Cause: navigation failed, JavaScript has not rendered, a request was blocked, or the site presented a CAPTCHA/bot check. Fix: log the final URL and browser errors, wait for a page-specific selector, verify network access, and handle authentication or anti-bot requirements legitimately. A screenshot call cannot bypass an access control.

Missing images or sections

Cause: lazy loading, delayed third-party resources, or an element that renders only after interaction. Fix: trigger the required state before capture, wait for the relevant selector, and disable animations where your test permits. Compare the captured page with a normal interactive browser session.

Rank #4

Sale

The Well Grounded Rubyist

$41.47

Buy on Amazon

Chrome exits in Docker or CI

Cause: sandbox, shared-memory, permissions, or missing system libraries. Fix: use a browser-ready image, provide the required writable directories, and follow your CI provider’s Chrome guidance. Cuprite documents a Docker-oriented no-sandbox example, but removing the sandbox has security implications and should not be a reflexive fix.

The output file cannot be written

Cause: a nonexistent directory, relative path confusion, or insufficient permissions. Fix: create the directory, use an absolute path, and check the process user’s write access.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF, so your Ruby process does not need to manage Chrome locally. Before capture it accepts cookie/consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether it was billed.

For a Ruby application, the API call can be made with the standard net/http library:

require "net/http"
require "uri"

uri = URI("https://api.screenshotneo.com/v1/shot")
uri.query = URI.encode_www_form(
  access_key: ENV.fetch("SCREENSHOTNEO_ACCESS_KEY"),
  url: "https://stripe.com"
)

response = Net::HTTP.get_response(uri)
abort "Screenshot failed: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)

File.binwrite("shot.webp", response.body)

See the ScreenshotNeo documentation for authentication, output controls, and the complete option list. The service supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or custom viewports, retina scale, PDF paper sizes/margins/landscape/page ranges, HTML/CSS-to-image, custom JavaScript and CSS, pre-capture clicks, selector or network-idle waits, ad/tracker/request blocking, custom headers/cookies/user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work to ease migration.

If you prefer command-line or another runtime, the same endpoint works with these documented forms:

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}`);

An MCP server provides take_screenshot, get_page_info, and capture_pdf tools to Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

ScreenshotNeo plans

Yearly billing gives two months free, and every feature is available on every plan. API responses include X-Page-Verdict and X-Billed headers, which let an automated pipeline distinguish a clean billed capture from a failed or non-billed result.

Best Value

Sale

Eloquent Ruby (Addison-Wesley Professional Ruby Series)

$19.22

Buy on Amazon

Ruby capture decision guide

Whichever route you choose, pin and review gem or API versions, make the page state deterministic, and retain enough logging to explain why a capture is missing or different.

FAQ

Does full-page mode capture content inside an iframe?

It captures the outer page’s document surface. An iframe is a separate browsing context and may require its own access, loading, or capture strategy.

Can I use Ferrum without headless mode?

Ferrum controls Chrome and Chromium; whether you display a visible window depends on the browser options and environment you configure. Headless operation is the usual choice for CI and servers.

Is a full-page PNG suitable for printing?

Not always. Extremely tall raster images can be awkward to print and large to open. Use a PDF capture or paginated sections when paper layout and selectable text matter.

How do I prove that a changed screenshot is a real page change?

Record the URL, viewport, browser version, authentication state, locale, timezone, and capture time, then compare artifacts under the same controlled conditions. Dynamic ads, timestamps, fonts, and animations can otherwise create differences unrelated to your code.

Frequently Asked Questions

Which Ferrum version does this example target?

The full: true option is documented in Ferrum 0.15 materials. Verify the exact call against the gem version in your bundle before relying on it.

Can Cuprite take full-page screenshots in a Capybara test?

Cuprite exposes a Ferrum-backed browser through Capybara. Configure the :cuprite driver and confirm that your installed Cuprite/Ferrum versions accept the full-page screenshot option.

Quick Recap

SaleBestseller No. 1

The Ruby Programming Language: Everything You Need to Know

Used Book in Good Condition

$17.76

SaleBestseller No. 2

Programming Ruby 3.3: The Pragmatic Programmers' Guide (Pragmatic Programmers; Facets of Ruby)

$58.31

Bestseller No. 3

The Little Book Of Ruby Programming: Learn To Program Ruby For Beginners (Little Programming Books)

$18.99

SaleBestseller No. 4

The Well Grounded Rubyist

$41.47

SaleBestseller No. 5

Eloquent Ruby (Addison-Wesley Professional Ruby Series)

$19.22

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.