Watir Project

Watir 7.3

2023-08-04T00:00:00+00:00

Watir 7.3 is now available on RubyGems. Two small features and some maintenance.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 7.3"

New Features

Two small feature additions for this release:

DateField and DateTimeField can be set with anything responding to #strftime instead of specific objects.
Cookies can set values for http_only and same_site

Watir and Selenium

Selenium has been churning out releases and making changes over the past year, mostly removing code that Watir doesn’t use, and requiring users to change things to what Watir is already doing. Watir continues to be an effective way to leverage the browser automation power of Selenium with the opinions and synchronization required to more easily maintain your test suites.

Technically, Watir 7.3 only requires Selenium 4.2 or greater (necessary for the new scrolling features), but it is highly recommended that you upgrade to the latest version of Selenium. Selenium 4.11 natively manages drivers better than the webdrivers gem, with more features coming, so you can stop requiring webdrivers and just let Selenium handle it. To keep up with the latest changes in Selenium that are available to Watir users, pay attention to the Selenium blog

Watir and BiDi

The primary functionality in Selenium that Watir has been ignoring so far is related to BiDirectional / Chrome DevTools Protocol features. The CDP implementation in Selenium is a temporary placeholder while the w3c browser tools working group completes the specification for WebDriver BiDi. Watir users can access the current features at any time by referencing the Selenium code and using the Selenium driver which can be obtained by: driver = browser.wd.

BiDi is the future of browser automation, and the Watir team is keeping a close eye on the state of the technology, and will figure out how best to support these features within the Watir API when they become standardized and as future versions of Selenium (think Selenium 5.0 and 6.0) make more use of them.

See the Changelog for the complete history of updates.

Watir 7.2

2022-12-24T00:00:00+00:00

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.

Watir 7.1

2021-11-15T00:00:00+00:00

Watir 7.1.0 is now available on RubyGems. This release re-works a few things related to scrolling.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 7.1"

New Method: `Element#in_viewport?`

This method attempts to determine whether the top of the element is positioned on the page within the browser viewport. It is of limited value for most testing purposes, but it is necessary to support other methods, and there wasn’t a good reason not to make it a public method.

Change to: `Element#obscured?`

This method attempts to determine if clicking an element will result in a click intercepted error before trying to actually click on the method. Previous behavior was to always scroll the element to the top of the page. For this release the element will only be scrolled if it is determined not to already be in the viewport, and if it is not, it will be scrolled to the bottom of the page to match the correct behavior for clicking an element according to the WebDriver specification.

Automatic Element Scrolling

Per the WebDriver specification, mouse movements when executing action chains are not supposed to scroll the page. If an element is outside the page, it is supposed to raise a “move target out of bounds” error. For most methods that use the actions chains (#double_click, #right_click, #hover, #drag_and_drop_on, and #drag_and_drop_by), Watir has been scrolling the element to the center of the viewport before executing the actions. In this release, we’ve added a :scroll_to parameter that allows you to automatically scroll to :top or :bottom instead of :center. Further, if you do not want Watir to scroll at all, you can pass in nil as the argument.

In addition to the above-mentioned methods, #click also uses action chains when provided modifiers (e.g., :shift, :alt, :control, :command, etc.), but has not been getting automatically scrolled. As of this release this method will also automatically scroll.

See the Changelog for the complete history of updates.

Watir 7.0 Released!

2021-10-18T00:00:00+00:00

Watir 7.0.0 is now available on RubyGems. It requires Ruby 2.6+ and Selenium 4.0 which was just released last week. It’s been a long road since Watir 6.0 was released almost 5 years ago. That version was a substantial reenvisiong of Watir’s default approach to automation, especially as it relates to Selenium. It was designed to combine the original philosophy of Watir with the power of Selenium. Watir 7 is mostly just a much more stable and performant implementation of that vision. As of this release, there are no outstanding Pull Requests or reported bugs in our Issue Tracker!

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 7.0"

New Windows Commands

Since Watir 7.0.0.beta5 2 new commands were implemented for Windows: Window#minimize and Window#full_screen. They both do about what you would expect, but be careful as there is no easy way to restore the browser to the previous state.

If you need to restore your window to previous size and position, you might need code like:

original_size = @browser.window.size
original_position = @browser.window.position
@browser.window.maximize
@browser.window.resize_to(*original_size)
@browser.window.resize_to(*original_size)

Changes from 6.19

A quick recap of the work that was done in the beta releases:

Watir 7.0.0.beta1: This removed all the deprecations and provided a clean slate for udpates

Watir 7.0.0.beta2: This added the features we couldn’t use with the deprecated code and/or without Selenium 4.

Watir 7.0.0.beta3: This was just bug fixes and some changes in defaults.

See the Changelog for the complete history of updates.

Watir 7.0 Beta 3

2021-05-05T00:00:00+00:00

Watir 7.0.0.beta3 is now available on RubyGems. This update includes bug fixes and things that were intended for the last release for Capabilities but overlooked.

To install:

gem install watir --pre

or in your Gemfile:

gem "watir", ">= 7.0.0.beta3"

Unhandled Prompt Behavior

We documented in the capabilities guide the reason for why Watir is going to override the default behavior for Alert Handling. Except we forgot to implement it. It’s non-backward compatible, but we’re in beta. You must send a command to accept or dismiss the Alert if you are rescuing the exception. This will allow users to query whether an alert is present without changing the state of the system.

Driver Timeouts

The Selenium::WebDriver::Timeouts class has always converted script timeout, page load timeout, and implicit wait timeouts from seconds (what the user enters) to milliseconds (what w3c spec expects). When support for setting timeout values was added to the capabilities, it did not convert from seconds to milliseconds. Watir now handles timeouts set in capabilities in a special way.

This is now deprecated:

opts = {timeouts: {page_load: 11000, script: 12000}}
browser = Watir::Browser.new(options: opts)

Instead do this:

opts = {page_load_timeout: 11, script_timeout: 12}}
browser = Watir::Browser.new(options: opts)

Note that Watir will now raise an exception if attempting to set an implicit wait because that conflicts with Watir’s automatic synchronization.

Vendor Capabilities

Watir was not properly handling valid vendor extension capabilities like sauce:options and selenoid:options. This has been fixed.

See the Changelog for the complete history of updates.

Watir 7.0 Beta 2

2021-03-26T00:00:00+00:00

Watir 7.0.0.beta2 is now available on RubyGems. This is all the additions and optimizations that were dependent on removing the deprecated code in Beta 1. Watir Repo now has zero outstanding bugs! The Issues list contains 2 optimizations and 2 feature requests which we may or may not get to before Watir 7.0 is released. Expect production release of Watir 7.0 as soon as Selenium 4.0 is released.

To install:

gem install watir --pre

or in your Gemfile:

gem "watir", ">= 7.0.0.beta2"

Setting Values on a Page

One of the coolest features implemented by Page Object gems is the ability to use Watir to automatically fill out a form based on Element type. This is an example of what it looks like with Watir 6
in WatirDrops:

  case watir_element
  when Watir::Radio
    watir_element.set if val
  when Watir::CheckBox
    val ? watir_element.set : watir_element.clear
  when Watir::Select
    watir_element.select val
  when Watir::Button
    watir_element.click
  when Watir::TextField, Watir::TextArea
    watir_element.set val if val
  else
    watir_element.click if val
  end

Some take true or false, some take String or Regexp or even Array.

It makes more sense for Watir to create a standard interface for this interaction than to require Page Object gems to implement it. The #set method was originally intended for this role, but determining how the arguments would be used was never fully implemented.

This release simplifies all of that by baking it into #set. The above code can now be implemented with:

  watir_element.set val

Even more interesting, there is a generic Element#set method. You don’t even have to specify the element subclass any more. If you have a generic Watir::Element that matches <input type="checkbox" id="checky" />, calling #set on it with true value, will now automatically determine that it is actually a CheckBox element and will ensure that it is selected (based on the true input). Obviously, it is better and more efficient for the user to set it, but it is no longer required.

More Select Lists

Watir 6 had two methods for selecting options. Select#select would select options based on text or label and Select#select_value would select options based on value. The code was also a little messy because we assumed everything might be a multiple select list, which impacted performance a bit.

The first fix was to combine selecting by text, label and value into the #select method. This allows us to have the single common interface aliased to #set (as described in previous section), and the likelihood of the value of one option matching the text of another option is relatively small, but more on this below.

To deal with multiple select lists, we first decided to have people use the short-lived Select#select_all method. Except this moved us away from the single common interface for all inputs that we want. Independently, we decided to support passing in an Array instance to #select as a way to indicate that multiple values should be selected, and it just made sense to remove #select_all in favor of toggling multiple select list behavior based on whether the argument received is an Array. So if you have a multiple select list and want to match multiple options with one command, put it in an Array.

browser.goto 'watir.com/examples/simple_form.html'

country_dropdown = browser.select(id: 'languages')
country_dropdown.select [/an/] # An Array, so only first matching selected
country_dropdown.selected?('1') # => true
country_dropdown.selected?('3') # => true

If there is an issue with the value being passed in matching on a value or a text item that you did not intend, you can now be explicit about what gets matched.

browser.goto 'watir.com/examples/simple_form.html'

country_dropdown = browser.select(id: 'country')
country_dropdown.select(text: 'Denmark')
country_dropdown.selected?('1') # => true
country_dropdown.select(value: '2')
country_dropdown.selected?('Norway') # => true
country_dropdown.select(label: 'Sverige')
country_dropdown.selected?('Sweden') # => true

Finally, we added the ability to check if an option is selected in the same manner that we are selecting it, so now :value is supported in addition to :text and :label

For everything about working with Select Lists, read our Dropdown Elements Guide

Selenium Support Classes

Alex implemented two non-automation-specific features for Selenium (Logger and Guards) that are being used by Watir. Maybe these will eventually be put into their own gems.

In Watir 6.6 we pretty much just copy/pasted the Logger implementation from Selenium and then added things to it. The Selenium Logger was updated in v4 to include all of the Watir functionality, and allows other projects to extend it.

WatirSpec::Guards has been a part of the WatirSpec project from the beginning (when Jari created them in 2009), and was based on code in rubyspec. They are very powerful and allow executing or not executing pretty much any block of code in the specs. Unfortunately, it was extremely challenging to keep the watirspecs updated as bugs were fixed and w3c capabilities were implemented by different browsers. Selenium Guards are tied into RSpec metadata. Rather than running or not running blocks of code, each spec has a single set of guards. The killer feature is that guarded code will execute as pending, so if the bug has been fixed the test will fail and we can update everything accordingly.

See the Changelog for the complete history of updates.

Watir 7.0 Beta 1

2021-03-18T00:00:00+00:00

Watir 7.0.0.beta1 is now available on RubyGems. Watir 7 is coming! Since Watir 7.0 will require Selenium 4.0, this beta release requires at least Selenium 4 beta 2. In spite of being pre-release versions, we recommend using these beta releases over the latest production releases of Watir 6 and Selenium 3.

A lot of deprecated code was removed, so please run your tests with Watir 6.19.1 and make sure you don’t have any deprecation warnings before trying this beta. Please let us know if anything is not working the way you expect it to.

To install:

gem install watir --pre

or in your Gemfile:

gem "watir", ">= 7.0.0.beta1"

Updated Support

Requires Selenium 4 beta 2 (or higher)
Officially supports Ruby 3
Officially supports Chromium based Microsoft Edge

Removes All Deprecated Code

When we upgraded watir-webdriver to Watir 6.0 back in 2016, we marked a few features as deprecated right at the beginning, but never removed the functionality. In the past 4+ years we’ve added literally dozens of deprecations as we identified code that we wanted to simplify and improve. This release finally removes all of it and encourages the behavior that is optimal for performance and future maintenance.

See the Changelog for the complete history of updates.

Watir 6.19

2021-03-12T00:00:00+00:00

Watir 6.19 is now available on RubyGems. Unless there are any bugs found, this will be the last 6.x release. Watir 7.0 will be based on Selenium 4.0, so expect some beta versions of Watir 7, so long as Selenium remains in beta status. That said, Selenium 4 beta is extremely stable and is highly encouraged at this point. This release fixes numerous limitations and bugs in staring a Watir Browser, and deprecates a number of things to prepare for Watir 7’s and Selenium 4’s way of starting the Browser/Driver.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.19"

Fixes Capabilities

Selenium has changed the way it handles capabilities quite a bit since Watir 6.6 was released. Additionally, there were a number of configurations that the Watir code never properly handled. This release fixes all of that, and sets us up for long term success with Selenium 4 going forward.

We’ve created a whole Capabilities Guide to explain what can and can’t be done now.

Watir HTTP Client

Of minor note, Watir defaults to its own HTTP Client now. It’s essentially the same default client except it adds Watir version info into the http header.

See the Changelog for the complete history of updates.

Watir 6.18

2021-02-26T00:00:00+00:00

Watir 6.18 is now available on RubyGems. As (one of?) the last 6.x release before Watir 7, this release adds some deprecations necessary for us to add the improvements we want for Watir 7. Most changes are for browser windows, with some updates to select lists and element collections.

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.18"

Browser Windows

The biggest deprecation is :index as a window locator, and the use of indexing (#[], #first, #last) on window collections. You can read the explanation here.

Because the vast majority of the time, there is only one other window you need to work with, there is now a Browser#switch_window method. It can only be used if there are 2 windows, and all it does is switch to the other window. This should be sufficient for the vast majority of users:

browser.switch_window
browser.button(id: 'close').click
browser.switch_window

Still, it’s only fair to add a locator since one is being taken away. Introducing the new :element locator which allows you to select a window based on a unique element on the page:

browser.window(element: browser.div(id: 'my-element'))

Also, to make sure people don’t continue to use indexing with an Array of Window instances, Browser#windows now returns a new WindowCollection object with the deprecation notices. This object will let us do some interesting things in the future, but right off it’s hooked up to use Watir’s powerful waiting functionality, so you can do things like:

browser.link(id: 'open-third-window').click
browser.windows.wait_until(size: 3)

Waiting for Multiple Elements

Many users do a lot of work with collections of elements instead of specific elements, which means that many of Watir’s best synchronization functionality has not been available to them. Similar to what we did with WindowCollection, we’ve hooked up ElementCollection to use Watir’s waiting features. You can now do things like:

browser.elements(divs: /foo/).wait_until(size: 3)
browser.elements(divs: /foo/).wait_until(&:exists?)
browser.elements(divs: /foo/).wait_while(&:empty?)

To accomplish this, Watir will now relocate the collection whenever an enumerable method is used. It shouldn’t be an issue for you unless you are doing a lot of size calls on the same collection. Indexing and iterating with ElementCollection#to_a won’t be affected.

So Long Select All

There is a lot of overhead to treating a select list like it might be a multiple select list, especially when multiple select lists are not very common. Way back in Watir 6.6 I had this brilliant idea for optimizing Select Lists. If we use Select#select for non-multiple select lists and Select#select_all for multiple select lists, it makes it really easy to only do the performance expensive things when needed.

Except… It turns out that we couldn’t easily completely stop using #select for multiple select lists, and there are some advantages for automatic form filling implementations to have everything necessary go through one method. So, Select#select_all and Select#select_all! are now deprecated, and I apologize for making people move to them only to ask them to move back away from them.

If you are working with a multiple select list and you want to select multiple things, you now need to pass in what you want to be selected as an Array, even if it is just one thing (like a Regexp instance):

browser.select_list(id: 'languages').select([/ish/])
browser.select_list(id: 'languages').select([/ish/, 'Latin'])
browser.select_list(id: 'languages').select(['English', 'Swedish'])

See the Changelog for the complete history of updates.

Watir 6.17

2020-08-28T00:00:00+00:00

I know it has been a long time without a release, but Watir 6.17 is now available on RubyGems! Mostly just a maintenance update, but Ruby 2.5 or greater now required and all of the warnings and noise from recent Selenium versions should be silenced. Mostly I’m pleased that in addition to code from the 3 main contributors, we received code submissions from four additional authors: Lakshya Kapoor, Matthew Mazaika, Olle Jonsson & Joe Schulte. Thank you for your work!

To install:

gem install watir

or in your Gemfile:

gem "watir", "~> 6.17"

Convenience Methods

Element#right_click now accepts modifiers for key presses just like Element#click
FileField#upload exists was added (same functionality as FileField#set)
Logger#selenium= allows setting selenium log level directly
Browser now accepts a :service parameter with a Selenium Service instance value

Deprecations and Removals

Element#scroll_into_view is deprecated in favor of the new Element#scroll functionality
Selenium noise from latest version is quieted

Bug Fixes

Locator code now respects case sensitivity and insensitivity based on w3c html specification
Each browser instance gets its own timer to allow threading
There was a location issue when an iframe was nested under another element
Locating with Regular Expressions used to only match direct child text nodes, now it matches any descendent

See the Changelog for the complete history of updates.

Watir Project

Watir 7.3

New Features

Watir and Selenium

Watir and BiDi

Watir 7.2

Shadow DOM

Advanced Scrolling

Capabilities Fixes

Deprecating Selenium Capabilities

Watir 7.1

New Method: Element#in_viewport?

Change to: Element#obscured?

Automatic Element Scrolling

Watir 7.0 Released!

New Windows Commands

Changes from 6.19

Watir 7.0 Beta 3

Unhandled Prompt Behavior

Driver Timeouts

Vendor Capabilities

Watir 7.0 Beta 2

Setting Values on a Page

More Select Lists

Selenium Support Classes

Watir 7.0 Beta 1

Updated Support

Removes All Deprecated Code

Watir 6.19

Fixes Capabilities

Watir HTTP Client

Watir 6.18

Browser Windows

Waiting for Multiple Elements

So Long Select All

Watir 6.17

Convenience Methods

Deprecations and Removals

Bug Fixes

New Method: `Element#in_viewport?`

Change to: `Element#obscured?`