Watij is a Java API that provides control and automation of Internet Explorer in order to test web applications. It was created out of the need to have a reliable, easy to use, and robust web application testing tool using Java as the scripting language. But why Java?

With Java at your fingertips you have access to a tremendous amount of existing libraries and tools. This means in your test scripts you are not restricted to testing only web applications. For example with Java you can write a test that calls a web service to do some processing and in the same test bring up your web application using Watij and validate that everything is correct. And if your web application is developed in Java, Watij integrates nicely into your already existing environment.

With Watij you can imitate real user interaction with your web application. Simple user actions like navigating, clicking links, filling out forms, and validating content are a breeze with Watij. Watij also makes it easy to handle more complex actions like file downloading and uploading, popup windows and dialogs, and screen captures.

Finding HTML elements on a page can be a cumbersome task using the traditional DOM. To make this easier Watij includes a powerful element finding capability that allows your scripts to find, access, and control any HTML element on the page. It even supports XPath expressions that are lightning fast.

Watij is a standalone Java API that purposely doesn’t force you into using a proprietary testing framework or IDE. Two of the most popular Java testing frameworks are JUnit and TestNG, and Watij integrates seamlessly with either one. Watij is just like any other Java library, so it’s very is easy to import into your favorite Java IDE like Eclipse or IntelliJ. And even though its main use is in testing web applications, because it is a standalone Java API Watij is not limited to the testing paradigm.

To begin you must create an instance of the IE object, but at this point the actual Internet Explorer browser has not been created.

IE ie = new IE();

It’s not until you call start that the instance of Internet Explorer browser appears

IE ie = new IE()
ie.start(); //starts up Internet Explorer

As a convenience you can also provide the url to navigate to

IE ie = new IE()
ie.start("http://www.google.com"); //starts up Internet Explorer and navigates to www.google.com

Watij allows you connect to and control an instance of Internet Explorer that is already open. You can find an IE browser by url or by title.

Attaching by url:

IE ie = new IE()
ie.attach(url,"http://www.google.com"); //connects to the first open browser with the provided url

Attaching by title:

IE ie = new IE()
ie.attach(title,"Google"); //connects to the first open browser with the provided title

Once you are attacted to the target browser, you can now use your IE object as if you started it up yourself.

Several means of navigating Internet Explorer are available to you at any time:

ie.goTo("http://www.mysite.com"); //navigates IE to www.mysite.com
ie.navigate("http://www.mysite.com"); //also navigates IE to www.mysite.com
ie.forward(); //navigates forward one item in the history list
ie.back(); //navigates back one item in the history list

Watij allows you to position your Internet Explorer instance virtually anywhere on the desktop, toggle visual modes, as well as size the window to your needs.

ie.bringToFront(); //brings the Iternet Explorer window to the foreground, in front of every other window
ie.focus(); //gives the window focus
 
ie.maximize(); //maximizes the window to take up the entire desktop scren
ie.minimize(); //minimizes the window to the desktop taskbar
ie.restore(); //restores the window to its previous positioned state
 
ie.fullScreen(true); //turns the window's full screen mode on
ie.fullScreen(false); //turns the window's screen mode back to normal
 
ie.theatreMode(true); //turns the window's theatre mode on
ie.theatreMode(false); //turns the window's screen mode back to normal
 
ie.visible(false); //hides the window from being seen on the desktop
ie.visible(true); //make the window visible on the desktop
 
ie.left(100); //sets the screen coordinate of the left edge of the window to 100
ie.top(200); //sets the screen coordinate of the top edge of the window to 200

Finding HTML elements on the page is handled through Watij Symbols, Finders, and XPath Expressions.

Watij brought over from Watir (Web Application Testing in Ruby) the concept of using Symbols to specify what to search by. The following code uses the Symbol name to search for a button with the attribute name=”button1”.

ie.button(name,”button1”);

Every HTML element modeled in Watij provides the singular form and the plural form of the object. So the object Button represents a single button, and the object Buttons represents a collection of Buttons.

Using Symbols we can find a collection of all the HTML elements on the page with specific properties.

ie.buttons(name,”deleteButton”); //returns all the HTML buttons on the page with the name=”deleteButton”

You can also access an HTML element in a returned collection by index. Indexes in Watij are zero-based, so the first element is at index 0.

ie.buttons(name,”deleteButton”).get(1);  //returns the 2nd Button in the collection
// OR
ie.buttons(name,”deleteButton”).button(1); //returns the 2nd Button in the collection

You are not limited to the amount of filtering using Symbols, so anything is possible:

Button button = ie.buttons(name,”deleteButton”).buttons(value,”Delete”).button(2); //finds the 3 Button with value=”Delete” and name=”deleteButton”

Watij also provides a generic object named HtmlElement that will allow you to access any other Html element not modeled in the API. For example if you have the following html:

<MYTAG>My Text1</MYTAG>

One way of accessing MYTAG is with the following code:

ie.htmlElement(tag,”MYTAG”);

To better equip you with the ability to access any element on the page in a simple easy to manner, Watij introduced a new concept called Finders. Finders are like Symbols except they are not limited by a single parameter. In fact later on you will see that the sky is the limit when it comes to Finders, especially when creating your own custom ones. For now let’s say you have the following html:

<MYTAG myattr1=”attribute1”>My Text1</MYTAG>
<MYTAG myattr2=”attribute2”>My Text2</MYTAG>

By using the Finder named attribute which takes in a name and value you can do the following:

ie.htmlElement(attribute(“myattr1”,"attribute1")); //returns the HtmlElement with myattr1="attribute1"

The following Finder objects are accessible via:

import static watij.finders.FinderFactory.*;

tag(String tagName)
attribute(String name, String value)
index(int index)
text(String text)
name(String value)
value(String value)
caption(String value)
id(String value)
title(String value)
alt(String value)
src(String value)
action(String value)
method(String value)
url(String value)
href(String value)
xpath(String expression)

Your browser would disply a link to Google as Google. The actual HTML would look something like:

<a href="http://google.com">Google</a>

There are many ways to have Watij click the above link to Google. You can find and click the link using the text or url attribute, which both also accept regular expressions. You can also use xpath to find the link.

ie.link(text,"Google").click();
 
ie.link(text,"/oogl/").click();
 
ie.link(url,"http://google.com").click();
 
ie.link(url,"/google.com/").click();
 
ie.link(xpath, "//A[@url='http://google.com']").click();

See the Watij API for a complete list of methods available for links

Watij sets or clears checkboxes based on the name and value attributes provided in the checkbox HTML tag. The HTML of a check box looks like:

Check Me: <input name="checkme" value="1" type="checkbox">

We can search for this checkbox using our Symbols

ie.checkbox(name,"checkme").set();
 
ie.checkbox(value,"1").set();
 
ie.checkbox(xpath, "//INPUT[@name='checkme' and @value='1']").set();

We can also use the clear method on a checkbox. See the Watij API for a complete list of methods available for checkboxes

Watij sets or clears radios based on the name and value attributes provided in the radio HTML tag. The HTML code of a radio looks like:

Click Me: <input name="clickme" id="1" type="radio">

We can search for this radio using our Symbols

ie.radio(name,"clickme").set();
 
ie.radio(id,"1").set();
 
ie.radio(xpath, "//INPUT[@name='clickme' and @id='1']").set();

We can also use the clear method on a radio. See the Watij API for a complete list of methods available for radios

Watij can submit HTML buttons on a web page based on the name, value (caption) and id attributes. The HTML code of a button looks like:

<input type = "submit" value = "ClickTheButton" name="b1"></input>

We can search for this select box using our Symbols

ie.button(name, "b1").click();
 
ie.button(value,"ClickTheButton").click();

The default way to find a button is through its value. Because of this, there is a simple way to find a button:

ie.button("ClickTheButton").click();

See the Watij API for a complete list of methods available for buttons

Watij selects an item in a select list (or dropdown box) based on the name and option value attributes provided in the select HTML tag. Or we can identify it based on the name and attribute, and the value we want to set. The HTML code of a SelectList looks like:

<select name = "selectme" > <option name="1">O1<option name="2">O2</select>

We can search for this select list using our *Symbols*

//(finds the option in the select list with name 1)
ie.selectList(name, "selectme").option(name,"1").select(); 
 
//(finds the second option in the list)
ie.selectList(name, "selectme").option(index,1).select(); 
 
//(returns whether the select list is disabled)
ie.selectList(name, "selectme").disabled();

You can also clear a select list using the clearSelection() method. See the Watij API for a complete list of methods available for select boxes

Watij clicks images based on the name, id, src, alt and other attributes provided in the image HTML tag. The HTML code of a image looks like:

<img src = images/square.jpg id=square title="square_image">

We can search for this select box using our Symbols

ie.image(src, "/square/").click();
 
ie.image(title, "square_image").hasLoaded();
 
ie.image(id,"square").width();
 
ie.image(xpath, "//IMAGE[@id='square']").click();

See the Watij API for a complete list of methods available for images

Watij sets textfields and textareas based on the name and id and other attributes provided in the HTML tag. The HTML code of a textfield looks like:

<input name="username" type="text">

We can search for this textfield using our Symbols

ie.textField(name, "username").set("myusername");
 
ie.textField(name, "username").value();

See the Watij API for a complete list of methods available for textfields and textareas

Watij supports attaching to child browsers that are created from a parent window. For example, you might have a link that creates a new popup window. This is easily handled in watij:

IE ie = new IE().start("www.mysite.com");
//lets click a link that causes a new window to popup
ie.link(name, "mylink").click();
//now lets get a handle on the child browser;
IE new_ie = ie.childBrowser();

Wasn’t that easy! You can also get the child browser at a specific index away from the parent window. The third child browser would be ie.childBrowser(2). See the Watij API for a complete list of methods available for browsers

Watij supports many methods for validation. You may check to see if an object is disabled, enabled, isSet, readOnly, or any other available element attribute. When writing Watij tests, you extend Junit, so you have the full capability for validation that JUnit and Java have to offer. I would highly suggest looking at the Watij unit tests to get a deeper understanding of the validation capabilities of Watij, JUnit, and Java. The Unit Tests are a great resource - and they all work, too!!

Watij is packaged with a preconfigured version of BeanShell. You can always run Beanshell and just start using Watij to explore an automation idea.