An Area Tag in HTML is related to a portion of a Map Tag, usually used in conjunction with selecting a clickable portion of an image. The WatiN Area method and Areas collection exposes the properties of the areas found on the page under test.
An area can be selected by either its ID, its ALT text or as a generic element which can then be cast as an area.
Examples of Usage
The following example uses the Images.html page found in the UnitTests folder provided with the WatiN source code. In this example, Area2 is found by its ALT text property.
''' <summary>
''' Test the properties of Areas by selected by ALT text.
''' </summary>
''' <remarks>
''' Area1Alt is a private const = "WatiN"
''' currentURL is a Private Const = ''' "http://localhost:3587/popup.html"
''' Requires a reference to Microsoft.MSHtml
''' </remarks>
<Test()> _
Public Sub AreaByAltTest()
Using ie As IE = New IE(currentURL)
Dim Area1 As Area
Area1 = ie.Area(Find.ByAlt(New Regex(Area1Alt)))
Assert.AreEqual("Area1", Area1.Id,
"Area1 ID did not match.")
Assert.AreEqual("WatiN", Area1.Alt,
Area1 ALT text did not match.")
Assert.IsTrue(Area1.Url.EndsWith("main.html"),
"Area1 HREF did not match.")
Assert.AreEqual("0,0,110,45", Area1.Coords,
"Area1 Coords were not correct.")
Assert.AreEqual("rect", Area1.Shape.ToLower(),
"Area1 Shape was not correct.")
End Using
End Sub
Some of the properties in the HTML page for this Area object are tested to ensure the area is set correctly. The next example uses the ID to find the correct area to test:
''' <summary> ''' Test the properties of Areas. ''' </summary> ''' <remarks> ''' Area2ID is a private const = "Area2" ''' currentURL is a Private Const = ''' "http://localhost:3587/popup.html" ''' Requires a reference to Microsoft.MSHtml ''' </remarks> <Test()> _ Public Sub AreaByIDTest() Using ie As IE = New IE(currentURL) Dim Area2 As Area Area2 = ie.Area(New Regex(Area2ID)) Assert.AreEqual("Area2", Area2.Id, "Area2 ID did not match.") Assert.AreEqual("Web Application Testing in .Net", Area2.Alt, "Area2 ALT text did not match.") Assert.IsTrue(Area2.Url.EndsWith("main.html"), "Area2 HREF did not match.") Assert.AreEqual("110,0,379,45", Area2.Coords, "Area2 Coords were not correct.") Assert.AreEqual("rect", Area2.Shape.ToLower(), "Area2 Shape was not correct.") End Using
End Sub
Once again, the area is tested to ensure that properties are set as expected.
Contents: Table of Contents Previous Page: WatiN API Reference - AddDialogHandler Next Page: WatiN API Reference - AttachToIE
One of the features that WatiN has that many web browser automation systems do not, is the ability to handle the variety of dialogs that pop up. The AddDialogHandler method is used to assign handlers to the IE instance. These handlers will then snag the dialog, even though it is modal, and either allow you access to the information in the dialog and let you to close it manually when you are done with it, or close it automatically, depending on the handler you chose.
Examples of Usage
The following example will create a handler for a JavaScript Alert box, then test pop the box open and close it.
''' <summary> ''' Ensure that an alert dialog will be handled and ''' closed properly. ''' </summary> ''' <remarks> ''' currentURL is a Private Const = ''' "http://localhost:3587/popup.html" ''' HelloButton is a Private Const = "hello" ''' </remarks> <Test()> _ Public Sub TestAddDialogHandler() Using ie As IE = New IE(currentURL) Dim myHandler As New AlertDialogHandler ie.AddDialogHandler(myHandler) ie.Button(HelloButton).ClickNoWait() myHandler.WaitUntilExists() Assert.IsTrue(myHandler.Message = "hello", "There should be a hello dialog open at this point.") myHandler.OKButton.Click() ie.WaitForComplete() End Using End Sub
The popup.html page is one that is provided with the WatiN source code, which you should have copied into your test project. This test will automate clicking the hello button, which will in turn open a JavaScript Alert box. Once the Alert box is opened, WatiN will have the handler click the OK button.
WatiN is a bit touchy about what you can do while an alert box is showing, as might be expected. Alert boxes are intended by JavaScript to be modal, after all. The assert in the test above works just fine, but the following alert would cause the test to freeze up while WatiN tries to resolve conflicts between the test and the modal alert box:
Assert.IsTrue(ie.DialogWatcher.Count > 0, "There should be a hello dialog open at this point.")
Either assert is actually moot. The fact that the test completes at all indicates that a dialog did open when the “hello” button was clicked, because the myHandler was able to click its OKButton successfully. If no dialog had opened, the system would have crashed because the OKButton would not have existed. The assert does serve the function of checking what the dialog had to say.
An alternative example is shown next using a different dialog handler:
''' <summary> ''' Ensure that an alert dialog will be handled and ''' closed properly. ''' </summary> ''' <remarks> ''' currentURL is a Private Const = ''' "http://localhost:3587/popup.html" ''' HelloButton is a Private Const = "hello" ''' </remarks> <Test()> _ Public Sub TestAddDialogHandler2() Using ie As IE = New IE(currentURL) Dim myHandler As New AlertAndConfirmDialogHandler ie.DialogWatcher.Add(myHandler) ie.Button(HelloButton).Click() Assert.IsTrue(myHandler.Count > 0, "There should be a hello dialog open at this point.") ie.WaitForComplete() End Using End Sub
This example uses the AlertAndConfirmDialogHandler rather than the AlertDialogHandler, which is a more general handler. This handler provides less information about the alert box and is useful basically to determine that an alert did, in fact occur. No access is provided to the contents of the dialog. Notice that the dialog is never actually closed via code in the test. The handler closes the dialog automatically.
This next example uses the ConfirmDialogHandler:
''' <summary>
''' Ensure that an confirm dialog will be handled and
''' closed properly.
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/TestEvents.html"
''' HelloButton is a Private Const = "hello"
''' </remarks>
<Test()> _
Public Sub TestConfirmDialogHandler()
Using ie As IE = New IE(currentURL)
Dim myHandler As New ConfirmDialogHandler
ie.AddDialogHandler(myHandler)
ie.Button(ConfirmButton).ClickNoWait()
myHandler.WaitUntilExists()
Assert.IsTrue(myHandler.Message.Contains("xyz"), "Dialog did not contain message expected.")
myHandler.OKButton.Click()
ie.WaitForComplete()
End Using
End Sub
This example shows the different syntax used by the confirm dialog handler. Note that the button causing the dialog to be displayed is processed with the ClickNoWait. This is required by the dialog handling process. The myHandler.WaitUntilExists ensures that the dialog has time to open before the OK button is clicked. With this handler, the dialog remains open so that it can be examined to ensure it says the correct text, then must be closed manually by clicking either the OK or the Cancel button.
Example four shows how to handle HTML dialog boxes. The key is to use ClickNoWait both to open the dialog and to access any buttons on the dialog as shown in the next section of code:
''' <summary> ''' Ensure that an modal dialog will be handled and ''' closed properly.
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/popup.html"
''' NameTextbox is a Private Const = "name"
''' HelloButton is a Private Const = "hello"
''' ModalPopupButton is a Private Const = "modalid"
''' </remarks> <Test()> _ Public Sub TestAddDialogHandler4()
Using ie As IE = New IE(currentURL)
Dim myHandler As New AlertAndConfirmDialogHandler
Dim myModalHandler As HtmlDialog
ie.AddDialogHandler(myHandler)
'The button that opens the HTML dialog must be clicked with NO WAIT
ie.Button(ModalPopupButton).ClickNoWait()
myModalHandler = ie.HtmlDialog(Find.ByTitle("PopUpTest"))
myModalHandler.TextField(NameTextbox).Value = "Test"
Assert.IsTrue(myModalHandler.TextField(NameTextbox).Value = "Test", "Did not set value of textbox.")
'The button on the HTML dialog must be clicked with NO WAIT
myModalHandler.Button(New Regex(HelloButton)).ClickNoWait()
Assert.IsTrue(ie.DialogWatcher.Count > 0, "There should be a hello dialog open at this point.")
myModalHandler.Close()
End Using
End Sub
This test is an extension of the third test because the modal dialog that gets opened is the same screen (popup.html).
You will notice that you have complete access to the controls on the modal dialog, just as though it were a normal page. In this test, I set the value of the text box and click the button to show an alert box before closing the dialog.
Contents: Table of Contents Previous Page: WatiN API Reference - ActiveElement Next Page: WatiN API Reference - Area
WatiN contains classes and methods to assist in automating activities within Internet Explorer and Firefox. Each of the methods available will be discussed along with examples of usage in the sections that follow:
Examples of how to use each command available to the IE instance will be provided. All examples will use either the simple default.aspx page created earlier or one of the html pages distributed with WatiN. Each command will be provided with at least one test which can be run as is. You should copy all of the html files that are in the \src\UnitTests\html folder inside of the folder in which WatiN was installed into your test solution using the following procedure if you wish to run these tests:
- Copy the entire contents of the WatiN\src\UnitTests\html\ folder including any sub-folders into the folder where your solution resides. Make note of the new folders that will be needed.
- Right click on the WatiNTest project where you placed the default.aspx page and choose Add – New Folder and add a folder for each of the folders noted previously.
- Right click on each of the new folders and choose Add – Existing Item.
- Browse to the respective folder under your solution and add all of the items therein.
- Right click on the WatiNTest project where you placed the default.aspx page and choose Add – Existing Item.
- Browse to the folder where you solution is located and CTRL-click on each html file, then click on the Add button.
ActiveElement
Each web page can have one and only one element with the focus at any one time. It is possible when a page has first been opened that there may be no active element (but the page itself). ActiveElement may be used to assign the element with the focus to a variable or to issue actions against the element.
Assignment
You can assign the active element with a command like the one that follows:
''' <summary>
''' Ensure that the textbox displays what is set to ActiveElement
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/Default.aspx"
''' MessageTextBox is a Private Const = "MessageTextBox"
''' </remarks>
<Test()> _
Public Sub TestActiveElementAssignment()
Using ie As IE = New IE(currentURL)
ie.TextField(Find.ById(New Regex(MessageTextBox))).Value =
ie.ActiveElement.Id
End Using
End Sub
This simple example opens the default web page created previously and displays the ID of the active element in the message textbox. Since no control will have focus, the message textbox should be blank.
Next is a more verbose test which uses the text box on the default.aspx to hold information about the active element and checks to see if it is information about the correct control.
''' <summary>
''' Ensure that the OK button is set to ActiveElement
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/Default.aspx"
''' OKButton is a Private Const = "OKButton"
''' MessageTextBox is a Private Const = "MessageTextBox"
''' </remarks>
<Test()> _
Public Sub TestActiveElementAssignment()
Dim aStringValue As String = ""
Using ie As IE = New IE(currentURL)
'Set the focus on the OKButton
ie.Button(Find.ById(New Regex(OKButton))).Focus()
ie.TextField(Find.ById(New Regex(MessageTextBox))).Value =
ie.ActiveElement.Id
aStringValue = _
ie.TextField(Find.ById(New Regex(MessageTextBox))).Text.Trim
Assert.IsTrue(aStringValue.Equals(OKButton),
"The ID of the OKButton should be in the textbox now.")
End Using
End Sub
Example of Usage
Once you have an active element, you can use the methods exposed by it. Each type of element will have its own set of available methods, of course. The following example shows setting a Button to the active element as was done in the last test. This time, the test will exercise the click event on the button:
''' <summary>
''' Ensure that the OK button is set to ActiveElement
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/Default.aspx"
''' OKButton is a Private Const = "OKButton"
''' MessageTextBox is a Private Const = "MessageTextBox"
''' </remarks>
<Test()> _
Public Sub TestActiveElementClick()
Dim aStringValue As String = ""
Using ie As IE = New IE(currentURL)
'Set the focus on the OKButton
ie.Button(Find.ById(New Regex(OKButton))).Focus()
ie.ActiveElement.Click()
aStringValue = ie.TextField(Find.ById(
New Regex(MessageTextBox))).Text.Trim
Assert.IsTrue(aStringValue.Equals("OK"),
"The ID of the OKButton should be in the textbox now.")
End Using
End Sub
The command ie.ActiveElement.Click() works because the active element happens to be a button with a click event. Generally, you will find it more stable to find buttons that you wish to click specifically, rather than relying on ActiveElement.
The ActiveElement method comes in most handy, when you need to determine what has the focus when you have not already set something yourself, such as on page load. There may be a requirement that a specific input field or button have focus when the page loads and you can check for it with ActiveElement. The following example shows a test to determine if the message textbox has the initial focus:
''' <summary>
''' Ensure that the MessageTextBox is set to ActiveElement
''' </summary>
''' <remarks>
''' currentURL is a Private Const =
''' "http://localhost:3587/Default.aspx"
''' MessageTextBox is a Private Const = "MessageTextBox"
''' </remarks>
<Test()> _
Public Sub TestActiveElementInitialFocus()
Dim aStringValue As String = ""
Using ie As IE = New IE(currentURL)
If Not ie.ActiveElement.Id Is Nothing Then
aStringValue = ie.ActiveElement.Id.ToString
End If
Assert.IsTrue(aStringValue.Contains(MessageTextBox),
"The initial focus should have been the textbox but instead
was [" & aStringValue & "].")
End Using
End Sub
Contents:
Table of Contents Previous Page:
Testing Web Pages - Things To Consider Next Page:
WatiN API Reference - AddDialogHandler