Index / Blog / Open-sourcing Cuprite Ruby driver

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

March 2020

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|, window_size: [1200, 800])

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, 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 = [""]


page.driver.browser.url_whitelist = [""]

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!

Evrone always encourages the developers to work on what they love and contribute back to the software world by writing open-source, that's how Cuprite Ruby driver for Capybara was born. Under the hood Cuprite uses Ferrum, we hope that both of the drivers will be useful in the development of the projects.
Dmitry Vorotilin
Team Lead,
Let’s talk about you
Attach file
Files must be less than 8 MB.
Allowed file types: jpg jpeg png txt rtf pdf doc docx ppt pptx.
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.