June 9, 2011

Python - Headless Selenium WebDriver Tests using PyVirtualDisplay

I need to integrate my functional UI tests (Selenium/WebDriver) with my Jenkins CI system. The problem is that my Jenkins CI server has no display, so I must run my GUI tests in a headless X-server.

A colleague pointed me to PyVirtualDisplay, a Python wrapper for Xvfb and Xephyr.

This makes running headless Python Selenium/WebDriver tests very easy.

Here is some Python code showing WebDriver with a virtual display provided by Xvfb:

#!/usr/bin/env python

from pyvirtualdisplay import Display
from selenium import webdriver

display = Display(visible=0, size=(800, 600))

# now Firefox will run in a virtual display. 
# you will not see the browser.
browser = webdriver.Firefox()
print browser.title


install PyVirtualDisplay on Ubuntu/Debian:

$ sudo apt-get install xvfb python-pip
$ sudo pip install pyvirtualdisplay


Anonymous said...

That sounds neat! I'll definitely give it a try.

Marius Gedminas said...

I have vague memories of seeing that Jenkins has a native xvfb plugin.

For buildbot jobs, I used to wrap my test-runner command with Debian's xvfb-run wrapper.

I find the PyVirtualDisplay solution (that I didn't know about) very interesting as well. You could take a screenshot when tests fail, to figure out why that happened.

Anonymous said...

Great post! Like Marius, I find that xvfb-run java -jar selenium-server-standalone-2.0b3.jar works really well if your stuck with Selenium RC.

Matt Austin said...

Very nice, I hadn't heard of Selenium before - looks very cool, especially as it can be paired with xvfb.

Prashant said...

Try xvnc plug-in for Jenkins

John said...

This code doesn't work for me on OS X Snow Leopard, I see the Firefox window.

Is there something other than PyVirtualDisplay and Selenium I need to install?

Jason said...

I agree with John this doesn't work for me on OS X 10.6. It still opens like normal.

Corey Goldberg said...

John, Jason,
pyvirtualdisplay has some dependencies (xvfb, etc). I show how to satisfy them on Ubuntu/Debian. You are on your own for Mac.



Anonymous said...

Just wanted to say this was quite helpful for me, was struggling to find docs on how to run it headless. Works with no probs, Debian wheezy.

Anonymous said...

Thanks Corey! This was a big help!

Anonymous said...

Just tested this. Exactly the solution I'm looking for! Great stuff!

Foobaz said...

thanks, work great for me. Great tip

jbianquetti said...

You should try http://testutils.org/sst/index.html

Corey Goldberg said...

yay for SST :)
I wrote the blog post while implementing this feature in SST.

jbianquetti said...

Give a try to Simple Selenium Test: http://testutils.org/sst/index.html

jbianquetti said...

Yes, I know :P

cbrunsdonza said...

Thanks, works 100% under Ubuntu 12.10 and so needed this today

Anonymous said...

I am just trying this under Redhat and this seems to stall at the
browser = webdriver.Firefox()

suggestions please

Anonymous said...
This comment has been removed by the author.
Corey Goldberg said...


can you run it *with* display turned on?

can you launch firefox from a command prompt without error? is firefox installed? is selenium installed? do you get any stack trace?

not a mind reader :)

Anonymous said...


sorry yes it turns out that selenium will not run Firefox from a script and I needed to pass in the location of the binary

ffbin = webdriver.firefox.firefox_binary.FirefoxBinary('/usr/lib/firefox/firefox')
self.driver = webdriver.Firefox(firefox_binary=ffbin)

I then ran into another bug or location problem really


I did the ugly symbolic link and everything was fine.

Thanks very much for the post.

I hope this helps the next person that reads your post

Ranveer Raghuwanshi said...

I had to install EasyProcess to get pyvirtualdisplay working.

sudo pip install EasyProcess

BTW very nice tutorial.

Teja said...

How is this headless if you are getting the screenshot by using firefox?

Corey Goldberg said...


Firefox *is* running, just inside a virtual x server. It is not displayed. So it is headless in that sense. You can run it from a server with no display attached.

Anonymous said...

Lovely, dude, lovely.... Just what I was in need of.