How to Control a Web Browser From Ruby With Watir

Did you know that you can control your web browser with Ruby?

The Watir gem allows you to do this.

And it comes with the full power of modern browsers:

  • You can take a screenshot of the visible area of the page
  • You can run javascript on any page, without having to manually open the developer tools & typing the code in
  • You can find links, click them, and even fill text into input fields

All of this is available to you thanks to Watir & the Selenium project.

Let’s have a look at some code examples!

Launching a Browser

First, create a browser object like this:

require 'watir'

browser =

This will open an empty Chrome window (assuming you have it installed) that you can control now.

For example:


Chrome will navigate to this URL, and the page will load as if you typed the URL yourself.


You can do anything you would normally do on a website with your mouse & keyboard.

Like finding a link & clicking it.

Example: "All Posts").click

How to Find Elements With Watir

You can find elements by their attributes, like:

  • text
  • class
  • id

These elements have methods that match their HTML name, so if you’re looking for H1 tags the method is h1, for paragraphs the method is p & for images the method is either img or images.


browser.h1(text: "Ruby Post Index")

You can also get lists of elements by using the plural of the method name.



This will give you a Watir::AnchorCollection object, which responds to methods like each, map & inject.


How to Deal with Timeouts & Elements That Aren’t Present

It can happen that an element is not present, maybe because the element hasn’t been loaded into the page yet, or the page has changed.

What happens when Watir can’t find an element?

There is a timeout.

It’s 30 second by default, but you can change it:

Watir.default_timeout = 10

When it expires you get a Watir::Exception::UnknownObjectException exception.

But there is another way to handle this!

You can check if the element is present before clicking it or doing any other action.

Here’s how:

link = 'Guides')

if link.present?

How to Take a Screnshot

Once you have an open browser & a page loaded you can take a screenshot of it.

Like this:"/tmp/screen.png")

This saves an image of the current viewport.

Running Scripts

You can run Javascript in the browser to affect the current state of the page, or you can call Javascript functions defined on that page.

Here’s how:

browser.execute_script "alert('bacon')"
# nil

The result?

An alert window with the word “bacon” 🙂

Run code & get the result back:

browser.execute_script "return 1 + 1"
# 2

How to Fill Input Fields

Filling an input field involves two steps:

  1. Find the element
  2. Send keys

Here’s an example:

browser.input(id: "search").send_keys("orange juice")

Now you’ll have to find the submit button & click it.

Helpful Watir Methods & Tips

Watir gives you access to some helpful methods.

For example, get the current URL:


Get a list of open tabs:

Maximize the current window:


Get the HTML & text for the current page:


Also here’s a tip if you want to look for elements with a partial match, you can use a regular expression.

Like this:

browser.p(text: /ruby/)


You’ve learned about Watir in this tutorial, a Ruby gem that allows you to remote control a web browser so you can automate tasks & extract information from pages.

Please share this article if you found it helpful so more people can find it!

Thanks for reading.