Setting up Selenium server on a headless Jenkins CI build machine

A quick guide to setting up Selenium server on a headless Jenkins CI build machine
By Ryan Marshall
3rd March 2011
First grab a copy of Selenium server (formerly Selenium RC) from You might also want to symlink the versioned file to a standard location.

sudo mkdir /var/lib/selenium
sudo mv selenium-server-standalone-2.0b2.jar /var/lib/selenium
cd /var/lib/selenium
sudo ln -s selenium-server-standalone-2.0b2.jar selenium-server.jar

Assuming at least one of your browser nodes will be running on the local machine, you’ll also need a virtual framebuffer so that a browser can actually load.

On Ubuntu you can:

sudo apt-get install xvfb

The following init.d script might also be useful to help start and stop that service:


if [ -z "$1" ]; then
echo "`basename $0` {start|stop}"

case "$1" in
/usr/bin/Xvfb :99 -ac -screen 0 1024x768x8 &

killall Xvfb
Save it to /etc/init.d/xvfb and chmod 755, then confirm that it works:
sudo chmod 755 /etc/init.d/xvfb
/etc/init.d/xvfb start

You may receive a few warnings regarding fonts and such, but it’ll still work despite these. If you want the framebuffer to start automatically on system startup you can do:

sudo update-rc.d xvfb defaults 10

If you don’t already have any browsers you might also want to install something like Firefox.
sudo apt-get install firefox

Now to Jenkins, you’ll probably want to install the Selenium HQ plugin. This will allow you to configure a path to your selenium report file so that it can be linked to your projects and Jenkins will draw a graph alongside your other metrics. It also adds a custom build step for configuring Selenium, but i had issues using this due to the need for the above framebuffer.

In your project configuration, add an “Execute shell” build step. In here we’ll export a display and run Selenium as follows:

export DISPLAY=":99" && java -jar /var/lib/selenium/selenium-server.jar 
-browserSessionReuse -htmlSuite *firefox http://path/to/app 

Finally, under post build actions, tick the box for “Publish Selenium Report” and add the path to your log file from above, relative to your workspace dir.


And that should be pretty much all you need. Run a build and watch your shiny new Selenium reports roll in.
For reference, if you don’t export the display you’ll probably receive exceptions that look something like:
HTML suite exception seen:

java.lang.RuntimeException: Timed out waiting for profile to be created!

Jenkins’ shell commands run through /bin/sh instead of bash, meaning it won’t look in your standard ~/.bashrc file. 

Although, if you also want to be able to run Selenium manually then you can always stick the export command in there too.
Hope that works for you. Let me know on Twitter @labelmedia

Like this? Sign up to our newsletter for more!


Tomek 26th April 2012
thank you for this detailed instruction

a one thing that could be changed is that you can also setup environmental variable DISPLAY with value :99 in Manage Jenkins / “Global Properties” -> “Environment Variables”
Chelli 25th August 2012
Hi Sam,

I was wondering, have you installed any of the Firefox Addons to your headless Jenkins/Selenium integration? There are some firefox addons for selenium that make it possible to have richer cases, but I'm not sure how to add those add0ns to my headless firefox.
MM 22nd February 2013
You talk about Ubuntu. Will this also work on a Windows server?
SmarterThanYou 9th July 2013

What an awful question... Will anything work on a Windows server?
Mark Butler 20th August 2013
This was a great post. Thank you. Your site design looks excellent too. Very best wishes!

Add your own comment

© 2015 Label Media