Wax, "Watin And eXcel" - User guide

Version 1.0.0.4 of Wax, released 12th October 2007. Copyright © 2007 Edward Wilde, Duarte Consulting

Introduction

There are 4 basic categories of commands:

Many commands are performed against a specific element of the HTML page. Inorder to carry out such a command the method to locate the element must be specified using a find method

Action commands

List of available action commands
Name Arguments Find method Description
AppendText Text to append Required Appends text to a given text input field.
AttachToIE Required Attaches to an exisintg instance of internet explorer that matches the passed in document title
Back Navigates to the previous page in the browser history
BringToFront Brings the current browser window to the foreground.
ClearCache Clears the browser cache, best called before using other commands.
ClearCookies Url (optional) Clears the browser cookies, either for a given url or all cookies.
ClearText Required Clears the value for the text input element specified by the find method
Click Required Triggers the click event for the element specified by the find method
Close Closes the browser
DoubleClick Required Triggers the double click event for the element specified by the find method
Flash Required Causes the selected browser element to flash
Focus Required Sets focus to a given element
Forward Navigates to the next page in the browser history
GetCookie Url, cookie name Gets the cookie for the specified Url and cookie name. Used in combination with the ValidateLastFound command.
Goto Url Navigates to the Url specified in the command arguments
PressTab Presses the tab key moving focus to the next element in the tab order.
Refresh Causes the current browser window to refresh.
Screenshot File name Creates an image of the current web page and saves it to disk.
SelectText Required Selects the text for the identified text input element.
SetCookie Url,cookie data Sets a cookie for the specified domain, The cookie data of the form: <name>=<value>[; <name>=<value>]... [; expires=<date:DAY, DD-MMM-YYYY HH:MM:SS GMT>][; domain=<domain_name>] [; path=<some_path>][; secure][; httponly].
SetValue Value,property name Required Sets the value for the element specified by the find method, using the value given in the command arguments
SetValues Values (comma seperated), property name Required Sets multiple values for the element specified by the find method, using the value given in the command arguments commonly used with a selected list that has the multiple attribute.
TypeText Text to type Required Types text for a given text field.

Examples using the action command

AppendText ^

Example usage:

    Command Id:     CmdAppendText
    Command:        AppendText
    CommandArgs:    Eddie
    FindMethod:     ById
    FindArgs        txtFirstName

Example of the append text command in Excel.

Description

This example will append text to the text field control identified by the id txtFirstName. If element with this id is found or the element is not a text field control, the test will fail.

AttachToIE ^

Example usage:

    Command Id:     CmdAttachToIE1
    Command:        AttachToIE
    CommandArgs:    {not applicable}
    FindMethod:     ByTitle
    FindArgs        Welcome to CodePlex

Example of the AttachToIE command in Excel.

Description

This example will attach to the first instance of Internet Explorer that has the page title "Welcome to CodePlex". If no instance of Internet Explorer is found, with that document title, the test will fail.

Back ^

Example usage:

    Command Id:     CmdGoBack
    Command:        Back
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the back command in Excel.

Description

This example will navigate to the previous page in the browser's history.

BringToFront ^

Example usage:

    Command Id:     CmdBringToFront
    Command:        BringToFront
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the bring to front command in Excel.

Description

This example will cause the current browser window to come to the foreground.

ClearCache ^

Example usage:

    Command Id:     CmdClearCache
    Command:        ClearCache
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the clear cache command in Excel.

Description

This example will clear the browser cache.

ClearCookies ^

Example usage:

    Command Id:     CmdClearCookies
    Command:        ClearCookies
    CommandArgs:    http://www.google.com
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the clear cookies command in Excel.

Description

This example will clear all cookies for the url http://www.google.com.

ClearText ^

Example usage:

    Command Id:     CmdClearText
    Command:        ClearText
    CommandArgs:    {not applicable}
    FindMethod:     ById
    FindArgs        txtFirstName

Example of the clear text command in Excel.

Description

This example look for a browser element with that has the id txtFirstName, it will clear the value for that text input field. The test will fail if an element can not be found for that id, or if the element found is not an text input element.

Click ^

Example usage:

    Command Id:     CmdSubmitLoginForm
    Command:        Click
    CommandArgs:    {not applicable}
    FindMethod:     ById
    FindArgs        btnOkay

Example of the Click command in Excel.

Description

This example look for a browser element with that has the id btnOkay, it will then fire that element's click event. The test will fail if an element can not be found for that id.

Close ^

Example usage:

    Command Id:     CmdCloseBrowser
    Command:        Close
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the close command in Excel.

Description

This example closes the browser the current test is attached to.

DoubleClick ^

Example usage:

    Command Id:     CmdPopUp
    Command:        DoubleClick
    CommandArgs:    {not applicable}
    FindMethod:     ByValue
    FindArgs        Title

Example of the DoubleClick command in Excel.

Description

This example look for a browser element with that has the value Title, it will then fire that element's double click event. The test will fail if an element can not be found for that value.

Flash ^

Example usage:

    Command Id:     CmdFalshElement
    Command:        Flash
    CommandArgs:    {not applicable}
    FindMethod:     ById
    FindArgs        txtLastName

Example of the flash command in Excel.

Description

This example will cause the browser element with the id txtLastName to flash. The test will fail if no element with that id is found.

Focus ^

Example usage:

    Command Id:     CmdFocusElement
    Command:        Focus
    CommandArgs:    {not applicable}
    FindMethod:     ById
    FindArgs        txtLastName

Example of the focus command in Excel.

Description

This example will set focus to the browser element with the id txtLastName to flash. The test will fail if no element with that id is found.

Forward ^

Example usage:

    Command Id:     CmdGoForward
    Command:        Forward
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the forward command in Excel.

Description

This example will navigate to the next page in the browser's history.

GetCookie ^

Example usage:

    Command Id:     CmdGetCookie
    Command:        GetCookie
    CommandArgs:    http://www.google.co.uk,wax
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the get cookie command in Excel.

Description

This example will get the cookie named wax for the domain http://www.google.co.uk.

Goto ^

Example usage:

    Command Id:     CmdGotoStart
    Command:        Goto
    CommandArgs:    http://wwww.google.co.uk
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

CommandArgs: The url to navigate to. If '~' is found in the url it will be replaced with the current directory.

Example of the goto command in Excel.

Description

This example will navigate to http://wwww.google.co.uk.

Note: If there is no attached browser, i.e. AttachToIE or Goto have not been called before in the test, a new browser window will be created prior to navigation

PressTab ^

Example usage:

    Command Id:     CmdPressTab
    Command:        PressTab
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the press tab command in Excel.

Description

This example will press the tab key moving focus to the next element in the tab order.

Refresh ^

Example usage:

    Command Id:     CmdRefresh
    Command:        Refresh
    CommandArgs:    {not applicable}
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the refresh command in Excel.

Description

This example will refresh the current browser window.

Screenshot ^

Example usage:

    Command Id:     CmdScreenshot
    Command:        Screenshot
    CommandArgs:    C:\images\testimage1.png
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the screen shot command in Excel.

Description

This example will create a screen shot of the current web page and save it to disk.

SelectText ^

Example usage:

    Command Id:     CmdSelectText
    Command:        SelectText
    CommandArgs:    {not applicable}
    FindMethod:     ById
    FindArgs        txtFirstName

Example of the select text command in Excel.

Description

This example will select the text for the text input element identified by the id txtFirstName. The test will fail if no element is found for the corresponding id, or if that element is not a text input field.

SetCookie ^

Example usage:

    Command Id:     CmdSetCookie
    Command:        SetCookie
    CommandArgs:    http://www.google.co.uk/,"wax=1234; expires=Wed, 01-Jan-2020 00:00:00 GMT"
    FindMethod:     {not applicable}
    FindArgs        {not applicable}

Example of the set cookie command in Excel.

Description

This example will set the cookie named wax to the value 1234 to expire on 1st Jan 2020 for the domain http://www.google.co.uk. Note the cookie data is enclosed in quotes because it contains a comma.

SetValue ^

Example usage:

    Command Id:     CmdSetFirstName
    Command:        SetValue
    CommandArgs:    Edward,Text
    FindMethod:     ById
    FindArgs        txtFirstName

insert excel image

Example of the SetValue command in Excel.

This example sets the value of the the browser element with the id txtLastName to Edward. The test will fail if no element with that id is found.

SetValues ^

Example usage:

    Command Id:     CmdSetMultiList
    Command:        SetValue
    CommandArgs:    Visa,MasterCard,SelectedItem
    FindMethod:     ById
    FindArgs        optCreditCards

Example of the SetValues command in Excel.

Description

This example finds the select list with the id txtLastName and sets the selected items to Visa and MasterCard. The test will fail if no element with that id is found.

TypeText ^

Example usage:

    Command Id:     CmdTypeText
    Command:        TypeText
    CommandArgs:    Eddie
    FindMethod:     ById
    FindArgs        txtFirstName

Example of the TypeText command in Excel.

Description

This example finds the text box with the id txtTypeText and types in the text Eddie. The test will fail if no element with that id is found.

Assertion commands^

List of available assertion commands
Name Arguments Find method Description
Validate value, property name Required Asserts the value of an element's property is the same as the expected value
Validate using attributes value, attribute:{name} Required Asserts the value of an element's attribute is the same as the expected value
Validate last found value value Required Asserts the value of the last "Get" command (i.e. GetCookie, GetJavaDialogMessage) is the same as the expected value
Validate document contains text value, text Required Asserts the document contains the specified value.
ValidateItems values (comma seperated), property name Required Asserts values for elements that can have multiple values. Commonly used with a selected list that has the multiple attribute.

Examples using the assertion commands

Validate ^

Example usage:

    Command Id:     CmdValidateLinkText
    Command:        Validate
    CommandArgs:    Save document,Text
    FindMethod:     ById
    FindArgs        linkSaveDocument

Example of the Validate command in Excel.

Description

This example will check that the link identified by the id linkSaveDocument has it's text property set to Save document If the link can not be found or the link's text property is not set to this value then the test will fail.

Validate using attributes ^

Example usage:

    Command Id:     CmdValidateAttrubute
    Command:        Validate
    CommandArgs:    mainForm,attribute:class
    FindMethod:     ById
    FindArgs        form1

Example of the Validate command in Excel.

Description

This example will check that the attribute called class is equal to mainForm

Validate document contains text ^

Example usage:

    Command Id:     CmdValidateDocument
    Command:        Validate
    CommandArgs:    WatiN Home,Text
    FindMethod:     UsingDocument
    FindArgs

Example of the Validate command in Excel.

Description

This example will check that the document contains the text UsingDocument. The test will fail if the document doesn't contain this text.
It's also possible to enter values using regular expressions see:http://msdn.microsoft.com/en-us/library/kweb790z(VS.71).aspx for correct syntax.

ValidateLastFound ^

Example usage:

    Command Id:     CmdLastFound
    Command:        ValidateLastFound
    CommandArgs:    wax=1234
    FindMethod:     
    FindArgs

Example of the Validate command in Excel.

Description

This example asserts that the value of the last get command, which retrieves a cookie, is equal to "wax=1234".

ValidateItems ^

Example usage:

    Command Id:     CmdValidateSelectList
    Command:        ValidateItems
    CommandArgs:    1,2,3,SelectedItem
    FindMethod:     ById
    FindArgs        listOptions

Example of the Validate command in Excel.

Description

This example will check that the selected items of a list, identified by the id listOptions are 1, 2 and 3; if otherwise the test will fail.

Dialog commands^

List of available dialog commands
Name Arguments Find method Description
AttachDialogHandler {dialog type},{dialog id} Attaches a specified type of dialog and assigns it a given id
GetJavaDialogMessage {dialog type},{dialog id} Using a previously attached simple SimpleJavaDialog get's its alert message

Dialog Types

Types of dialogs that can be tested
Value Description
SimpleJavaDialog Used to test a javascript alert dialog, used in the and

Examples using the dialog commands

AttachDialogHandler ^

Example usage:

    Command Id:     CmdAttachDlg1
    Command:        AttachDialogHandler
    CommandArgs:    SimpleJavaDialog,dlgSimple
    FindMethod:     
    FindArgs

Example of using the attach dialog handler command.

Description

This will attach a SimpleJavaDialog handler and assign it the id dlgSimple. The id allows subsequent commands to interact and reference this dialog.

GetJavaDialogMessage ^

Example usage:

    Command Id:     CmdAttachDlg2
    Command:        GetJavaDialogMessage
    CommandArgs:    SimpleJavaDialog,dlgSimple
    FindMethod:     
    FindArgs

Example of using the java dialog get message command.

Description

This example shows how to attach a dialog, click a link that will cause the dialog to appear, and then retrieve it's message content and finally assert that it's equal to an expected value.

Find methods^

List of available find methods
Name Arguments Description
ById {Id} Finds an element using the value of it's id.
ByValue {value} Finds an element by it's value
ByLastElement Use the last element found from the previous command executed.
ByUrl Find an element based on the value of it's url
ByNameAndValue {name, value} Find an element based on it's name and value.
UsingDocument Used for validating properties at the document level see: example validate UsingDocument

Examples using the find methods

FindById ^

Example usage:

    Command Id:     CmdFindByTest
    Command:        Click
    CommandArgs:    
    FindMethod:     ById
    FindArgs        link1

Example of using the FindById method to locate an element.

Description

This example will locate an element by it's id. If no matching id is found then the test will fail.

FindByLastElement ^

Example usage:

    Command Id:     CmdFindByLastElement
    Command:        Click
    CommandArgs:    
    FindMethod:     ByLastElement
    FindArgs

Example of using the find by last element method to locate an element.

Description

This example will use the last element found and fire its click event.

FindByUrl ^

Example usage:

    Command Id:     CmdFindByUrl
    Command:        Click
    CommandArgs:    
    FindMethod:     ByUrl
    FindArgs        http://www.google.co.uk

Example of using the find by url method to locate an element.

Description

This example will use the element that has an href of "http://www.google.co.uk" and fire its click event. If no such element is found the test will fail.

FindByValue ^

Example usage:

    Command Id:     CmdFindByValue
    Command:        Click
    CommandArgs:    
    FindMethod:     ByValue
    FindArgs        3

Example of using the FindByValue method to locate an element.

Description

This example will locate an element by it's value. If no matching value is found then the test will fail.

This example would match the following html fragment:
<input type="Radio" name="radio1" value="3">

FindByNameValue ^

Example usage:

    Command Id:     CmdFindByNameValue
    Command:        Click
    CommandArgs:    
    FindMethod:     ByNameValue
    FindArgs        radio1, 3

Example of using the FindByNameAndValue method to locate an element.

Description

This example will locate an element by it's name and value. If no matching element is found then the test will fail.

This example would match the following html fragment:
<input type="Radio" name="radio1" value="3">

Settings command ^

List of available settings
Name Description
AttachToIETimeOut Time to wait whilst trying to attach to an instance of IE.
AutoCloseDialogs Automatically close any dialogs opened during a test

Example usage:

    Command Id:     CmdFindByNameValue
    Command:        Click
    CommandArgs:    
    FindMethod:     ByNameValue
    FindArgs        radio1, 3

Example of using the FindByNameAndValue method to locate an element.

Description

This example will locate an element by it's name and value. If no matching element is found then the test will fail.