Enabling Cuprite: A Headless Chrome Ruby Driver for Capybara

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).

https://github.com/rubycdp/cuprite

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!