This repository has been archived by the owner. It is now read-only.


Justin Ko edited this page Jul 10, 2013 · 4 revisions


"Watir" (pronounced water) stands for "Web Application Testing in Ruby". Watir is an automated test tool which uses the Ruby scripting language to drive the Internet Explorer web browser. Watir is a toolkit for automated tests to be developed and run against a web browser.

What Does Watir Work With?

Watir will drive web applications that are served up as HTML pages in a web browser. Watir will not work with ActiveX plugin components, Java Applets, Macromedia Flash, or other plugin applications. To determine whether Watir can be used to automate a part of a web application, right click on the object and see if the View Source menu option is available. If you can view the HTML source, that object can be automated using Watir.


To use the tool, you should have a basic understanding of:

  • HTML: This is a basic HTML tutorial.
  • Programming: You should understand programming basics, including variables and simple control structures like "for" loops and "if" statements.
  • Ruby: You do not need to know how to program in Ruby to get started with Watir, but you should learn some Ruby if you really want to get the most out of Watir. Check out the Cheat Sheet for Ruby for basic Ruby information.
  • Most browsers have a toolbar that can be useful in navigating the DOM for pages that you're looking to automate - see the Browser Development Toolbar page.


Watir runs on Windows machines and works with the Internet Explorer web browser, versions 6 and 7. We recommend using Ruby 1.8.5-24 or Ruby 1.8.6-26 final (or later). Watir runs on Windows 2000, XP, Server 2003 and Vista. Make sure you are logged in as Administrator while installing Ruby and Watir.

Developing Test Cases

See Developing Test Cases

Interacting With a Web Page

You will notice we've chosen to name the variable name ie used in Watir test scripts for the Internet Explorer browser. You could call it whatever you wish, but we use ie for ease of use. This variable tells the Watir library to exercise test scripts against an instance of the Internet Explorer web browser.

In Ruby, think of programming in terms of objects and messages. Watir was also developed with objects and messages in mind. If you think of the ie variable as an object, you can send messages to it. Think of objects as nouns. When you start up Internet Explorer, the operating system starts the program which creates an instance of the Internet Explorer web browser. You refer to this Internet Explorer browser instance as a thing. If you send a message to that object, it will respond to that message if it recognizes it.

Think of the messages as verbs. In Ruby, you send a message to an object by separating the object you are calling from the message you are sending to it with a dot. For example:


would tell the object dog that it must bark.

This isn't very specific though. What dog should bark? In the Watir world, you could identify the test area to be our yard. Like ie, treat it as an object with attributes containing other objects with attributes. For example, in our yard, there are two dogs: Heidi and Megabyte. Each of these dog objects have attributes that identify them. They have names, breeds, shapes and sizes and colors. To be more specific, and interacting with them the Watir way, you could send the message bark to the dog Heidi like this:, "Heidi").bark

This says in Watir syntax: in the yard, identify the dog Heidi by her name attribute, and send her the bark message. The expected outcome would be Heidi responding to the message by barking.

When you develop test scripts with Watir, you interact with objects on a web page by sending them messages. Like the yard example, the Internet Explorer browser itself contains objects. You can access these objects within an Internet Explorer browser instance by identifying them by different attributes. Just like in the dog example, above, you must be very specific when you send messages to objects on a web page. You must also be able to identify objects on a web page by using a variety of different attributes due to the diversity in how tags are declared by different application developers. With Watir, identify objects and send them messages by using the dot notation. For example:


narrows down the type of object to send a message to.

ie.button(:value, "Click Me").click

identifies the object on the page as a button within the instance of Internet Explorer (ie) that has the value attribute (caption) Click Me. When you send the message (the verb) click, Watir interprets and tells Internet Explorer to click.

Watir Syntax

The Watir syntax is shown later with three views. One is the view that we see objects on a web page while viewing them in a web browser. The next view is an example of the Watir code that would be needed to automate an action using that web page object. The third view is the object on the web page shown in its HTML form. This is the way it looks when we view the source of a web page, or open the file in a text editor.

Require the Watir Tool

To use the Watir tool, first enter the following in your test script:

require 'watir'

This allows our test script to use the Watir tool.

Create a Test Instance of Internet Explorer

To create a test instance of Internet Explorer, enter the following in your test script:

ie =

Watir sends a message to Internet Explorer, telling to create a new instance of itself, and assigns that instance to ie.

To create an instance of Internet Explorer and navigate to the site with one statement:

ie = Watir::IE.start("http://mytestsite")

Watir uses the start method to both create a browser instance and navigate to a site.

Site Navigation

To direct your test script to the web application you are testing, enter the URL in this command:


In the example above, enter in your application's URL in place of mytestsite.

Watir sends the goto message to Internet Explorer, telling it to enter the address you entered as a method argument in the Address bar, and to direct the browser to that site.

Page Elements

See Page Elements

Finding Page Elements

See Finding Page Elements

Running Tests


You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.