Watir 6.10.0 is now available on RubyGems! It features a new locator and other element location improvements.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.10"

Locating Elements by Text

Currently, the :text locator behaves differently depending on whether it is provided a value of RegExp or String. A String value will match any text in the DOM, but a RegExp will only match visible text.

We have decided to change the RegExp behavior to match the String behavior and locate based on any text found in the DOM, and create a new locator :visible_text that will filter on only text that is actually displayed on the screen. As such the :text locator will be effectively equivalent to the #text_content method, and the :visible_text locator is effectively equivalent to the #text method.

The actual change to the behavior of text: <RegExp> will not be made until a future release, but as of this release, if Watir sees that the update might be a breaking change in your code, it will give a deprecation warning with a suggestion to change to using :visible_text.

<div>Foo<span style="display:none;">Bar</span></div>

element1 = browser.div(text: 'FooBar')
element2 = browser.div(visible_text: 'Foo')
element1 == element2 # => true

element2.text_content # => 'FooBar'
element1.text # => 'Foo'

Custom Attributes

One of the impressive things Watir does is to parse the HTML5 IDL to obtain a list of all of the valid attributes for each valid html element in the spec. This allows Watir to provide classes that correspond to each element, allows those classes to be initialized with its corresponding attributes as locators, and provides those classes with custom methods to obtain each attribute’s value.

For this release we decided to remove the restriction on only being able to locate elements with a limited number of valid HTML5 attributes. Methods will still only be created for valid attributes, but any locator that Watir doesn’t recognize it will now assume that it is an attribute and attempt to locate an element with it like:

<div custom-attribute="custom"></div>

element = browser.div(custom_attribute: 'custom')
element.attribute_value('custom-attribute') # => 'custom' 

As a result, people can now locate custom Angular elements without needing to use watir_angular, and can locate various div and span elements that (incorrectly) use the name attribute.

Selenium vs Watir Locators (Implementation)

Watir’s powerful location strategy is implemented by default by converting some of the locators provided by the user into a complicated XPath call, and then, if necessary, filtering the results of that call with the remaining locators. Until now, Watir has provided limited support for the standard Selenium locators. This release will rely more heavily on using the Selenium locators directly without any XPath conversion where possible (a minor performance enhancement). Additionally, while most of the Selenium locators can be used with any Watir::Element subclass and can be mixed and matched with any other Watir locators and will accept either String or RegExp values, there are three Selenium supported locators that can’t do any of these things. As of this release, :link, :link_text, and :partial_link_text are deprecated in favor of the new :visible_text locator which behaves like all of the other Watir locators.

See the Changelog for the complete history of updates.