Watir 6.12.0 is now available on RubyGems. Three new contributors to Watir and several great new features available.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.12"

New Contributors

First of all, thank you for taking the time to contribute:

• Aleksandar Kostadinov (akostad)
• Gijs Paulides (sjieg)
• John Fitisoff (jfitisoff)

Locating Elements with Custom Attributes

We recently allowed elements to be located with non-HTML5 compliant attributes. These were required to Symbol instances like all other locators.

This element:

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

can be located with this code:

browser.div(custom_attribute: "foo")

Since Symbol instances can’t have dashes, and most attributes use dashes instead of underscores, we convert underscores to dashes. That means this element could not be located:

<div custom_attribute="foo">Foo</div>

To allow for underscores in custom attributes, Watir now supports custom attributes as keys with String instances:

browser.element("custom_attribute" => "foo")

Additional Element Features

Get Array of Element from an ElementCollection when using a Range

browser.divs[2..4] 

Get attribute values with Symbol as well as String values

browser.element.attribute_value :data_type

Element#flash can do a bunch more interesting things:

browser.element.flash :rainbow
browser.element.flash :slow
browser.element.flash :fast
browser.element.flash :long
browser.element.flash color: ["red", "white", "blue"]

Logger

Users can now ignore specific warnings thrown by the Watir Logger.

As we move toward Watir 7, we are deprecating a number of features and throwing warnings that look like this:

2018-07-23 02:12:37 WARN Watir [DEPRECATION] ["wait_while_present"] Watir::Window#wait_while_present is deprecated. Use Watir::Window#wait_while(&:present?) instead.

If you want to ignore this specific warning in your tests:

Watir.logger.ignore :foo

If you want to ignore all deprecation warnings in your tests:

Watir.logger.ignore :deprecations

Waits

Message values for waits can now be instances of Proc instead of just String

msg = Proc.new { |obj| "waiting for #{obj.inspect}" }
browser.element.wait_until message: msg, &:present?

Also Element#wait_while_present and Element#wait_until_present now have slightly different behaviors from the “to_proc” syntax of wait_while(&:present?) and wait_until(&:present?). For most situations you want to use this latter syntax.

But what if you have this element:

<div class="here">Foo</div>

and you locate it with this code:

element = browser.div(class: "here")

and then some dynamic event caused the element class to change:

<div class="not-here">Foo</div>

Because of how Watir caches elements for performance reasons, this will time out, because Watir will just keep verifying that the cached element is still there:

element.wait_while(&:present?)

In this case we want the element to be looked up from scratch during the polling, which is what this does:

element.wait_while_present

Similarly for #wait_until_present, the scenario is when an element is located, then goes away, and you want to wait for it to come back.

This will throw a Stale Element exception:

element.wait_until(&:present?)

This will return when the element has come back:

element.wait_until_present

Deprecations

1. Don’t use #present? or #visible? if you need to know if an element has gone stale, use #stale? for this. Right now calling the same method multiple times can result in different values even when the state of the DOM has not changed, which is undesirable.

2. Don’t use ordered parameters to locate elements. All Watir location needs to be done as part of a Hash. This increases flexibility to easily allow adding additional locators in the same selector and to improve consistency across code bases.

# Bad:
browser.element(how, what)

# Good:
browser.element(how: what)

3. I wrote a whole blog post on how we are changing #visible?

4. I discussed above under what special circumstances you should use Element#wait_while_present and Element#wait_until_present. Right now these methods can be used with non-Element classes, and support for that will soon be removed. It is safe to use wait_while(&:present?) and wait_until(&:present?)

See the Changelog for the complete history of updates.