Learn to Code WatiN: Browser Test your Web Site with WatiN

•

Aligned with another jam session at Ann Arbor's Come Jam With Us is another installment of Learn to Code, this time providing an introduction to WatiN, or Web Application Testing in .NET. The jam session was held at the offices of SRT Solutions in Ann Arbor, Michigan, at 5:30p, Tuesday April 6th. Though thunderstorms were in the forecast, the predicted high was 72°F (22°C), so we weren't bothered by the same 8" of fluffy white snow that caused cancellations and delays during my session on ASP.NET MVC 2. But for those that couldn't make the WatiN jam session, might I recommend the exercise below.

About This Exercise

This coding exercise is designed to give you an introduction to browser-based testing using the WatiN framework, or Web Application Testing in .NET. The framework allows developers to create integration tests (using a unit testing framework like MbUnit, NUnit, or MSTest) to test and assert their application within a browser window. The framework interacts with the browser DOM much like and end-user, producing reliable results that mimic the real world. In this sample, we will write a few WatiN tests against the Google search engine.

Prerequisites

To complete this exercise, you will need to meet or complete a few prerequisites. Please complete these prerequisites before moving on. The session is designed to be completed in about an hour, but setup and prerequisites are not included in that time.

  • An active internet connection. (Our tests will be conducted against live third-party sites.)
  • Install Microsoft Visual Studio 2008 or Microsoft Visual Studio 2010.
  • Download and extract the latest version of the WatiN framework.

Exercise 0: Getting Started

Creating a project

WatiN is generally used within the context of a unit testing framework. For this exercise, we will be using a Visual Studio Test Project and MSTest to wrap our WatiN code.

  1. Create a new "Test Project" in Visual Studio named WatinSample. The language is up to you, but all of the examples in this post will use C#.
  2. Feel free to delete the Authoring Tests document, the Manual Test file, and UnitTest1.cs. We won't be using these.
  3. Add a reference to WatiN.Core.dll from the bin directory of your extracted WatiN download.
  4. Compile.

Exercise 1: My First Browser Tests

In our first test, we will use the project we just created to test Google's home page. After accessing https://www.google.com, we will check a few properties of the browser and a few loaded elements to ensure that the expected page was returned. The first thing we will need is a new Unit Test class to start our testing.

  1. Create a new class (right-click on the WatinSample project and select Add –> Class…), called WhenViewingTheGoogleHomePage.
  2. Mark the class as public.
  3. Add the MSTest [TestClass] attribute to the new class.

  4. Compile.

    1
2
3
4
5
6
7
8
9

    using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace WatinSample
{
  [TestClass]
  public class WhenViewingTheGoogleHomePage
  {
  }
}

Make an Instance of the Browser

Now that we have a test class, we can start writing WatiN code. Each of our tests will first need a Browser object to test against. Using methods attributed with TestInitialize and TestCleanup, we can create a browser instance before the test starts and shut it down when the test is complete.

Creating an instance of a browser in WatiN is easy: simply create a new instance of the IE class, passing in a URL. We can assign this new class to a field of type Browser, which is a base class of all browser classes in WatiN. Currently, WatiN supports Internet Explorer and Firefox.

  1. Create a private field in the test class named browserInstance of type WatiN.Core.Browser. Add a using statement to WatiN.Core if you wish.
  2. Create a test initialization method named WithAnInstanceOfTheBrowser and give it the [TestInitialize] attribute. Within this method, create a new instance of the IE class, passing in the Google URL, https://www.google.com, and assigning the instance to the browserInstance field.

  3. Finally, create a test cleanup method named ShutdownBrowserWhenDone and give it the [TestCleanup] attribute. Within this method, execute the Close() method on our browser instance and assign the field to null to assist with object disposal.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    using Microsoft.VisualStudio.TestTools.UnitTesting;
using WatiN.Core;

namespace WatinSample
{
  [TestClass]
  public class WhenViewingTheGoogleHomePage
  {
    Browser browserInstance;

    [TestInitialize]
    public void WithAnInstanceOfTheBrowser()
    {
      browserInstance = new IE("https://www.google.com");
    }

    [TestCleanup]
    public void ShutdownBrowserWhenDone()
    {
      browserInstance.Close();
    browserInstance = null;
    }
  }
}

Our First Tests: Checking for existing of an element

There are three prominent items on the Google home page: the Google logo, the search criteria text box, and the search button. Using WatiN, we can check for them all. The WatiN Browser object contains an Elements collection, which is a flattened collection of every element in the entire DOM. Like any collection, you can use LINQ and lambda expressions to search for items within this collection. Alternately, you may also use the Element method, which accepts the same lambda expression that would be used within the Where extension method on the collection, and returns the first or default element. For more specific searches, WatiN's Browser object includes similar collections and methods for searching explicitly for Images (<IMG>), Paras (<P>), Text Fields (<INPUT type="text">), and so on.

On each returned Element (or derived Para, Image, or Text Field, etc., all of which inherit from Element), WatiN supplies properties for accessing the CSS Class, Id, InnerHtml, Name, Tag, Text, Value, or many other attributes. The method GetAttributeValue(string attributeName) is provided for accessing other attributes that are not explicitly defined on the object (uncommon attributes and custom attributes). Finally, elements also contain a Style property, which not only gives access to the inline style attribute, but also any CSS properties associated with the element from Internal Style (in the Page Head) or External Style (in an external style sheet).

On to checking for the three elements within the Google home page: the logo, the criteria input, and the search button. First, check for the existence of the Google logo graphic. The image can be found by searching the DOM for an image with an Id of "logo". WatiN works very closely with lambda expressions, so we can use these to help us find out graphic.

  1. Create a new public method named PageShouldContainGoogleLogo.
  2. Add the MSTest [TestMethod] attribute to the method.
  3. Search for and assert on the existence of an Image with the Id of "logo".
  4. Optionally, we can also check that the image has the expected alt attribute; in this case, the value should be "Google".

  5. Compile and run the test. The test should pass.

    1
2
3
4
5
6
7
8

    [TestMethod]
public void PageShouldContainGoogleLogo()
{
  Image googleLogo;
  googleLogo = browserInstance.Image(img =&gt; img.Id == "logo");
  Assert.IsTrue(googleLogo.Exists);
  Assert.AreEqual("Google", googleLogo.Alt);
}

Next, check for the existence of the search criteria input box. WatiN refers to these elements as Text Fields, using the TextField type. Additionally, this form field is identified by its Name rather than its Id. In Google, the name given to the criteria input is "q".

  1. Create a new public method named PageShouldContainSearchCriteriaInput and give it the [TestMethod] attribute.
  2. Search for and assert on the existence of a TextField with the name "q".

  3. Compile and run the test. The test should pass.

    1
2
3
4
5
6
7

    [TestMethod]
public void PageShouldContainSearchCriteriaInput()
{
  TextField criteriaInput;
  criteriaInput = browserInstance.TextField(tf =&gt; tf.Name == "q");
  Assert.IsTrue(criteriaInput.Exists);
}

Finally, check for the existence of the search button using the Button method. In our lambda expression, it is not important to know if the field is identified by a Name property or an Id attribute, as WatiN supplies an IdOrName property to help us find the element. The value to identify the button is "btnG".

  1. Create a new public method named PageShouldContainSearchButton and give it the [TestMethod] attribute.
  2. Search for and assert on the existence of a Button with the Id or Name of "btnG".
  3. Optionally, we can also check the value of the button, which is the text displayed on the button on-screen. This text should be "Google Search".

  4. Compile and run the test. The test should pass.

    1
2
3
4
5
6
7
8

    [TestMethod]
public void PageShouldContainSearchButton()
{
  Button searchButton;
  searchButton = browserInstance.Button(btn =&gt; btn.IdOrName == "btnG");
  Assert.IsTrue(searchButton.Exists);
  Assert.AreEqual("Google Search", searchButton.Value);
}

Working with Style

WatiN can access properties on the DOM beyond just Text values and Alt attributes. WatiN also has full access to the style that CSS has applied to an element. Let's check out a few CSS properties, both those explicitly defined by WatiN and those implicitly accessible through the WatiN framework.

For our first style check, we'll take a look at the default font family used on the Google Home Page. Font Family is one of the explicitly available style properties on a WatiN element. Some others, like Color, Display, and Height are also explicitly defined.

  1. Create a new public test method named BodyShouldUseArialFontFamily.
  2. Assert that the font family assigned to the body matches "arial, sans-serif".

  3. Compile and run the test. The test should pass.

    1
2
3
4
5

    [TestMethod]
public void BodyShouldUseArialFontFamily()
{
  Assert.AreEqual("arial, sans-serif", browserInstance.Body.Style.FontFamily);
}

For our second style check, we will look for an implicit style definition. At the top of the Google Home Page is a series of links to other areas of Google, such as Images, Videos, Maps, and News. At the end of this list is a More link, that when clicked, displays a hidden DIV tag containing even more links, such as Books, Finance, and Google Translate. Since we do not have any code in our test initialization that interacts with the browser, and thus nothing that is clicking the More link, that DIV should still have a hidden visibility. However, since Visibility isn't an explicitly defined style property within WatiN, we need to use the GetAttributeValue method to retrieve the current visibility setting.

  1. Create a new public test method named MoreItemsShouldNotBeVisibleOnPageLoad.
  2. Search for the More Items DIV. It's Id is "gbi".
  3. Using the property lookup method, GetAttributeValue(string attributeName), check that the Visibility is set to "hidden".

  4. Compile and run the test. The test should pass.

    1
2
3
4
5
6

    [TestMethod]
public void MoreItemsShouldNotBeVisibleOnPageLoad()
{
  var googleBarMoreItems = browserInstance.Div(gbi =&gt; gbi.Id == "gbi");
  Assert.AreEqual("hidden", googleBarMoreItems.Style.GetAttributeValue("visibility"));
}

Exercise 2: Interacting with the Browser

Browser Integration tests are more than just loading a page and checking a few element attributes. Our tests may also need to enter values into form fields, click links and buttons, or interact with browser navigation like the back button. WatiN fully supports all of these features in a very intuitive fashion.

A New Test Class: This time with search capability

Create a new test class, similar to what we did in Exercise 1, calling the new test class WhenViewingGoogleSearchResultsForComeJamWithUs. Also add in the TestInitialize and TestCleanup methods that open and close the browser. However, this time, after we load https://www.google.com, enter a value into the search criteria input and then click the Google Search button.

  1. Create a new class named WhenViewingGoogleSearchResultsForComeJamWithUs, similar to what was done in Exercise 1.
  2. Add in the TestInitialize and TestCleanup methods from Exercise 1. Name the Initialize method WithAnInstanceOfTheBrowserSearchingGoogle.
  3. After the code that initializes the IE class, find the search criteria Text Field and set its value to "Come Jam With Us".
  4. After setting the Text Field value, click the Google Search button by calling the Click() method on the Button class.

  5. Compile.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

    using Microsoft.VisualStudio.TestTools.UnitTesting;
using WatiN.Core;

namespace WatinSample
{
  [TestClass]
  public class WhenViewingGoogleSearchResultsForComeJamWithUs
  {
    Browser browserInstance;

    [TestInitialize]
    public void WithAnInstanceOfTheBrowserSearchingGoogle()
    {
      browserInstance = new IE(@"https://www.google.com");
      TextField criteria =
        browserInstance.TextField(tf =&gt; tf.Name == "q");
      criteria.Value = "Come Jam With Us";
      Button search =
        browserInstance.Button(btn =&gt; btn.IdOrName == "btnG");
      search.Click();
    }

    [TestCleanup]
    public void ShutdownBrowserWhenDone()
    {
      browserInstance.Close();
      browserInstance = null;
    }
  }
}

With this code, or initialized test will load the Google Home Page and will conduct a search for "Come Jam With Us".

Validating the Search Results Page

For our first verification, let's check the URL for the browser window. The search result URL should contain the search criteria in the URL's query string; we can validate this using the URL property on our instance of the Browser object.

  1. Create a new public test method named BrowserUrlShouldContainSearchCriteria.
  2. Validate that the current browser URL contains the search criteria information, "q=Come+Jam+With+Us".

  3. Compile and run the test. The test should pass.

    1
2
3
4
5

    [TestMethod]
public void BrowserUrlShouldContainSearchCriteria()
{
  Assert.IsTrue(browserInstance.Url.Contains(@"q=Come+Jam+With+Us"));
}

Finding Child Elements

With WatiN, we are not just limited to searching for items directly from the Browser object. We can also search for child elements directly from their parent element or any ancestor element. Our search results should contain a search result item linking to the Come Jam With Us web site. The Google Results page contains a DIV identified as "res" that serves as a container for all search result information. Rather than checking that our Come Jam With Us link exists somewhere on the page, we should search for it directly within the results DIV.

  1. Create a new public test method named ResultsShouldContainLinkToComeJamWithUs.
  2. From the browser instance, find a DIV identified as "res".
  3. Assert that a link to http://www.comejamwithus.org exists within the "res" DIV.

  4. Compile and run the test. The test should pass.

    1
2
3
4
5
6
7
8
9

    [TestMethod]
public void ResultsShouldContainLinkToComeJamWithUs()
{
  Link comeJamWithUs;
  Div searchResults = browserInstance.Div(div =&gt; div.IdOrName == "res");
  comeJamWithUs =
    searchResults.Link(link =&gt; link.Url == @"http://www.comejamwithus.org/");
  Assert.IsTrue(comeJamWithUs.Exists);
}

Inner Text Versus InnerHtml

An element may contain many child elements. An anchor tag, <A href="#">, can contain text, and child elements may make portions of that text bold, italic, underlined, or even bright red. Through WatiN, we can access that inner content as straight text without the formatting, or as the InnerHtml including all of the child elements.

  1. Create two public test methods, one named ResultsLinkContainsComeJamWithUsText and the other named ResultsLinkContainsComeJamWithUsHtml.
  2. In both methods, search for the results DIV, as we did in the previous test.
  3. In both methods, search through the results DIV for a link with a URL matching http://www.comejamwithus.org.
  4. In the Text method, assert that the text of the link matches "Come Jam with Us (Software Development Study Group)". Note that the value contains no child HTML elements.
  5. In the HTML method, assert that the InnerHtml of the link matches "<EM>Come Jam with us</EM> (Software Development Study Group)". Note that for the same link, we now have the emphasis tags surrounding Come Jam With Us.

  6. Compile and run both tests. The tests should pass.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    [TestMethod]
public void ResultsLinkContainsComeJamWithUsText()
{
  Link comeJamWithUs;
  Div searchResults = browserInstance.Div(div =&gt; div.IdOrName == "res");
  comeJamWithUs =
    searchResults.Link(link =&gt; link.Url == @"http://www.comejamwithus.org/");
  Assert.AreEqual(@"Come Jam with us (Software Development Study Group)",
    comeJamWithUs.Text);
}

[TestMethod]
public void ResultsLinkContainsComeJamWithUsHtml()
{
  Link comeJamWithUs;
  Div searchResults = browserInstance.Div(div =&gt; div.IdOrName == "res");
  comeJamWithUs =
    searchResults.Link(link =&gt; link.Url == @"http://www.comejamwithus.org/");
  Assert.AreEqual(
    @"&lt;EM&gt;Come Jam with us&lt;/EM&gt; (Software Development Study Group)",
    comeJamWithUs.InnerHtml);
}

Back to the Start

As previously mentioned, we can also fully interact with the browser, itself. Our test initialization started from the Google Home Page and performed a search. Using functionality built in to WatiN, we can execute the browser's back navigation to return to the previous page.

For our next test, execute a back navigation and verify that the browser's URL matches https://www.google.com.

  1. Create a public test method named PageShouldHaveComeFromGoogleDotCom.
  2. Execute back navigation in the browser by calling the Back() method on browserInstance.
  3. Validate that the browser URL matches https://www.google.com.

  4. Compile and run the test. The test should pass.

    1
2
3
4
5
6
7
8

    [TestMethod]
public void PageShouldHaveComeFromGoogleDotCom()
{
  string previousUrl;
  browserInstance.Back();
  previousUrl = browserInstance.Url;
  Assert.AreEqual(@"https://www.google.com/", previousUrl);
}

Putting It All Together

Some interactions on a page cause element properties to change. An example of this is the More link from Exercise 1; when the end-user clicks the More link, the More Items DIV appears because the link's click event changes the Visibility style property of the DIV to visible. For our final test, we will use what we have learned to test this functionality.

  1. Create a new public test method named MoreItemsShouldBeVisibleOnMoreLinkClick.
  2. Search for the header bar of Google links, a DIV with an Id of "gbar".
  3. Within "gbar", search for the More Items DIV by an Id or Name of "gbi".
  4. Assert that the Visibility style property has a value of "hidden".
  5. Within "gbar", search for the More link by its class name, "gb3". Note that since a class attribute may contain multiple class definitions, this is accomplished by validating that the class attribute contains the class you are searching for.
  6. Execute a Click event on the link.

  7. Assert that the Visibility style property of the More Items DIV has changed to "visible".

    1
2
3
4
5
6
7
8
9
10
11
12
13

    [TestMethod]
public void MoreItemsShouldBeVisibleOnMoreLinkClick()
{
  var googleBar = browserInstance.Div(gbar =&gt; gbar.Id == "gbar");
  var googleBarMoreItems = googleBar.Div(gbi =&gt; gbi.Id == "gbi");
  Assert.AreEqual("hidden",
    googleBarMoreItems.Style.GetAttributeValue("visibility"));
  var googleBarMoreLink =
    googleBar.Link(link =&gt; link.ClassName.Contains("gb3"));
  googleBarMoreLink.Click();
  Assert.AreEqual("visible",
    googleBarMoreItems.Style.GetAttributeValue("visibility"));
}

That's It

Now that we have spent some time on basic properties, interactions, and style sheets within the WatiN framework, hopefully you can apply this to your own application and get started with your own browser-based integration tests. If you would like more information, I encourage you to check out the WatiN site at https://watin.sourceforge.net. And as always, if you have any questions, drop me a line.