Alfredo Motta

Dockerized Rails Capybara tests on top of Selenium

If you use Docker to deploy your Rails application you may want to use the same infrastructure to run your tests.

However the setup of your Selenium browser tests is far from obvious with Rails and Docker and may generate some confusion 1 2 3 4 5.

The short answer is available in this repository on Github. For the long answer keep reading this blog post for a step by step tutorial!

Dockerize Rails

Let’s start by creating a Docker container to run your application. First we create a simple rails hello world app with the following commands:

then we add the following to your Gemfile :

Run bundle install  and bundle exec rails server  to make sure that our app is accessible at http://locahost:3000 . Also run  rails generate rspec:install to initialize the spec directory.

We will now use the  Gemfile  and the  Gemfile.lock to set up of our Docker container. Let’s create a Dockerfile in the root of the project with the following:

The Dockerfile downloads the Ruby image called ruby:latest  and installs  build-essential ,  nodejs and the gems specified in our Gemfile including Rails.

Connect to a remote Selenium server

To run our tests we need a Selenium server running somewhere. By default the  capybara  and  selenium-webdriver gems spawn the selenium server automatically for us when we run our specs. But nothing stops us to select a different remote selenium server! Let’s do that.

First go to, download the latest tar and run the server with:

Now connect Capybara with the Selenium server we just started. Inside  rails_helper.rb add the following:

This will instruct  Capybara to connect to the remote Selenium instance we are running. Finally add to the RSpec configuration the following lines:

This will tell the  Selenium server that the app it must visit is the one spawned by Capybara in our localhost. If you run  bundle exec rspec you should see the following in the Selenium server output:

The server correctly received the calls from Capybara, visited the test app and completed the test successfully.

Dockerize Selenium

The next step is to dockerize our Selenium server to run our browser tests inside a Docker container instead of our localhost . First, we need to create a docker-compose  file to run our application:

The app has two services running inside the corresponding containers. The test service is running the rails container specified in our Dockerfile . The build entry specifies the location of the  Dockerfile. The command entry specifies the command to execute when the service is invoked. In our case we want to run our tests. container_name,  environment and depends_on  are self explicative. Finally the volumes instruction link our code into the container. Finally, the Selenium service is pretty easy to set up because there is a dockerized version of the server ready for us in  selenium/standalone-firefox !

Let’s now go back to our rails_helper . We need the following to use the Selenium remote server:

Notice that Docker by default makes the Selenium service available at the  http://selenium host using the name specified in the docker-compose file. The port is the default one.

The RSpec configuration changes as follows:

You may be surprised by these four magic lines:

these instructions retrieve the ip address of the container and pass it to Capybara and in turn to Selenium such that it will be able to retrieve the pages to test. In the basic Selenium remote example this configuration was not necessary because our test app was running on our localhost.

Lunch the tests!

To run our tests at this point all we need is:

and you should see something similar to the following:


In this blog post I have presented how to run your Selenium tests in a Docker environment. For people new to Docker it may be quite hard to fit all the pieces together and I hope this will be helpful to some fellow engineer.

If you enjoyed this blog post you can also follow me on twitter.
Looking forward to hearing your comments!


  1. StackOverflow: Dockerized selenium browser cannot access Capybara test url
  2. StackOverflow: How to configure Capybara to run tests in a dockerized Selenium Grid?
  3. A gist file with the same setup presented here
  4. Another blog post on the same topic
  5. Docker compose tutorial


Leave a Reply to Jaron Gao Cancel reply

Your email address will not be published. Required fields are marked *

Answer the question * Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.