Update: 22 August 2011: Please see: watirwebdriver.com for a detailed guide to Watir-WebDriver
Update: 22 July 2011: I have updated quite a number of things that have changed since the earlier releases
Watir-WebDriver is a really great tool; Jari Bakken‘s done a really good job of it. There’s not a huge amount on the web about it, how to get it up and running and use it. I’m aiming to fix that here.
For those who don’t know what Watir-WebDriver is, it’s basically a nice Watir (ruby) implementation on WebDriver, so it gives you four browsers (three real, one headless) using one neat API, out of the box. The thing I like about it is you don’t need to use JRuby (like Celerity), which means it plays nice with Cucumber (although Cucumber does work under JRuby).
I’ve written about how Watir, WebDriver and Selenium all fit together before, so this post aims to be a lot more hands-on.
Getting Watir-WebDriver Running
There are essentially two components you need: the Watir-WebDriver ruby gem, and the remote WebDriver server. The remote WebDriver server is only needed if you want to run your tests in headless mode without a real browser (or want to use Opera). You obviously need ruby first but I won’t detail that here. You can find info about ruby versions etc. at watir.com. If you’re on Mac or Linux, I strongly suggest using RVM and bundler.
The Watir-WebDriver ruby gem
It’s a simple matter of opening a command prompt and typing:
gem install watir-webdriver (windows); orsudo gem install watir-webdriver (osx or linux – better to use RVM and bundler)
The remote WebDriver Server
This is the slightly tricky part. This is so that WebDriver can run headless without a real browser, and isn’t needed for real browser support (bar Opera). The quickest easiest way to get up and running is to download this java jar file, open a command prompt where you have saved it, and run:
java -jar selenium-server-standalone-2.0b1.jar
You can also specify the startup and max memory allocated, which is handy when running large test suites.
java -Xms1024M -Xmx2048M -jar selenium-server-standalone-2.0a7.jar
You need to have this java server running whenever using WebDriver, but it’s easy enough to bootstrap it.
Update: Jari has pointed out you can run the server programmatically which is even better:
require 'selenium/server'
server = Selenium::Server.new("/path/to/jar", :background => true)
server.start
# run your tests
server.stop
First Impressions
Waiting in Watir-WebDriver doesn’t seem as straightforward as with Watir, probably due to the underlying drivers, but fortunately there’s an inbuilt waiting library to use (also available in Watir 1.6.7+):
Watir::Wait.until { ... }: where you can wait for a block to be trueobject.when_present.set: where you can do something when it’s presentobject.wait_until_present:; where you just wait until something is presentobject.wait_while_present:; where you just wait until something disappears
Hello Watir-WebDriver
It seems pertinent to start with a google search example.
Hello Watir-WebDriver in three browsers
These three browsers seem to work very similarly, but obviously Internet Explorer will only run on Microsoft Windows.
require 'rubygems'
require 'watir-webdriver'
b = Watir::Browser.new :chrome
b.goto 'www.google.com'
b.text_field(:name => 'q').set 'Watir-WebDriver'
b.button(:name => 'btnG').click
b.div(:id => 'resultStats').wait_until_present
puts "Displaying page: '#{b.title}' with results: '#{b.div(:id => "resultStats").text}'"
b.close
The only difference for Firefox:
b = Watir::Browser.new :firefox
The only difference for IE:
b = Watir::Browser.new :ie
Hello Watir-WebDriver in Headless (HTML Unit)
I imagine this is the most anticipated feature for Watir users, as it means your tests run much faster, and you can still use ruby (unlike Celerity which uses JRuby). The script is fairly straightforward, you simply specify the hostname for your WebDriver server you started above. You need to specifically enable JavaScript by creating a capabilities profile.
require 'rubygems'
require 'watir-webdriver'
include Selenium
capabilities = WebDriver::Remote::Capabilities.htmlunit(:javascript_enabled => true)
b = Watir::Browser.new(:remote, :url => 'http://127.0.0.1:4444/wd/hub', :desired_capabilities => capabilities)
b = Watir::Browser.new :firefox
b.goto "www.google.com"
b.text_field(:name => "q").set "Watir-WebDriver"
b.button(:name => "btnG").click
b.div(:id => "resultStats").wait_until_present
puts "Displaying page: '#{b.title}' with results: '#{b.div(:id => "resultStats").text}'"
b.close
Sample Timings
As an experiment, I looped the Google Search script above 100 times to measure and compare the execution times.
- Internet Explorer 8 on Windows 7: 400 seconds
- Firefox 3.6 on Mac OSX: 277 seconds
- Headless HTMLUnit on Mac OSX: 269 seconds
Very surprisingly, the headless run wasn’t much quicker at all. This may be due to running the test on Google over the Internet and not a local application.
Caveat Emptor
There are a number of differences between Watir-WebDriver and Watir. The main ones that are important to me are:
Zero based indexing as opposed to 1 based
For example,
In Watir/FireWatir: this finds the first table on a page:
puts b.table(:index => 1).text
But in Watir-WebDriver, it finds the second table on a page.
Attaching to windows
Attaching to new windows (for example pop-ups) has been fairly straightforward in Watir with its attach method, which is missing in Watir-WebDriver. It looks like you can iterate through a collection of windows in Watir-WebDriver using browser.windows, but I haven’t tried this out yet.
Summary
Watir-WebDriver is a very solid testing tool that uses a great browser automation engine (WebDriver) with a clean ruby API (Watir). I believe it will be a popular choice amongst testing teams, particually those using it for ATDD through Cucumber and running it as headless on a continuous integration server.
Further Reading
