Watir 2.0

Recently, Watir 2.0 got released! This post will try to explain all the important changes what this version brought to the automated testing world.

About FireWatir

There is no FireWatir 2.0 and there won’t be any new releases of FireWatir anymore due to the fact that JSSH extension, which is used to control Firefox by FireWatir, is not available for Firefox versions 4 and newer. This means that we’ve decided that it’s time for the FireWatir to retire. We’ve released a version 1.9.3 which doesn’t have any new functionality, but has a less strict dependency requirement for common-watir gem so you could use Watir 2.0 and FireWatir 1.9.3 together in your Bundler’s Gemfile if really needed. We recommend you to start using Watir-WebDriver Firefox driver instead if you want to test your application on Firefox.

Zero based indexing

The next big change is zero based indexing. As you might know then Watir has used one based indexing so far. For example, if you are using Watir 1.x and you’d like to access first div element on the page, you’d write code like this:

browser.div(:index => 1)

In Watir 2.0 and newer, you have to write code like this instead:

browser.div(:index => 0)

That change is done to be more compatible with Watir-WebDriver and the Ruby (and many other) programming language itself. For example, the first element in the array has an index of 0. That’s it, no more remembering if the indexing started from 0 or 1 in Watir. It’s consistently 0. This also applies to tables, rows and cells:

table = browser.table(:class => "sometable")

will get the first row

first_row = table[0]

will get the first cell

first_cell = first_row[0]</code>

You can revert to one-based-indexing to make the integration from Watir 1.x to Watir 2.0 easier and faster for your existing tests by using a special option:

require "watir" Watir.options[:zero_based_indexing] = false

Remember that this option will be probably removed in the not-too-soon-future, so you’d better edit your tests to start working with zero-based-indexing. I’m pretty sure you want to do that since starting from now Watir will become more and more compatible with Watir-WebDriver.

Multiple locators

Starting from Watir 2.0 ALL elements support multiple locators for searching. Even browser#element. In case you don’t know what this feature is, then here is an example for searching for the span element with a specific name AND class:

# only span with name "something" AND class "else" will be found browser.span(:name => "something", :class => "else")

You can also search all elements by :xpath and :css locators now, but please remember that these are considerably slower than any other locators.

Locators for collections

When you were dealing with element collections in Watir 1.x then you had to use Ruby’s Enumerable methods for filtering out elements with specific criteria. Let’s say that we’re interested only in the images, which have a name of "logo":

browser.images.find_all {|image| image.name == "logo"}.each do |image|

only images with the name of “logo” will print out their html

puts image.html end</code>

In Watir 2.0 you can also specify locators for the collections methods so it’s a lot easier to filter out the elements in interest. The above example in Watir 2.0 would be:

browser.images(:name => "logo").each do |image| puts image.html end

Of course you can use multiple locators for the collection methods too!

Default locator

Have you done something like this in your tests:

browser.span(:class => "something").div(:index => 1).span(:class => "else")

Notice the usage of :index => 1 to specify that the span with class "else" should be inside of the first div. In Watir 2.0 you can use the syntax below instead:

browser.span(:class => "something").div.span(:class => "else")

In other words - if no other locators are specified, then :index => 0 will be used as a default. Convenient, eh?

Aliased methods

Have you typed browser.tr instead of browser.row? What about browser.td instead of browser.cell? Since most of the html elements are accessible by the same method name as their tag then it just makes sense to have methods for these elements too. In Watir 2.0 you can use #tr, #trs, #td, #tds, #a, #as, #img and #imgs! Consistency is good!

Conclusion

Watir 2.0 tries to be the best “driver” for IE browser by adding all these missing features and incompatibilities between Watir-WebDriver. Our goal is to minimize that gap even further. Stay tuned for future releases!