Watir 7.2 is now available on RubyGems. Shadow DOM! Advanced Scrolling! Bug Fixes! Minimum requirements of Selenium 4.2 and Ruby 2.7

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 7.2"

Shadow DOM

Shadow DOM implementations have increased considerably in the past few years. There are 3 parts to accessing Shadow DOM content - identifying the host element, switching to the shadow_root of that element, and then locating children elements from there.

For example:

shadow_host = browser.div(id: 'shadow_host')
shadow_root = shadow_host.shadow_root
_shadow_content = shadow_root.span(id: 'shadow_content')

Shadow DOM is a bit tricky with Watir, because it does not support Watir’s standard approach for locating elements. Justin figured out a good solution for this to get it working. A more performant approach might be possible.

Advanced Scrolling

Watir incorporated Alex’s excellent watir-scroll.gem in Watir 6.16. It uses JavaScript to move the entire page by the desired amount.

This does not work if you have nested frames or need to scroll a portion of the screen. This release includes Scroll#from, which allows you to set that origin. Think of it like moving the mouse to a specific point on the screen and then using a scroll wheel.

Using this from your browser:

browser.scroll.from(8, 11).by(0, 225)

This sets the origin (“moves the mouse”) starting from the upper left of the browser viewport 11 pixels down and 8 pixels to the right. From that origin, it then scrolls down 225 pixels.

From the element:

browser.footer.scroll.from(0, -50).by(0, 200)

This sets the origin (“moves the mouse”) starting from the “in-view centerpoint” of the element, 50 pixels up. From that origin, it then scrolls down 200 pixels.

To bring the element into viewport using the official driver approach instead of JavaScript, scroll to :viewport:

browser.footer.scroll.to(:viewport)

Finally, I did not replace the Scroll#by implementation because there are too many issues with the way the browsers are currently implementing it.

Capabilities Fixes

There were several scenarios I thought were implemented in 7.0 that it turns out were not.

You can now initialize your browser session by passing in a Hash like this:

options = {browser_name: 'firefox', prefs: {foo: 'bar'}}
service = {port: 1234}
Browser.new(options: options, service: service)

Watir will figure out what browser to use based on the other information provided, and will default to “chrome.”

Deprecating Selenium Capabilities

Selenium is moving away from supporting Selenium::WebDriver::Remote::Capabilities and so is Watir! You can either use a Selenium class browser option object (e.g., Selenium::WebDriver::Chrome::Options), or a Hash that Watir will use to construct that Options class instance for you. Either way, the inputs are more controlled, and it will error if you are requesting something that isn’t supported. (which is how it is supposed to be!)

So, do not use :capabilities argument or Selenium Capabilities classes any longer.

See the Changelog for the complete history of updates.