Watir 6.2 Released!

Written by: Titus Fortner on February 20, 2017

Watir 6.2.0 is now available on RubyGems! Several exciting new features have been added for this release.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.2"


Adjacent Element Location

One of the goals of Watir is to keep users from ever having to write XPath. Why? Because it is difficult to read and difficult to write well enough to avoid brittleness. Until now, accessing adjacent elements required users to write XPath.

Locating Single Elements:

  • Element#parent returns the element that exists one level up in the DOM from the base element.
  • Element#preceding_sibling returns the Element that exists at the same level in the DOM immediately prior to the base element.
  • Element#following_sibling returns the Element that exists at the same level in the DOM immediately after the base element.
  • Element#child returns the Element that exists one level down in the DOM from the base element.

Locating Element Collections

  • Element#preceding_siblings returns an ElementCollection of all elements that exists at the same level in the DOM immediately prior to the base element.
  • Element#following_siblings returns an ElementCollection of all elements that exists at the same level in the DOM immediately after to the base element.
  • Element#children returns an ElementCollection of all elements that exists one level down in the DOM from the base element.

All of these methods accept both :index and :tag_name parameters.

For instance, this code:

table_cell = browser.td(text: 'My data')
grandparent_table = table.parent(tag_name: 'table', index: 2)

Note that index is base 1 here. Assuming this cell is in a nested table, then index: 1 returns the parent HTMLElement::Table, and index: 2 returns the grandparent HTMLElement::Table. Either way it skips past all of the tr and tbody elements to match the correct tag_name.

No More XPath!

Keyword Support

If you’ve ever gotten an UnknownObjectException with an obscure locator that’s required you to hunt through a bunch of files trying to figure out which one is broken, this is the fix. You can now set a keyword on an element which will show up in the error allowing for easier identification.

This code:

element = browser.div(id: 'foo')
element.keyword = 'foo'
element.click

Now gives this error:

Watir::Exception::UnknownObjectException: timed out after 1 seconds, waiting for 
#<Watir::Div: keyword: foo located: false; {:id=>"foo", :tag_name=>"div"}> to be located


Behavior of Element#wait_while_present

As of this release, Element#wait_while(&:present?) and Element#wait_while_present will have slightly different behaviors. The scenario is when you locate an element by a specific selector, and while the element itself is still there, the signature by which you located it has changed. For instance if you locate:

<div class='foo'>

with:

foo = browser.div(class: foo)

but some javascript or CSS transition happens to change the class name to something like:

<div class='bar'>

In one sense the element object is still there, but the Watir way of evaluating an element is whatever element is at the provided address, in which case this element no longer exists. With this update, Element#wait_while(&:present?) will timeout because it continues to see the element object; and Element#wait_while_present will exit because it is evaluating the selector is as expected and not just the object. Feel free to ask us on the Watir channel in Selenium Slack if you have specific questions about the reasons behind this particular implementation.

See the Changelog for the complete history of updates.

Tags:

Releases