Running headless Watir-WebDriver tests using a real browser

I seem to get quite a few questions from people trying to use Watir-WebDriver in headless mode using a WebDriver server and HTMLUnit. It seems to me that it’s problematic, especially when your web app contains JavaScript (who’s app doesn’t?).

The problem stems from HTMLUnit’s JavaScript support. Whilst it does support JavaScript, myself and many others have found the JavsScript support to be pretty poor as it uses its own JavaScript engine (Rhino) that no other ‘real’ browser actually uses, which sorta raises a question: are you really testing your app’s JavaScript?

The other thing about HTMLUnit is the lack of screenshot capability, as it’s purely headless, there’s no way to capture a screenshot when something goes wrong, so you’ll find yourself re-running failed tests using a different browser, which may or may not reproduce your problem. Not ideal!

Finally, running WebDriver headless tests requires you to run a Selenium Server, which is additional overhead for your tests.

But why headless?

Whilst running automated browser tests in a headless form can speed things up, the main reason I see people wanting headless watir-webdriver support is so that tests can be run on headless Linux machines, for example, a Jenkins Server. I’ve found running tests in parallel speeds things up more than headless execution can, so it’s mainly headless server support most people are after.

Enter the headless gem.

The headless gem is a ruby wrapper for Xvfb that makes it super easy to run graphical applications (such as real web browsers) on a headless machine. This gem is perfect for running headless watir-webdriver tests using a real browser.

How? It’s simple.

require 'watir-webdriver'
require 'headless'
headless =
b = Watir::Browser.start ''
puts b.title

You’ll need Xvfb installed, which is as easy as:

sudo apt-get install xvfb

Or if you’re using cucumber like me, you just need the following code in your env.rb file:

  require 'headless'
  headless =
  at_exit do

This then means you can still launch and use Firefox (or Chrome) on a headless machine.

The best thing about it though is that Watir-WebDriver’s inbuilt screenshots still work perfectly, so it captures a screenshot of the actual page even though it has no display. How awesome is that!


The headless gem makes it super easy to run real browsers on headless servers. This way you get real JavaScript support without the need to run a Selenium server, and is perfect for running your tests as part of continous integration.

Stay tuned as I’ll be writing a post soon about how to use an EC2 instance to run your headless watir-webdriver tests in the cloud, for free!

Author: Alister Scott

Alister is an Excellence Wrangler for Automattic.

24 thoughts on “Running headless Watir-WebDriver tests using a real browser”

  1. Is there a way to use this on Windows? Am I correct in saying that Xvfb is only for Linux? (I don’t know much about it other than google’ing around)


    1. Yes, Xvfb is only for Linux.
      Why would you want to use on Windows?
      My understanding is there is no such thing as a headless windows machine.
      Watir-WebDriver will run fine on Windows without being headless.


      1. I wanted to try and speed things up. I’m kind of just trying to find all the features and options of webdriver for future reference whenever my team switches to Cucumber and this looked like a better option than htmlUnit or Celerity


        1. This won’t speed things up, because it will actually be slower than running a real display, and the virtual display takes memory and CPU.
          If you’re running on Windows, you should be able to run multiple concurrent browsers without issue.


  2. Do you know if it’s possible to have multiple processes running this at the same time, without conflicts? I am trying to do just that, but get “Connection refused” errors. If I run a single instance, everything looks fine.


    1. I’m not sure to be honest. Best to raise a question on stackoverflow where you’ll be bound to find an answer.


    2. Did you ever find an answer to this?

      I’m having the same issue. I’m trying to use a combination of jenkins, ruby, watir and headless to develop a test suite. But, if two of the jenkins jobs run at the same time, one of them fails due to a conflict. This pretty much kills the entire project if it’s not possible.


  3. Awesome tutorial and blog!! I’m having a bit of a problem following your directions towards running headless firefox. Do you have any suggestions for what I’m doing wrong?

    I didn’t have FF installed on my machine, so I un-tarred the most recent firefox download into /will/firefox. Then I start up the ruby console and type in.

    require ‘watir-webdriver’
    require ‘headless’
    headless =
    Selenium::WebDriver::Firefox.path = “/will/firefox/firefox” #I think that is the executable for FF
    b = Watir::Browser.start ‘’

    After that last line I get an error about not finding firefox.
    Selenium::WebDriver::Error::WebDriverError: unable to obtain stable firefox connection in 60 seconds (
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/firefox/launcher.rb:77:in `connect_until_stable’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/firefox/launcher.rb:37:in `launch’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/firefox/socket_lock.rb:20:in `locked’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/firefox/launcher.rb:32:in `launch’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/firefox/bridge.rb:19:in `initialize’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/common/driver.rb:29:in `new’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver/common/driver.rb:29:in `for’
    from /usr/lib/ruby/gems/1.8/gems/selenium-webdriver-2.7.0/lib/selenium/webdriver.rb:81:in `for’
    from /usr/lib/ruby/gems/1.8/gems/watir-webdriver-0.3.4/lib/watir-webdriver/browser.rb:35:in `initialize’
    from /usr/lib/ruby/gems/1.8/gems/watir-webdriver-0.3.4/lib/watir-webdriver/browser.rb:18:in `new’
    from /usr/lib/ruby/gems/1.8/gems/watir-webdriver-0.3.4/lib/watir-webdriver/browser.rb:18:in `start’
    from (irb):22


    1. Usually that error means the selenium version isn’t compatible with Firefox, but unless you’re using Firefox 8+, that doesn’t sound like it’s the case.
      I’d play around with irb and see if you can find anything else out.


  4. Hi Alister, great blog and great tool! I’m trying to run watir-webdriver on mac os x jenkins slave. When I run it locally, with my own user, everything works just great. However, when I run as the “jenkins” user it executes with firefox in the background and I receive cucumber errors saying:
    Element cannot be scrolled into view: (Selenium::WebDriver::Error::MoveTargetOutOfBoundsError)


  5. This is probably the best and easiest solution for setting up cucumber + watir in headless mode for a CI server. Thanks for this post because it saved me a lot of headache trying to come up with a different solution.


      1. Let’s say you don’t want headless as default and want headless in your ‘ci’ profile, your cucumber.yml should look like:
        default: -r features –format pretty –format html –out tests_report.html
        ci: HEADLESS=true -r features –format pretty –format html –out tests_report.html

        You can even call cucumber from command line passing it:
        $ cucumber HEADLESS=true


  6. Hi Alister Scott , I have followed your instructions and tried to run texts on my mac box (OS X 10.8.5 (12F37) in the headless mode but I keep bumping into this error

    unknown driver: :HEADLESS (ArgumentError)
    /Users/vamsi/.rvm/gems/ruby-2.0.0-p247/gems/selenium-webdriver-2.35.1/lib/selenium/webdriver/common/driver.rb:49:in `for’
    /Users/vamsi/.rvm/gems/ruby-2.0.0-p247/gems/selenium-webdriver-2.35.1/lib/selenium/webdriver.rb:67:in `for’
    /Users/vamsi/.rvm/gems/ruby-2.0.0-p247/gems/watir-webdriver-0.6.4/lib/watir-webdriver/browser.rb:46:in `initialize’

    What I am missing here ? I followed your exact steps ..
    would greatly appreciate any help .


Comments are closed.