Watir 6.0 Beta 5 is now available on rubygems! Watir 6.0 depends on Selenium 3.0, and it will have its production release once Selenium 3 is released. We’re continuing to update and simplify the code in the meantime. This release allows elements in collections to be relocated when stale, adds a new visibility locator, and provides updated error messages when unable to locate elements.

To install:

gem install watir --pre

or in your Gemfile:

gem "watir", ">= 6.0.0.beta5"

Relocating Elements from Collections

This new feature addresses one of the most common confusions people have with Watir. Watir now allows things like iterating over a collection of elements, even when the DOM changes:

browser.links.each do |link|
  link.click
  expect(browser.title).not_to eq '404 Not Found'
  browser.back
end

Note - the above code is for example only, it is not the recommended way to verify working links.

The above code would previously have provided this not-very-helpful error message:

Watir::Exception::UnknownObjectException: unable to locate element, using {:element=>#<Selenium::WebDriver::Element:0x2836d06ee67909a id="0.18715359551127864-1">}

Visible Locator

As Single Page Apps become more common, there are often multiple similar forms that exist on the page at the same time, while only one of them is visible. For instance, a create object modal and an edit object modal, or a log in modal and a sign up modal. Rather than needing to create multiple page objects if the forms have the same characteristics, or needing to use index locator to pick which form to use, Watir now supports locating based on a visible locator:

browser.text_field(name: "username", visible: true)

If there are multiple forms with the a name attribute of “username”, this locator will return the first one that is visible on the page.

Error messages

Previously, error messages for when elements were not found only returned selector information for the most nested element. For instance, if this iframe was present, but the div inside it was not, this used to be the result:

browser.iframe(id: 'one').div(id: 'bar').wait_until_present
# => Watir::Wait::TimeoutError: 'waiting for {:id=>"bar", :tag_name=>"div"} to become present'

To provide more information on the exact problem, the error will now look like this:

browser.iframe(id: 'one').div(id: 'bar').wait_until_present
# => Watir::Wait::TimeoutError: 'waiting for {:id=>"foo", :tag_name=>"iframe"} --> {:id=>"bar", :tag_name=>"div"} to become present'

See the Changelog for a complete list of updates.