Test Automation FX

UI test automation for .NET developers

Introduction to the Test Automation Framework
In this document, well take a look at the generated test code and the framework that it
runs within. Sooner or later youll inevitably need to go beyond just recording. The real
power of TAFX is the ability it gives you to adapt your tests to suit your needs exactly. TAFX
lives within Visual Studio and it combines a simple to use API with the all the power that the
.NET framework offers.

Test Fixtures
Test fixtures are at the heart of a TAFX project. They contain the actual test code and
objects they need to find the applications and windows that are exercised during a test.

Test Methods
When TAFX is running the suite of tests in your application, it will look for all public
methods with the UITest attribute attached to them. So every method in your test code
needs to have the following signature:
[UITest]
public void TestAddition()
{
}

If you want to temporarily ignore a test method, you can attach the UIIgnoreTest attribute
to it. This will cause TAFX to leave that test out of the test run and report it as ignored. You
should add a reason to the ignore attribute so that it will be clear from the test results why
the test has been ignored.
[UITest]
[UIIgnoreTest("Waiting for new component library")]
public void TestAddition()
{
}

Interacting with the Application Under Test (AUT)

TAFX offers you a powerful way to have your tests interact with other applications and their
GUI elements. Tests perform actions on, and verify state of, the application under test via
UIObjects.

Test Automation FX
UI test automation for .NET developers
The following test method uses UIObjects to manipulate the Windows Calculator:
[UITest()]
public void TestAddition()
{
Button1.Click();
ButtonAdd.Click();
Button4.Click();
ButtonEquals.Click();
TextBox1.VerifyProperty("Text", "5, ");
}

There are several types of UIObjects, but the most common ones are UIApplication, which
represents an application, and UIWindow, which represents windows in an application.
The UIObjects of a TAFX project are stored in a hierarchical structure with the TestFixture at
the root, having one or several UIApplication objects as its direct descendants. Under each
UIApplication there are UIWindow objects that represents the different windows and
controls of the application.

All of the objects used here are UIObjects. TAFX creates and initializes these in the designer
part of your TestFixture class:
partial class TestFixture1
{
// ...
private void InitializeComponent()
{
CalcApplication = new TestAutomationFX.UI.UIApplication();
CalculatorWindow = new TestAutomationFX.UI.UIWindow();
Button1 = new TestAutomationFX.UI.UIWindow();
ButtonAdd = new TestAutomationFX.UI.UIWindow();
Button4 = new TestAutomationFX.UI.UIWindow();
ButtonEquals = new TestAutomationFX.UI.UIWindow();

Test Automation FX
UI test automation for .NET developers
TextBox1 = new TestAutomationFX.UI.UIWindow();
// ...
}
}

Matching UIObjects
The UIObjects acts as representatives for the parts of the application under test that we
want to manipulate. When we perform an action, such as a click, on a UIObject for the first
time, it will attach itself to the corresponding object in the application under test.
How a UIObject will find the corresponding object in the AUT is controlled by its matching
properties. These describe the conditions used to determine what object in the AUT we
should attach to.
The UIWindow object that represents the button for the number 1 in the Windows
Calculator example, has the following matching properties set:
Button1.Parent = CalculatorWindow;
Button1.WindowText = "1";
Button1.WindowClass = "Button";
Button1.Index = 7;
Button1.MsaaRole = System.Windows.Forms.AccessibleRole.PushButton;
Button1.MatchedIndex = 0;

When we call Button1.Click() for the first time in the test code, these properties will be
used to find the window that:
-

Is a child of CalculatorWindow (Parent)

Has the window text 1 (WindowText)
Is of the Button window class (WindowClass)
Is the seventh child window of CalculatorWindow (Index)
Has the MSAA role push button. (MsaaRole)
If several windows match these properties, we can indicate which one of the matches to
select by setting the MatchedIndex property. In this example we only expect there to be
one window to fit this description, so we set MatchedIndex to 0.

Attaching to a Process
The UIApplication has matching properties as well.
CalcApplication.ImagePath = "C:\\WINDOWS\\system32\\calc.exe";
CalcApplication.ProcessName = "Calc";
CalcApplication.CommandLineArguments = "";
CalcApplication.MatchedIndex = 0;
CalcApplication.UsedMatchedProperties =

Test Automation FX
UI test automation for .NET developers
IApplicationMatchedProperties.ProcessName |
UIApplicationMatchedProperties.ImagePath) |
UIApplicationMatchedProperties.CommandLineArguments;

When TAFX attempts to attach CalcApplication to an application, it will look for a process
that:
-

has the full path C:\Windows\system32\calc.exe (ImagePath)

has the name Calc (ProcessName)
is started with no command line arguments (CommandLineArguments)
The UseMatchedProperties property specifies which of the matching properties are used
when TAFX attaches this object to a process.
If no process can be found that matches the specified criteria, you can use the
StartAutomatically property to tell TAFX wether it should attempt to start the application
automatically or consider the test failed if the correct process cannot be found.

Hooking Into the Attachment Process

The UIObjects generates events during the attachment process. You can intercept these
and change how your test code behaves. The events that you can intercept are:

ActionExecuting. UIObjects generate this event when you perform an action on them, such as
clicking or dragging.
Attaching. UIObjects generate this when they are attempting to attach to objects in the AUT.
Attached. UIObjects generate this event when they have attached to objects in the AUT.
AttachFailing. UIObjects generate this event when they are about to consider the attempt to
attach to objects in the AUT failed.
AttachFailed. UIObjects generate this event when they have failed to attach to objects in the
AUT.
ActionExecuted. UIObjects generate this event an action is completed.
To subscribe to the events that are generated by a UIObject, the easiest way is to select
that UIObject in the design view and add an event handler in its property grid.

Test Automation FX
UI test automation for .NET developers
ActionExecuting
The ActionExecuting event is generated when your test code performs an action on a
UIObject.
private void Button1_ActionExecuting(object sender, ActionEventArgs e)
{
UIWindow button1 = (UIWindow)sender;
//...
}

The sender parameter is a reference to the UIObject that generated the event, and the
ActionEventArgs contains information about what action is performed on it.
It is possible to cancel the action by setting the ActionEventArgs.IsCanceled property to
true.

Attaching
If this is the first action on the UIObject in question, it will attempt to attach itself to the
corresponding object in the AUT. This will trigger the Attaching event.
You have the opportunity to override the attaching behavior in this event handler. You can,
for instance, create your own function for finding the correct window in the AUT and set
the Window property of a UIWindow yourself.
private void Button1_Attaching(object sender, EventArgs e)
{
UIWindow button1 = (UIWindow)sender;
button1.Window = CustomWindowFinder();
}

Attached
When a UIObject is attached to its AUT counterpart it will trigger the attached event.
private void Button1_Attached(object sender, EventArgs e)
{
UIWindow button1 = (UIWindow)sender;
//...

AttachFailing
If TAFX fails to find a match for a UIObject, it will fire the AttachFailing event.
private void Button1_AttachFailing(object sender, AttachFailingEventArgs e)
{
UIWindow button1 = (UIWindow)sender;
//...
}

Test Automation FX
UI test automation for .NET developers
The AttachFailingEventArgs parameter gives you the opportunity to change TAFXs default
behavior of considering the test failed. You can change some of the conditions of the AUT
and then tell TAFX to try again by setting the Action property to AttachFailingAction.Retry.
You can also use your own method of finding the correct object in the AUT and attach the
result to the UIObject triggering the event. You indicate this by setting the Action property
to AttachFailingAction.Handled.

AttachFailed
When an attach operation has failed for a UIObject, it will generate the AttachFailed event.
private void Button1_AttachFailed(object sender, EventArgs e)
{
UIWindow button1 = (UIWindow)sender;
//...
}

ActionExecuted
UIObjects triggers the ActionExecuted event when they have completed an action. This
event marks the end of the cycle for performing actions.
private void Button1_ActionExecuted(object sender, ActionEventArgs e)
{
UIWindow button1 = (UIWindow)sender;
//...
}

The ActionEventArgs enumerator contains information about what type of action has been
completed.

The IsOptional Property

If you set the IsOptional property of a UIObject, TAFX wont report an error or stop the test
if it fails to match that object. This is useful for when you have controls or windows that
may or may not show up during a test run.
You might, for instance, have a dialog that records information about the user the first time
an application is run, but not on subsequent runs. In that case you can add test code that
enters the correct user information and mark the dialog as optional. That way you can
make sure that if the dialog pops up it will be filled with the correct data, without you
having to add any specific code on your own.
Tip: If you set the IsOptional property, it also a good idea to lower the time that TAFX waits
for the UIObject. This can reduce the time it takes to run your tests dramatically.

Test Automation FX
UI test automation for .NET developers
Verifying the State of the AUT
Up until now we have been talking about how to automatically exercise your AUT from
TAFX. We also need to verify that the application responds to the actions we perform on it
in the way we expected. We need to test the state of the application.
TAFX allows you to verify the state of the AUT in several ways. You can also create your own
custom verifiers to if you need to go beyond the ones provided out of the box.

Verifying Properties
Most of the time you will probably verify that the properties of controls have the correct
values. You might, for instance, verify that a text box displays the correct text, or that a
button is enabled or disabled correctly.
You verify the property of a UIObject by calling its VerifyProperty method:
[UITest()]
public void TestAddition()
{
Button1.Click();
ButtonAdd.Click();
Button4.Click();
ButtonEquals.Click();
TextBox1.VerifyProperty("Text", "5, ");
}

This code verifies that text box of the Windows Calculator (TextBox1) contains the correct
result after weve performed a simple calculation. The first parameter is the name of the
property that we want to verify, and the second parameter is the expected value.

Verifying Controls against an Image

You can verify that a control has the correct appearance by comparing it to a bitmap. TAFX
will automatically save a bitmap for each of the controls that it encounters during the
recording of a test, and attach that to the corresponding UIObject. You can see those
bitmaps in the design view for your test fixtures.
You can verify a control either against the automatically generated bitmap, or against a
bitmap that you provide yourself.
[UITest()]
public void TestVerifyImage()
{
//...

TextBox1.VerifyImage();
}

Test Automation FX
UI test automation for .NET developers
Miscellaneous Verification Helpers
The Verify class contains helper methods that you can use to perform a few useful
verifications in your test code. All these methods will throw a VerifyException if the
verification fails.
You can use the Verify.FileExists method and its overloads to verify that a file exists.
[UITest]
public void Test()
{
//...

Verify.FileExists("C:\\Output\\Result.log");
}

You can use the Verify.AreEqual method to verify that two different objects are equal.
[UITest()]
public void Test()
{
//...

Verify.AreEqual(resultFromOperation, 5);
}

You can use the Verify.UserAcknowledge to make the test display a dialog asking the user to
verify that the AUT seem to be in the correct state.
[UITest()]
public void Test()
{
//...

Verify.UserAcknowledge("Does this seem right to you?");

}

The Verify.FailTest will make the test run fail.

[UITest()]
public void Test()
{
//...

if(SomeImportantRequirementIsNotMet())
{
Verify.FailTest("Some important requirement is not met.");
}
}

Test Automation FX
UI test automation for .NET developers
Custom Verifiers
TAFX allows you to easily create your own custom verifiers. A custom verifier that you
create will automatically be visible and configurable from the Add Verification dialog when
you are recording a new test.

To add your own verifier, you simply add a new class that derives from the CustomVerifier
class to your test project.
public class MyCustomVerifier : CustomVerifier
{
//...

NB! Remember to set the class as public.

This will automatically add your class to the list of available verifiers that you can use while
recording a test.
You need to override the following methods and properties in you custom verifier to give it
the behavior you want:
public override string DisplayName
{

Test Automation FX
UI test automation for .NET developers
get
{
return "Check maximum WorkingSet";
}
}

This property is used by the Add Verification dialog to display the name of the custom
verifiers.
If you need to, you can also add public properties to your class. These will automatically be
editable from the Add Verification dialog. You should also use the DescriptionAttribute to
add a short description about the properties and how they should be used.
[Description("The UIApplication to check the WorkingSet for.")]
public UIApplication Application { get; set; }

You use the Validate method to make sure that the user has set up the custom verifier
properly. When the user clicks the Ok button to add the verifier, TAFX will call this method.
If something is wrong with how the verifier has been set up, you have the opportunity to
tell the user that something has to be done to be able to continue.
public override bool Validate()
{
if (Application == null)
{
MessageBox.Show("The Application property must be set");
return false;
}
return true;
}

When youre done recording a test, TAFX will generate code that will perform the
verification when you run the test later. To determine what code to generate, TAFX will call
the methods StaticVerifyMethodName and GetParameters.
You implement the code that performs the actual verification when you run a test as a
static method in your custom verifier. The StaticVerifyMethodName should return the
name of that method.
public override string StaticVerifyMetodName
{
get
{
return "VerifyMaxWorkingSet";
}
}

10

Test Automation FX
UI test automation for .NET developers
You can tell TAFX what parameters it should pass to your custom static verification method
by having the GetParameters method return the values of those parameters as an object
array.
public override object[] GetParameters()
{
return new object[] { MaxWorkingSetKb, Application};
}

This will cause TAFX to inject something like the following code into your tests:
MyCustomVerifier.VerifyMaxWorkingSet(12, CalcApplication);

11