Note: If you are having an issue updating to Watir 6.19, please contact us so we can help!


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: # ==> (uses Chrome) :edge :firefox :internet_explorer :safari

Browser Options

Use the :options parameter

Watir 6.6 tried to make it easier to do everything with Watir::Capabilities, 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.

W3C Capabilities

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:

  • :browser_name
  • :browser_version
  • :platform_name
  • :set_window_rect

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 #goto method, and does not have any effect from navigation based on page interactions (like clicking a link)
    • :none value - does not wait for anything; Because Watir waits for elements before interacting with them, this may speed up your tests without causing additional failures
    • :eager value - waits for the document readiness state to be “interactive”; this is probably the best setting for most Watir users
    • :normal value - 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 :timeouts value 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.
    • :implicit timeout - Watir prevents this setting since it conflicts with Watir’s waiting strategy
    • :script timeout - how long to wait for a script to finish executing (default 30 seconds)
    • :page_load timeout - when using the #goto method 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 #upload
  • :unhandled_prompt_behavior - what the driver should do when it encounters an Alert
    • :dismiss value - Use this if your site has intermittent alerts pop up that your test does not care about and you can’t turn off
    • :accept value - Use this if your site requires accepting alerts for you to run your tests, and your tests do not care about them
    • :ignore value - 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_notify value - 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 (:ignore).
    • :accept_and_notify value - similar to :dismiss_and_notify except 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_opts = {accept_insecure_certs: true,
                page_load_timeout: 100,
                script_timeout: 30},
                page_load_strategy: :eager}
b = :chrome, options: browser_opts

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:

browser_opts = {exclude_switches: ['disable-popup-blocking'],
                args: ['start-fullscreen'],
                detach: true}
b = :chrome, options: browser_opts

Note that you can combine W3C and Browser specific keys in the same Hash:

browser_opts = {accept_insecure_certs: true,
                page_load_timeout: 100,
                script_timeout: 30},
                page_load_strategy: :eager,
                exclude_switches: ['disable-popup-blocking'],
                args: ['start-fullscreen'],
                detach: true}
b = :chrome, options: browser_opts

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 selenoid:options.

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).

browser_opts = {accept_insecure_certs: true,
                page_load_timeout: 100, 
                script_timeout: 30},
                page_load_strategy: :eager,
                exclude_switches: ['disable-popup-blocking'],
                args: ['start-fullscreen'],
                detach: true,
                'sauce:options': {username: ENV['SAUCE_USERNAME'],
                                  access_key: ENV['SAUCE_ACCESS_KEY'],
                                  name: test_name,
                                  build: build_name,
                                  idle_timeout: 60}}
b = :chrome, options: browser_opts, url: ''

Where Code is Sent

Use the :url or :service parameter

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 parameter:

b = :chrome, url: ''

If :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:
chromedriver --help
geckodriver --help
msedgedriver --help
safaridriver --help

An example of setting service arguments with the :service parameter is:

service_opts = {path: '/path/to/drivers/chromedriver', 
                port: '12345', 
                args: ['--verbose', '--log-path=/path/to/logs/chromedriver.log']}
b = :chrome, service: service_opts

How the Code is Sent

Use the :http_client parameter

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: Watir:HttpClient. 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 Watir:HttpClient.

An example of setting service parameters is:

client_opts = {read_timeout: 120,
               open_timeout: 30}
b = :chrome, http_client: client_opts

Bonus Features

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:

b = :chrome, headless: true


b = :firefox, headless: true


  • 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 :headless on 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.

b = :safari, technology_preview: true
  • You will get an error if you set this with any browser other than Safari

Selenium Classes

While we recommend using Hashes and letting Watir convert things for you, you are more than welcome to use Selenium classes directly as necessary:


driver =
b =


options =
b =, options: options)


Note: 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)

capabilities =
b =, options: capabilities)


service =
b =, service: service)


client =
b = http_client: client)

Last Updated: May 05, 2021