UIA Pro Add-in

Relevant for: GUI tests and components

This topic provides a basic understanding of UIA Pro Add-in and how to use UIA Pro to test applications that implement Microsoft UI Automation patterns.

Overview

UI Automation Pro (UIA Pro) is an advanced version of the existing UI Automation Support. Like UI Automation Support, it enables users to test Windows-based applications that have implemented UI Automation provider interfaces.

In addition, it makes test creation and maintenance easier, improves test performance, and provides support for more objects, methods, and patterns.

Using UIA Pro requires the UIA Pro Add-in to be installed and loaded.

Recently, this add-in has been enhanced further, to provide full maturity and support. For details, see UIA Pro enhancements.

For implementation guidance and optimization tips, see UIA Pro Add-in Best practices.

UIA Pro patterns

Using the UIA Pro Add-in, you can test applications that implement Microsoft UI Automation patterns regardless of how they appear visually. These patterns define the behavior and capabilities of the UI elements.

Different UI controls implement patterns that match their natural functionality.

For example:

Grid Pattern: Controls that display data in rows and columns, enabling capabilities like retrieving and manipulating cell data.

Example: UIAProDataGrid("Grid").GridPattern.GetCellValue(0,0)

Invoke Pattern: Controls that can be activated, such as buttons, checkboxes, and other clickable elements.

Example: UIAProButton("Button").InvokePattern.Invoke

Scroll Pattern: Controls like scroll bars, list boxes, list views, comboboxes, and other elements that handle scrollable content.

Example: UIAProScrollBar("ScrollBar").ScrollPattern.SetScrollPercent 50,50

The actual patterns available for any control may differ from the examples provided here. The patterns supported by any UI Automation element are determined by the application's implementation.

To identify the patterns supported by an object:

Use the Object Spy tool to inspect objects visually. The SupportedPatterns property lists all patterns supported by the selected object.

During runtime, use UIAProObject("Element").GetSupportedPatterns method.

UIA Pro functions

Each object supports many low-level functions that enable detailed communication with the application. To make your work easier, the UIA Pro Add-in also provides high-level functions that package several low-level functions together to provide methods that are more generic and simpler to use. If you need something designed more specifically, build the functionality yourself from the low-level functions.

High-level functions

Low-level functions are individual, direct interactions with UI elements that operate at the system or framework level. Using discrete low-level methods gives you full control over each step you perform, directly accessing and manipulate UI elements using specific patterns and properties. Low-level functions are ideal for more complex scenarios that require more advanced customization than the high-level functions provide.

Low-level functions

Low-level functions are individual, direct interactions with UI elements that operate at the system or framework level. Low-level methods consist of multiple discrete commands that give you full control over each step of interaction. They allow you to directly access and manipulate UI elements using specific patterns and properties. Low-level functions are ideal for more complex scenarios that require advanced customization than what high-level functions provide.

Example:

High-level functions	Low-level functions
`UIAProDataGrid("Grid").GridPattern.GetCellText(0,0)`	`UIAProDataGrid("Grid").GridPattern.GetCell(0,0).TextPattern.GetText()`
`UIAProDataGrid("Grid").GridPattern.GetCellValue(0,0)`	`UIAProDataGrid("Grid").GridPattern.GetCell(0,0).ValuePattern.GetValue()`
`UIAProDataGrid("Grid").GridPattern.ClickCell(0,0)`	`UIAProDataGrid("Grid").GridPattern.GetCell(0,0).Click`

Relative paths in object descriptions

A UIA Pro object's path property describes its position in the object hierarchy. Rather than using absolute paths, which represent the complete hierarchy starting from the root window, you can choose to describe an element using a relative path.

A relative path describes the test object in relation to its immediate parent, as defined in the object repository or programmatic description.

Use relative paths to simplify test maintenance; When the parent object's path changes, the child's relative path remains valid without requiring updates.

By default, a path property created for a new test object is an absolute path. You can manually edit an object's path property to be relative in the Object Identification Center (OIC), in the Object Repository, or in programmatic descriptions.

A test object with a relative path can be placed under a test object with an absolute path. however, if a relative path is used for an object, all its descendants must also use relative paths.

Relative paths are indicated by the tilde (~) character.

Example: Absolute path

Parent: Window;Pane;Pane
Child: Window;Pane;Pane;List;ListItem

Relative path

Parent: Window;Pane;Pane
Child: ~List;ListItem

Spy on objects in UIA Pro mode

The Object Spy and Object Identification Center provide a separate mode for UIA Pro object identification. Use this mode to identify objects based on their UI Automation properties and create UIA Pro test objects.

To spy on objects in UIA Pro mode

Do one of the following:

In the Object Spy, click the pointing hand drop-down arrow, select UIA Pro, and click the button to spy on an object in UIA Pro mode.
In the Object Identification Center, click the UIA Pro button to spy on objects in UIA Pro mode.

In the UIA Pro mode, you can view object properties, add the spied object to your local or shared repository, or drag it into your test to create a step. For details, see Use the Object Spy and Use the Object Identification Center.

Object properties are displayed as they would be recognized using UI Automation instead of their native technology.

Create UIA Pro test steps

You can create objects and add them to your test from the Object Spy or Object Identification Center.

Each test object supports the following types of methods:

OpenText Functional Testing common methods and properties, such as Click and Type.
Methods based on a control type's supported patterns. You can use the supportedpatterns description property to check what patterns an object supports.

For details on these test object methods, see the UIA Pro section of the Object Model Reference.

Note: The test objects and methods available are completely dependent on the properties and patterns implemented in your application. We recommend that you familiarize yourself with the properties of your application's objects - specifically the Control Type IDs and supported patterns to understand what test objects and methods you can use.

UIA Pro enhancements

This section describes the enhancement recently introduced in the UIA Pro Add-in.

Area	Enhancement
Performance and stability	The enhanced UIA Pro Add-in provides: Significant performance improvement. Increased testing stability.
Object hierarchy: Test object tree navigation	UI Automation applications often have deep object hierarchies. The enhanced add-in supports full access and interaction with all of the objects in the hierarchy. New methods enable comprehensive and flexible traversal of the test object tree: You can retrieve child or parent objects from all levels, or specify how many level of objects to retrieve. You can also provide a description of the type of children or parent objects to retrieve. For details, see the following methods in the UIAPro section of the Object Model Reference. GetAncestors, GetChildren, GetDescendants, GetParent. Use these methods instead of the ChildObjects method, which is still supported for backward compatibility.
Object hierarchy: Spying	The Object Identification Center shows the full hierarchy of a spied UIA Pro object. When adding a test object to the Object Repository, only its most significant ancestors are included.
Object hierarchy: Common methods and properties	Common methods and properties are supported on objects retrieved during a run session, such as by the GetCell method. The newly supported methods are: Exist, GetROProperty, GetTOProperty, SetTOProperty, Highlight, RefreshObject, ToString, CheckProperty, WaitProperty. This enables robust tests that can interact with objects found during runtime in the application's object hierarchy. For example, the following statement is newly supported: `UIAProDataGrid("dataGrid").GridPattern.GetCell(1,1).Highlight`
More specialized object descriptions	Assistive properties are supported, enabling the creation of optimized test object descriptions. Previously, all object identification properties were included in all UIA Pro test object descriptions. Now, you can see in the Object Identification dialog box which properties are considered for each type of UIA Pro test object. For details on using the Object Identification dialog box, see Configure object identification for a test object class. You cannot edit this list of properties, but after a test object is added to the Object Repository, you can edit its description, modifying the list of properties used to identify it, as well as their values.
Relative paths in object descriptions	To simplify test maintenance, you can define a test object's path property as a relative path in relation to its parent object. When the parent object's path changes, the child's relative path remains valid without requiring updates. For details, see Relative paths in object descriptions.
Fixed known defects	The following known issues have been fixed: Object indexes, meant to uniquely identify objects in the application, were not used correctly. Some steps, such as Highlight, GetROProperty, and RefreshObject were not included in the run results report. When an object that was temporarily inaccessible in the application became available again, test steps on that object failed. In some situations, OpenText Functional Testing stopped responding. In some of these cases, customers were required to reapply some registry keys. In some cases, highlighting an object from the object repository did not work. When running a test, its progression from step to step was not clearly displayed, sometimes creating the impression the run had stopped. When an object cannot be identified, the step fails and the report specifies which object could not be found. In some cases, the report specified one of the objects in the tests object's hierarchy, but not the object that was missing. When editing UIA Pro steps, code completion can suggest enumeration values to use for method arguments. These values were not recognized when running the test.