Skip to content
Chrome driver for Capybara using Chrome's remote debugging protocol
Branch: master
Clone or download
Latest commit dd22c69 May 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin initial commit Jun 18, 2018
lib Bump version Nov 14, 2018
.gitignore initial commit Jun 18, 2018
.rspec initial commit Jun 18, 2018
.travis.yml initial commit Jun 18, 2018
Gemfile initial commit Jun 18, 2018
LICENSE.txt initial commit Jun 18, 2018 Transfer to sandro May 9, 2019
Rakefile More readable rake tag output Aug 23, 2018
capybara-chrome.gemspec Transfer to sandro May 9, 2019


Use Capybara to drive Chrome in headless mode via the debugging protocol.


Add this line to your application's Gemfile:

gem 'capybara-chrome'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capybara-chrome

Using Docker

Add this line to your Dockerfile to install Chrome:

  RUN curl -sL -o chrome-stable.deb ; dpkg -i chrome-stable.deb ; apt-get install -fy; rm -rf /var/lib/apt/lists/*

In my experience, headless Chrome cannot be run as root, so you need to run rspec as an unprivileged user and use this flag with docker run

docker run --security-opt seccomp=unconfined


Capybara.javascript_driver = :chrome
Capybara::Chrome.configuration.chrome_port = 9222 # optional

The standard port for the debugging protocol is 9222. Visit localhost:9222 in a Chrome tab to watch the tests execute. Note, the port will be random by default.

Using thin

I like using thin instead of WEBrick as my Capybara server. It's a little faster, gives me greater control of logging, shows errors, and allows me to disable signal handlers. Below are my settings:

Capybara.register_server :thin do |app, port, host|
  require "rack/handler/thin"
  Thin::Logging.silent = false
  # Thin::Logging.debug = true # uncomment to see request and response codes
  # Thin::Logging.trace = true # uncomment to see full requests/responses, Host: host, Port: port, signals: false)
Capybara.server = :thin


Use byebug instead of binding.pry when debugging a test. The Pry debugger tends to hang when visit is called.

Using the repl

You can use the capybara-chrome browser without providing a rack app. This can be helpful in debugging.

[2] pry(main)> driver =, port:9222); driver.start; browser = driver.browser
[3] pry(main)> browser.visit ""
=> true
[4] pry(main)> browser.current_url
=> ""
[5] pry(main)>

Further, you can run a local netcat server and point the capybara-chrome browser to it to see the entire request that's being sent.

Terminal one contains the browser:

[1] pry(main)> driver =, port:9222); driver.start; browser = driver.browser
[2] pry(main)> browser.header "x-foo", "bar"
[3] pry(main)> browser.visit "http://localhost:8000"

Terminal two prints the request

$ while true; do { echo -e "HTTP/1.1 200 OK \r\n"; echo "hi"; } | nc -l 8000; done
GET / HTTP/1.1
Host: localhost:8000
Connection: keep-alive
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/68.0.3440.106 Safari/537.36
x-foo: bar
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
Accept-Encoding: gzip, deflate


A video showing capybara-chrome running in a browser tab

Preview of visualizing capybara-chrome

A video demonstrating debugging an rspec test with byebug

Preview of debugging capybara-chrome

A video showing capybara-chrome running against a netcat backend

Preview of debugging capybara-chrome with netcat


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.