Nadim's Blog: WHITE : How to test Windows desktop application using WHITE UI automation framework and Visual Studio Unit test

Automating desktop application is challenging now a days due to unavailability of suitable open source tool as lots of commercial tools in the market with high cost. Due to the revolution of desktop application and implementing WPF or Silverlight in place of basic WinForms, UI is becoming more dynamics and colorful and different UI objects are coming for business purpose. Also more commercial user controls are evolving and increasing more competition with Web UI, desktop application automation are now more complex and it is hard to search the appropriate UI objects in complex UI.

White has come to provide some relives to automated UI tester to automate rich client application such as Win32, WinForms, WPF, Silverlight and SWT (Java) platforms. It is fully .Net based and it can be implemented any .Net based language. It uses Visual Studio IDE for scripting. It has no proprietary scripting languages. It provides a consistent object-oriented API, hiding the complexity of Microsoft's UIAutomation library (on which White is based) and windows messages.

How a simple windows application can be automated by using WHITE framework, is given below. To implement this we need:

WHITE Framework
Visual Studio IDE

Step 1 : Pick a sample application and create a Test plan to write automated test

We will automate our Calculator application and do some basic calculation using this tool.

Test case: Verify that user can add two numbers by using calculator.

Open the Calculator application
Click on 2 (Two) button
Click (+) button
Click on 3 (three) button
Click (=) equals button
Verify the result

Step 2 : Create a New Unit Test project

Open Visual Studio 2013
Click on File>New>Project

New project window is displayed.
Select .Net Framework 4
Select Unit Test Project as Project type
Enter project name as “CalculatorTest”
Browse the project directory
Click Ok button and new project Calculator test is created.

Step 3 : Download WHITE and add to project as reference

Go to Solution Explorer
Right click on the option Add reference
Click on Manage NuGet Packages…

NuGet package manager window is displayed.

Enter “White” as search text and press enter button from keyboard.
TestStack.White package is displayed and click on Install button.

Installation starts.

After finishing installation click close button to close the package manager window.

To verify that proper reference added we need to expand the References and see appropriate dll installed.

Step 4 : Writing code for Setting up Application

Go to Editor and write code for setting up application under UnitTest1 class.

In this section we will launch the application.

private TestStack.White.Application application;

 [TestInitialize]
 public void TestSetUp()
 {
      string ApplicationPath= @"C:\Windows\system32\calc.exe";
      application = TestStack.White.Application.Launch(ApplicationPath);
 }

White framework has its own method Launch() of Application class under TestStack.White namespace. This takes application path as argument and returns an object that has pointed to “application” variable.

We write this code under TestInitialize attribute so that it executes before running text. Main purpose is to start the application here.

Note that we need to add the namespace here.

using TestStack;

Step 5 : Writing code for Testing the application

Open the Calculator application.

This is written at public void TestSetUp() method.
// Define application Main window
   Window mainWindow = application.GetWindow("Calculator");
We need define the main window. We have Window class under TestStack.White.UIItems.WindowItems namespace. mainWindow object is used in detecting other UI object of Calculator application window. Our application.GetWindow() method returns the object of Calculator window. It takes window title “Calculator” as argument.
Note that we need to add the following namespace.
using TestStack.White.UIItems.WindowItems;

Click on 2 (Two) button

//Click on 2 (Two) button 
TestStack.White.UIItems.Button btnTwo=mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("2"));
btnTwo.Click();

Here a button object object is defined under TestStack.White.UIItems.Button class. Note that we also add search criteria for Two (2) button in calculator. Common Syntax to define an object and adding search criteria is

UIClassName objectName=windowObject.Get<UIClassName>(SearchCriteria.ByParameter(value));

Here,

UIClassName : There are separate classes for every UI object in WHITE. We have to find out which UI object and implement it among list of classes from WHITE.

objectName : Name of UI Object.

windowObject : It is the object of main window where the UI object possess.

SearchCriteria : This class contains search properties of the UIClassName.

ByParameter : It is the different types of property name of that UI class.

value : Property value of the UI Object.

Not that here we use ByText("2")) search property that contains the value 2. This is the same as “Name” properties of an UI object.

Also note that we need to add following namespace for Search Criteria.
using TestStack.White.UIItems.Finders; 

We can determine the properties and values by using VisualUIAVerify tool. You can download the tool from this site and get the documentation from this site. After downloading the VisualUIAVerify solution and you have to open it using Visual Studio and Build it. Then run exe file from bin folder.

To detect the search properties of an UI object using VisualUIAVerify tool, you need to run the application and then move mouse pointer to UI object and pressing CTRL key from Keyboard. It draws a blue color rectangle and show the property list and values under the application.

I will discuss in details on how to detect search properties of an UI object using VisualUIAVerify tool on my future posts.

Click (+) button

//Click (+) button 
TestStack.White.UIItems.Button btnPlus = mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("Add"));
btnPlus.Click();

Click on 3 (three) button

//Click on 3 (three) button
TestStack.White.UIItems.Button btnThree=mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("3"));
btnThree.Click();

Click (=) equals button

//Click (=) equals button
TestStack.White.UIItems.Button btnEquals = mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("Equals"));
btnEquals.Click();

Verify the result

//Verify the result 5
TestStack.White.UIItems.Label txtResult = mainWindow.Get<TestStack.White.UIItems.Label>(SearchCriteria.ByAutomationId("150"));
Assert.AreEqual("5", txtResult.Text);

Note that we have used ByAutomationId property which is common and unique to all controls. It is recommended to use this property as search property on most the cases if it is present and defined for that control.

Also we use AreEqual() method to verify expected result with the actual result. This method is under Assert class of VS Unit Test Framework.

Step 6 : Writing code for closing the application

[TestCleanup]
public void TearDown()
{
    application.Close();
}

Note that we Close() method to close the application.

Now our UnitTest1.cs file will look like the following,

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;

using TestStack;
using TestStack.White.UIItems.WindowItems;
using TestStack.White.UIItems.Finders;

namespace CalculatorTest
{
    [TestClass]
    public class UnitTest1
    {   
        private TestStack.White.Application application;

        [TestInitialize]
        public void TestSetUp()
        {
            string ApplicationPath= @"C:\Windows\system32\calc.exe";
            application = TestStack.White.Application.Launch(ApplicationPath);
        }

        [TestMethod]
        public void TestMethod1()
        {
            // Define application Main window
            Window mainWindow = application.GetWindow("Calculator");
            
            //Click on 2 (Two) button 
            TestStack.White.UIItems.Button btnTwo=mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("2"));
            btnTwo.Click();

            //Click (+) button 
            TestStack.White.UIItems.Button btnPlus = mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("Add"));
            btnPlus.Click();

            //Click on 3 (three) button
            TestStack.White.UIItems.Button btnThree=mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("3"));
            btnThree.Click();

            //Click (=) equals button
            TestStack.White.UIItems.Button btnEquals = mainWindow.Get<TestStack.White.UIItems.Button>(SearchCriteria.ByText("Equals"));
            btnEquals.Click();

            //Verify the result 5
            TestStack.White.UIItems.Label txtResult = mainWindow.Get<TestStack.White.UIItems.Label>(SearchCriteria.ByAutomationId("150"));
            Assert.AreEqual("5", txtResult.Text);
        }

        [TestCleanup]
        public void TearDown()
        {
            application.Close();
        }
    }
}