Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC 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 & 11Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Poltergeist sits between Capybara and a headless PhantomJS browser. Use Poltergeist’s save_screenshot for viewport, full-page, or CSS-element images; use PhantomJS viewportSize to control responsive layout; and use paperSize (through Poltergeist’s paper_size=) for PDF dimensions, margins, and orientation. These settings solve different problems, so configure the one that matches the output you need.
The examples below follow the archived Poltergeist documentation and PhantomJS APIs. Check the gem and PhantomJS versions installed in your test environment before adopting them in a current suite.
What Poltergeist and PhantomJS each control
Poltergeist is a Capybara driver that runs tests in headless PhantomJS. Capybara supplies the test-facing driver interface; PhantomJS supplies webpage rendering properties such as viewportSize, paperSize, and image rendering.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
That division explains many confusing results. A window or viewport setting changes CSS layout and responsive breakpoints. A screenshot option decides which part of the laid-out page is captured. A PDF paper setting changes the physical page used for PDF output; it does not make the browser lay out the page as though its window had a different width.
#1 Best Overall
Install and configure the legacy driver
The Poltergeist README documents this setup:
require 'capybara/poltergeist'
Capybara.javascript_driver = :poltergeistPhantomJS 1.8.1 or newer is listed as a requirement in the README. The Poltergeist repository is archived and points readers to its 1.18.1 release documentation, so confirm that your installed gem, PhantomJS binary, Ruby version, and Capybara version are compatible rather than assuming these legacy examples work unchanged.
Set the driver window size
Poltergeist documents a :window_size option as a two-item array. Its documented default is [1024, 768]:
Capybara.register_driver :poltergeist do |app|
Capybara::Poltergeist::Driver.new(
app,
window_size: [1280, 900]
)
endThe separate :screen_size option describes the dimensions used when Window#maximize is called. Neither option is the same as setting PhantomJS’s webpage viewportSize directly.
Take a normal viewport screenshot
By default, Poltergeist captures the currently visible viewport:
save_screenshot('/tmp/dashboard.png')This is appropriate for assertions about what a user can see without scrolling. The output format is inferred from the filename in the usual Capybara workflow. Keep the viewport dimensions stable in CI so responsive breakpoints do not change between runs.
Capture the entire page
Pass :full => true to request a full-page screenshot:
save_screenshot('/tmp/dashboard-full.png', full: true)Full-page capture includes content beyond the initial viewport. It is useful for visual baselines and long documents, but it can produce a very tall image and may expose page sections that lazy-load only after scrolling. If the page uses JavaScript to reveal content, wait for that state before calling the screenshot.
Recommended Free Tools
Capture one element with a CSS selector
Use :selector to bound the image to an element matched by CSS:
save_screenshot(
'/tmp/invoice-total.png',
selector: '#invoice-total'
)The selector must match the intended element in the loaded DOM. A missing selector, a selector that matches an unexpected node, or an element with zero dimensions can result in an error or an unusable image. Prefer a stable ID or test-specific class over a position-dependent selector.
Control layout with PhantomJS viewportSize
PhantomJS describes viewportSize as the simulated browser-window size because the browser is headless. Set both width and height, and set them before loading the page so responsive CSS uses the intended dimensions:
var page = require('webpage').create();
page.viewportSize = {
width: 1280,
height: 900
};
page.open('https://example.com', function (status) {
// Capture only after the page has loaded.
});The height is required; setting only a width is not a complete viewport configuration. Changing this value can alter media queries, column wrapping, font behavior, and the amount visible in a viewport screenshot. It does not set PDF page dimensions.
Render images as Base64
For an image embedded in a report or returned by another API, Poltergeist documents page.driver.render_base64(format, options). PNG is the default; PNG, GIF, and JPEG are documented formats:
base64_png = page.driver.render_base64('PNG')
File.binwrite('/tmp/page.png', Base64.decode64(base64_png))Require Ruby’s Base64 library before decoding. Choose PNG for lossless UI text and transparency, JPEG for photographic content where a smaller file is more important, and GIF only when that format is required by a downstream system. The underlying PhantomJS renderBase64 API likewise returns a Base64-encoded image buffer and documents PNG, GIF, and JPEG.
Generate PDFs with paper_size
For PDF output, configure the Poltergeist driver’s paper_size= with PhantomJS paper settings. A format-based configuration is:
page.driver.paper_size = {
format: 'A4',
orientation: 'portrait',
margin: '1cm'
}
page.save_screenshot('/tmp/report.pdf')The exact PDF invocation can vary with the Poltergeist and Capybara versions in use, so validate the output path and driver API in your installed release. PhantomJS’s paperSize accepts named formats including A3, A4, A5, Legal, Letter, and Tabloid. Orientation defaults to portrait; use landscape when the document is wider than it is tall.
Use custom PDF dimensions
Set explicit width and height when a standard page is not suitable:
page.driver.paper_size = {
width: '5in',
height: '7in',
margin: {
top: '0.5in',
left: '0.5in',
bottom: '0.5in',
right: '0.5in'
}
}Dimensions may use mm, cm, in, or px; unitless dimensions are treated as pixels. A margin can be one measurement or an object with separate top, left, bottom, and right values. The documented default margin is zero.
Add repeating headers or footers
PhantomJS paper settings can include a header or footer with a height and callback-generated contents. Use this for page numbers, report titles, or dates that should repeat on every PDF page. Keep the callback output small and deterministic; dynamic network content in a header can make tests flaky.
Choose the setting by the output you need
| Need | Setting | Effect |
|---|---|---|
| What is currently visible | save_screenshot(path) |
Captures the viewport by default. |
| The complete document | full: true |
Requests a full-page image. |
| One component | selector: 'CSS selector' |
Bounds the image to a matched element. |
| Responsive layout width and height | viewportSize or driver window settings |
Changes browser layout dimensions; set before loading. |
| PDF page dimensions | paper_size= / paperSize |
Controls format or custom size, margins, orientation, and optional header/footer. |
Do not use landscape paper as a substitute for a wider viewport. First choose the viewport that should determine the page’s CSS layout, then choose the paper on which that layout will be printed.
Free tools Windows power users keep installed
One-click scans. No signup required.
A reliable capture sequence
- Configure the Poltergeist driver and confirm the PhantomJS executable version.
- Set the window or viewport dimensions before visiting the URL.
- Visit the page and wait for the application state required by the test.
- For an element capture, verify that the selector exists and has non-zero dimensions.
- Choose viewport, full-page, or element capture with
save_screenshot. - For PDF output, configure
paper_size=independently and inspect margins, orientation, and page breaks. - Store artifacts with a format-appropriate extension and review one output manually before enforcing visual comparisons in CI.
Troubleshooting common failures
The screenshot is only the top of the page
This is the documented default. Add full: true for a complete page, or use a selector for a particular component.
The mobile or desktop layout is wrong
Check the viewport or window dimensions, including height, and set them before loading. A PDF’s paper orientation does not change responsive layout.
The PDF is clipped or has unexpected whitespace
Inspect paper_size=: format, explicit width and height, margins, and orientation. Standard formats provide predictable pages; custom dimensions are better when the target size is nonstandard.
An element screenshot fails
Confirm the CSS selector matches exactly one intended element after JavaScript has finished. Wait for the element, remove overlays that cover it, and check that its computed width and height are not zero.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Lazy images or asynchronous content are missing
Do not capture immediately after navigation. Wait for the application’s completion condition, image load, or a stable DOM state. Full-page mode alone does not guarantee that application code has loaded every asset.
Rendering differs between local and CI
Compare PhantomJS and Poltergeist versions, viewport/window dimensions, fonts, asset availability, and network timing. Because the project is archived, pin known-good versions and treat upgrades as compatibility work.
Base64 output cannot be opened
Ensure the format string is supported, decode the Base64 value as binary, and write the decoded bytes rather than the encoded text. Use the matching file extension.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability, and maintenance considerations
Viewport screenshots generally use less memory than very tall full-page images. Element captures can reduce artifact size further. Large pages, many images, and repeated PDF rendering increase runtime and memory pressure, so capture only the area needed by the assertion.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesDeterministic dimensions and stable test data matter more than nominal screenshot speed. Freeze animations where possible, wait for network-dependent content, and avoid relying on remote resources that may be unavailable in CI. Since PhantomJS and Poltergeist are legacy components, record the versions in your test documentation and have a migration plan if your browser requirements move beyond their supported behavior.
Best Value
Or skip the browser setup
ScreenshotNeo provides a one-request website screenshot API and MCP server when you need a clean image or PDF without maintaining PhantomJS. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.
Use its documented API examples at https://screenshotneo.com/docs/:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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 also supports full-page and CSS-element captures, dark mode, device presets and custom viewports, retina scale, PDF paper size and margins, custom CSS or JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data, and an OpenAPI specification. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing provides two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to try the browser-free workflow.
Frequently Asked Questions
Can I set viewport size and PDF paper size in the same test?
Yes. Set the viewport before loading to control responsive layout, then configure paper_size for the PDF’s page dimensions. They affect different stages of rendering.
Which image formats does renderBase64 support?
The documented formats are PNG, GIF, and JPEG, with PNG as the default.
Is Poltergeist still actively maintained?
Its repository is archived and directs readers to the 1.18.1 release documentation. Validate the examples against your installed versions.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why would an element screenshot be blank?
The selector may match no element, a hidden element, or an element with zero dimensions. Verify the post-JavaScript DOM and computed size before capture.
Quick 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.
