Note: If you are having an issue updating to Watir 6.19, please contact us so we can help!
- Browser Defaults
- What the Browser Does
- Where Code is Sent (driver, server, etc)
- How Code is Sent
- Bonus Features
- Selenium Classes
Watir Browser Defaults
The default initialization of
Watir::Browser, without any arguments, uses Chrome on your
local machine with all of the driver default settings.
The most obvious desired customization is by browser, which you can pass in as the first argument:
Watir 6.6 tried to make it easier to do everything with
but ended up making a number of edge cases even more difficult.
Watir 6.19 fixed this by using a more focused API and noting deprecations in preparation for Watir 7.
According to the W3C, there are only 10 top-level capabilities allowed. Some of these are set to ensure you are getting the session you want. Other than browser name, most of these are only useful when using a Selenium Grid or Service. Note that if you specify any of these, the driver must ensure that everything matches or else you’ll get an error:
The remaining capabilities are set to indicate how you want the driver to behave.
:accept_insecure_certs- whether to trust self-signed certificates; defaults to false
:page_load_strategy- what the driver should wait for after a navigation has called Important: this only applies to when you are using the
#gotomethod, and does not have any effect from navigation based on page interactions (like clicking a link)
:nonevalue - does not wait for anything; Because Watir waits for elements before interacting with them, this may speed up your tests without causing additional failures
:eagervalue - waits for the document readiness state to be “interactive”; this is probably the best setting for most Watir users
:normalvalue - this is the default behavior that waits for a document readiness state of “complete’
:proxy- allows user to define a proxy for site traffic to be routed through
:timeouts- Note: as of Watir 7.0.0beta3, users should not set the
:timeoutsvalue directly. Also, the default w3c expected unit is microseconds, but Watir expects seconds and will do the conversion. Please See the example below for how to properly set these values in Watir 7.
:implicittimeout - Watir prevents this setting since it conflicts with Watir’s waiting strategy
:scripttimeout - how long to wait for a script to finish executing (default 30 seconds)
:page_loadtimeout - when using the
#gotomethod how long to wait for a page to finish loading (default 300 seconds)
:strict_file_interactability- defaults to false; set it to true if you are concerned about your file type input fields being visible when using
:unhandled_prompt_behavior- what the driver should do when it encounters an Alert
:dismissvalue - Use this if your site has intermittent alerts pop up that your test does not care about and you can’t turn off
:acceptvalue - Use this if your site requires accepting alerts for you to run your tests, and your tests do not care about them
:ignorevalue - If there is an alert on the page and you send any browser command that isn’t related to the alert, your code will raise an exception. If you rescue the exception, you can continue the test by switching to the alert and handling it as desired before continuing. This is the option that provides the most control to the user and is therefore the default that Watir sets. Note that this is the only setting that allows you to query whether an alert has popped up in a way that doesn’t change the state of the alert
:dismiss_and_notifyvalue - This is the WebDriver default, but Watir overrides it and sets
:ignore. This setting raises the exception just like in
:ignore, but then automatically dismisses the alert. So if you rescue the exception, you don’t then have to switch to the alert to manage it, you can directly continue with your test. This is the worst of either alternate settings above. Either you don’t care about whether there is an alert and should use
dismiss, or you do care about it, and should be able to choose what you to about it (
:accept_and_notifyvalue - similar to
:dismiss_and_notifyexcept that the alerts are accepted instead of dismissed after raising an exception. It is similarly a bad idea.
W3C Capabilities can be set with the
:options key as follows:
Browser Specific Capabilities
In addition to the W3C Capabilities that all browsers support, each browser vendor has their own list of settings that can be adjusted. Check out the details of those specific capabilities in the respective Watir Guides:
An example of using these browser vendor specific capabilities looks like this:
Note that you can combine W3C and Browser specific keys in the same Hash:
Service Provider Capabilities
Service providers have their own capabilities, and they have to use name spaced keywords.
Sauce Labs uses
sauce:options, BrowserStack uses
bstack:options, and Selenoid uses
To add custom service provider capabilities, add a hash of the capabilities inside the provider’s
custom keyword, inside the
:options Hash. Note that since the keyword has a colon, it needs to
have quotes around it. Also note that using a service provider requires specifying their url (more on
that in the next section).
Where Code is Sent
You can execute tests on your local machine, via a Selenium server (either locally or on another machine), or via a service provider (like Sauce Labs or Browser Stack).
To route commands via a server or service provider, simply pass in the location of the
server’s endpoint with the
:url is not specified, Watir assumes you want to execute your tests locally.
It will use Selenium code to determine the
installed driver associated with the chosen Browser, start it up,
and set it to be the recipient of the commands.
To customize how the driver is started, use the
:service parameter with these keywords:
:path- the path of the driver;
:port- the port the driver should start on
:args- the list of command line switches to start the driver with. You can get a list of valid arguments for each driver via the command line with the –help argument:
An example of setting service arguments with the
:service parameter is:
How the Code is Sent
The WebDriver protocol is based on using an HTTP client to send JSON packets to various endpoints.
As of Watir 6.19, we are using our own custom client:
All it is doing differently is adding some header information to
indicate to browser services that Watir is being used and including the version.
If you are using your own HttpClient, consider
subclassing the Watir one, or
[tell us](contact us
what you’d like to see us add.
The settings that can be adjusted for the HTTP Client are:
:read_timeout- the amount of time to wait for data to be received
:open_timeout- the amount of time to wait for a connection to be opened
These both default to 60 seconds in
An example of setting service parameters is:
Watir wants to provide more convenience functionality than Selenium by default. As such, we’re going to provide “special” features that generate the underlying capabilities for common things that people might be interested in. If there are things you want to see here let us know.
Headless mode is supported in Chrome & Firefox. You can turn on headless by sending the following:
- A headless browser isn’t a “full” browser, so not all features may work
- It is unlikely to speed up your tests by much in most cases
- You will get an error if you specify
:headlesson a browser that does not support it
Safari Technology Preview
See the Safari Guide for details on why you would want to use this setting.
- You will get an error if you set this with any browser other than Safari
While we recommend using Hashes and letting Watir convert things for you, you are more than welcome to use Selenium classes directly as necessary:
Capabilities should only be used if you want to specify the exact
JSON for the driver to receive, without any conversions (e.g., keywords are camelCase and
String instances, etc)