Capybara headless Chrome tests can produce either a screenshot or a video, depending on what you need to inspect. In Rails system tests, select the Selenium headless Chrome driver with driven_by :selenium, using: :headless_chrome, then use Rails’ take_screenshot for an image or take_failed_screenshot for failure diagnostics. For a video of RSpec system examples, add the optional selenium_screencast gem and enable it with RECORD_VIDEO=1.
Choose the artifact you need
“Record” can mean saving a still image or capturing the sequence of browser interactions. Those are different workflows:
- Use a screenshot when you need to inspect the page at one point in a test or preserve an image for a failure report. Rails system tests provide
take_screenshotandtake_failed_screenshot. - Use a video when the order and timing of clicks, navigation, or other interactions matter. The optional
selenium_screencastgem records enabled RSpec system examples and writes WebM by default, or MP4 when configured.
Capybara provides Selenium-backed Chrome and Chrome-headless driver registrations; the standard headless registration is :selenium_chrome_headless. Rails system tests use the corresponding Rails declaration, driven_by :selenium, using: :headless_chrome. Capybara describes changing “from fast headless mode to an actual browser with no changes to your tests,” so the choice of headless driver need not dictate how the test itself is written.
Run Rails system tests in headless Chrome
In test/application_system_test_case.rb, set the system-test driver:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
- individuals with color vision defect should see a different figure from individuals with normal color vision.
- Makes use of the peculiarity that in red-green blindness, blue and yellow appear remarkably bright compared with red and green
- Diagnostic plates: intended to determine the type of color vision defect
- Ishihara Test Chart Books for Color Deficiency 24 Plates with usar manual
require "test_helper"
class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
driven_by :selenium, using: :headless_chrome
endThis selects Selenium with Rails’ headless Chrome option for the system test case. Use the same test steps you would use for the browser workflow you are checking; the driver declaration is the part that chooses headless Chrome.
Save a screenshot during a test
Call Rails’ helper at the point where the page state is useful to inspect:
take_screenshotThis is useful when the test passes but you want to preserve a particular screen, or when a failure occurs later and the final page would not show the earlier state. Rails also provides take_failed_screenshot for failure diagnostics. In the documented Rails system-test setup, the failed-screenshot helper is included in teardown, so failure capture does not require placing a manual screenshot call at every assertion.
Make failure images useful
- Use an explicit
take_screenshotimmediately after the state you want to inspect if the eventual failure screen may differ. - Use the failed-screenshot behavior for the final state associated with a failing system test.
- Ensure your CI job retains the files generated by the test run as downloadable artifacts. The precise artifact-upload setting depends on the CI system; the Rails helper provides capture, not the CI retention policy.
Record RSpec system examples as video
For a sequence rather than a single frame, use the optional selenium_screencast gem. Add it to the test group:
bundle add selenium_screencast --group testRequire the RSpec adapter once, for example in rails_helper.rb or a support file loaded by it:
require "selenium_screencast/rspec"Then enable recording for the run by setting the environment variable:
RECORD_VIDEO=1 bundle exec rspec spec/system/checkout_spec.rbThe gem’s documented integration uses Chrome DevTools screencast. It records each enabled system example and saves video files under the configured output directory. WebM is the default output format; MP4 can be used when configured. Because the output directory and format can be configured, check the recorder’s configuration for the exact settings used by your project rather than assuming a universal path.
When to prefer video over screenshots
- Use a still image for a simple layout, missing text, or unexpected final state.
- Use video when the sequence itself is evidence: for example, an interaction changes the page and a later step reveals the defect.
- Use both only when each adds useful information. A video can show progression; a failure image is quicker to scan and can be easier to retain in bulk.
Video recording is an optional layer, not a requirement for headless Chrome or for Rails screenshots. Keep it enabled only for the examples and runs where the additional interaction trace helps diagnose a problem.
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 →Configure remote Selenium for Docker or CI
A browser running in a separate container or on a remote Selenium service cannot be treated like a browser located inside the application container. Rails documents using SELENIUM_REMOTE_URL and remote browser options. A system-test declaration can select remote Selenium when the environment variable is present and use Chrome otherwise:
url = ENV.fetch("SELENIUM_REMOTE_URL", nil)
options = if url
{ browser: :remote, url: url }
else
{ browser: :chrome }
end
driven_by :selenium, using: :headless_chrome, options: optionsWhen the application and browser are in different containers, the browser must also be able to reach the application server. Rails’ guidance is to bind the app server to a reachable address, commonly 0.0.0.0, and set an appropriate app_host. The correct host value depends on the network and service names in your Docker or CI setup; localhost inside the browser container refers to that container, not automatically to the application container.
- Set
SELENIUM_REMOTE_URLto the remote Selenium endpoint available to the test process. - Use the remote browser options when that variable is set, as in the example; keep a local Chrome branch if you also run the tests locally.
- Bind the Rails application server so the browser container can reach it, and configure
app_hostto use the application’s reachable address. - Run the test and retain the generated images or videos through your CI artifact mechanism.
The remote URL, app host, and container network must agree. A valid browser session alone is not enough if that browser cannot load the application under test.
Collect artifacts without overwhelming CI
Screenshots and videos solve different diagnostic problems, and their operational cost depends on your own test suite and CI environment. The cited recorder documentation does not publish numeric benchmarks for added runtime or storage, so measure those in the environment where you plan to use it.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsBest Value
- Start with failed-test images if the main need is to understand the last page state after a failure.
- Enable video selectively when the interaction sequence matters, especially if retaining every video would create too much artifact volume.
- Keep artifact collection explicit: configure CI to upload the directory or files your test setup produces, and verify that a completed job exposes them.
- Check retention and naming behavior in the recorder and CI configuration before relying on artifacts for later investigation.
No single artifact policy fits every suite. A practical approach is to start with failure screenshots, add video for selected examples or diagnostic runs, and compare runtime and storage in your own CI jobs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common recording problems
No video appears
- Confirm that the run has
RECORD_VIDEO=1in its environment. - Confirm that
selenium_screencast/rspecis required by the RSpec setup that actually loads for the run. - Check the recorder’s configured output directory and your CI upload paths. The documented behavior saves files under the configured directory, which may not be the directory your artifact step currently collects.
- Check that the example is an enabled system example; the documented integration records enabled system examples, not an indiscriminate capture of every kind of RSpec example.
A screenshot is missing from CI
- Check that the test reached the screenshot call or the failure teardown path.
- Confirm the CI job uploads the location where Rails is saving the generated image. Rails provides capture helpers, but the upload and retention step belongs to the CI configuration.
- If you need an intermediate state rather than the final failing state, call
take_screenshotwhere that state occurs.
Remote browser cannot load the app
- Check that
SELENIUM_REMOTE_URLpoints to the endpoint reachable from the test process. - Check that the app server binds to a network-reachable address and that
app_hostnames the application from the browser container’s perspective. - Do not assume a container’s
localhostreaches a different container; use the hostname or address provided by your container or CI network.
Video format is not what you expected
The recorder uses WebM by default. If the workflow needs MP4, check and set the gem’s output-format configuration; do not infer the format from the file viewer or artifact system.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a replacement for recording the interactions inside your Capybara system tests. It is useful when the job is to capture a website page as an image without setting up a browser script of your own. A GET request returns a PNG, JPEG, WebP, or PDF; see the ScreenshotNeo API documentation for the available parameters.
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 or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Recommended Free Tools
Sign up for ScreenshotNeo to get 1,000 free screenshots a month with no card.
Sources and scope
The Rails system-testing guidance establishes the driver declaration and screenshot helpers; Capybara documents its Selenium Chrome and headless registrations; and the selenium_screencast project documents its RSpec adapter, recording switch, and output formats. The exact generated-file paths, CI artifact commands, runtime cost, and storage overhead vary by configuration and are not quantified here.
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.
