Run and debug selenium tests inside a docker container. With a browser you can see via VNC :)
Clone or download
Latest commit 1d81913 Oct 6, 2018

Selenium Cucumber Docker

This repo explains how to setup Ruby/Cucumber/Capybara tests in one docker container which drive a browser in a separate standalone Selenium container.

See support/env.rb for the magic.

Getting started

We're going to start two containers: one which holds chrome and the selenium hub and a second which holds ruby and runs our tests:

Basic steps

#start the two containers, but specifically run bash inside the ruby container

docker-compose run ruby bash
# Note: This could take a few min the first time you run...

# Open another terminal session connect via VNC to view the browser container:
open vnc://:secret@

#now run the tests in the first container:

#when you're done, you can exit the ruby container

#Now stop the containers from the host machine
docker-compose down


Getting an error that port 5900 is already allocated.

You may have "Screen sharing" enabled on your mac. Go to "Settings" > "Sharing" and untick the "Screen Sharing box"

start the selenium chrome container in the background:
docker run -d -p 4444:4444 -p 5900:5900 selenium/standalone-chrome-debug

# wait while it starts up so we can connect...
sleep 5

# need to see the browser? Connect via [VNC]( (password is 'secret')
# You can also do this via the Finder: Go > Connect to server (cmd+k)
open vnc://:secret@

#build a container with the gems specified in our Gemfile and Gemfile.lock
docker build . -t ruby_test

# start it up and run cucumber
docker run -v "$(PWD)":/app -it ruby_test

Advanced usage

Use Docker compose!

docker-compose up

Using the 'pry' debugger.

You can add a step And I debug to your features to open the pry interactive debugger which lets you write code to interact with the browser in real-time without restarting your tests.

Use Scenario Outlines

You can use "scenario outlines" to quickly run through the same scenario with different variables.

Go headless

If you don't need to see the browser, you can use a smaller/faster headless Selenium container:

docker run -d -p 4444:4444 -p 5900:5900 selenium/standalone-chrome

Manually start a browser session

You can manually start a browser session in the Selenium container:

  • Browse to
  • Click "Create session"
  • Select "Chrome"
  • Connect via VNC (see above) open vnc://:secret@