Cuprite: headless Chrome Ruby driver for Capybara
Cuprite is a pure Ruby driver for Capybara that allows you to run Capybara tests on a headless Chrome or Chromium using Ferrum under the hood
Ferrum + Capybara = Cuprite
Cuprite is a driver for Capybara that uses Ferrum — a minimal-dependency pure-Ruby driver for running headless Google Chrome instances.
If you’re already using Capybara, Cuprite gives you all the benefits of Ferrum, but without the overheads of having to switch APIs. Because Ferrum employs Chrome's native DevTools Protocol (CDP), it doesn't need anything special in order to operate Chrome or Chromium in headless mode, unlike some alternative solutions.
Enabling Cuprite
Add these lines to your Gemfile
and run bundle install
.
gem "cuprite", group: :test
Next, add the following to your test setup:
require "capybara/cuprite"
Capybara.javascript_driver = :cuprite
Capybara.register_driver(:cuprite) do |app|
Capybara::Cuprite::Driver.new(app, window_size: [1200, 800])
end
If you already have tests written using Poltergeist, then transitioning to Cuprite shouldn't be any more complicated than the above — Cuprite aims to have an API consistent with Poltergeist's where it's reasonably able to.
Controlling the browser
You can synthesise mouse events with page.driver.click
, scrolling with page.driver.scroll_to
, and key presses with element.send_keys
(keystrokes are sent to a specific DOM node).
Using page.driver.headers
, you can override the request headers that are sent, and page.driver.add_headers
to append headers to the default set (the changes apply to all subsequent HTTP requests until the end of the request).
Limiting scripting
Sometimes you want to run a test in a constrained environment, and Cuprite has the tools to do this in the form of white- and blacklists, which if populated specify the URL prefixes which are permitted or blocked from script execution. If you don't specify a whitelist, all scripts not matching the URLs in the blacklist will be permitted; if you do, only scripts from the URLs listed will be executed. Careful use of these lists can help speed up your test runs: for example, do you need your standard web analytics scripts executing in your tests?
Specifying the URL prefixes is as easy as providing a list:
page.driver.browser.url_blacklist = ["http://www.example.com"]
and
page.driver.browser.url_whitelist = ["http://www.example.com"]
Under the hood
If the Cuprite API doesn't do what you need for your tests directly, you can also get access to the underlying Ferrum instance for full control in your tests, for example:
browser = page.driver.browser
browser.mouse.move(x: 123, y: 456).down.up
The browser
object exposes the full breadth of APIs that Ferrum has to offer: navigation, debugging, script execution, DOM manipulation, screenshot generation, traffic analysis, and complete fine-grained mouse and keyboard event synthesis: everything you could need for automated testing of a website or app, right at your fingertips!