52.1
Proceeding

The Microsoft UI Automation is an Accessibility and Test Framework allowing programs to control the GUI elements of native Windows applications. With QF-Test you can use the framework in script nodes via the Jython module uiauto (alternatively de.qfs.UIAuto for Groovy, uiauto for Javascript).

QF-Test provides a package in the standard library with procedures for the most commonly needed interactions with GUI elements for direct and easy use of the API for test development. This chapter describes the standard library package.

You will find the procedures relevant for control of native Windows elements in the package qfs.autowin. You can see several procedures marked as deprecated. They have been replaced by normal nodes of the win engine of QF-Test, and the procedures in the qfs.autowin package will not be further maintained. However, you can continue using them as they are. If you encounter problems, for example with scaled windows applications, it is advised to switch to the win engine.

Figure 52.1:  UI Automation procedures in the standard library

When developing tests for native windows applications you generally need to perform the following steps:

52.1.1
Starting the application

The application to be tested may but does not necessarily have to be started via QF-Test.

When starting the application via QF-Test the client process started is listed in the QF-Test menu »Clients« and can also be stopped via QF-Test.

Please use the procedure qfs.autowin.checkForExistence to check whether the application was started.

You will find an example for the start of an application in subsection 52.2.1.

52.1.2
Listing the GUI elements of a window

Before you can set up a test you need to get an overview of the GUI elements of the application. You may either use the procedure qfs.autowin.helpers.dumpComponents to print the GUI elements to the QF-Test terminal or qfs.autowin.helpers.dumpComponentsToFile to write them to a file.

The procedure qfs.autowin.helpers.DumpDesktopWindows allows you to list the titles of all open windows of the desktop.

qfs.autowin.helpers.dumpComponents prints the name (Name), the class (ClassName), the compontent type (ControlType) and the Id (AutomationId) of the GUI elements, provided they were implemented for the respective GUI element.

All the GUI elements visible on the Windows desktop are organized in a tree structure with the desktop as the root element. When calling the dump procedure you need to specify the window for which to list the GUI elements. Nesting of the components is represented via indentation.

Note The procedure dumpComponents() prints its output to the QF-Test terminal displayed in the botton part of the QF-Test window. The output is not displayed in the terminal or consoles which can be opened separately (client terminal and scripting consoles).

Please find an example in subsection 52.2.2.

52.1.3
Information on single GUI elements

The procedure qfs.autowin.helpers.dumpComponent allows you to print further information for single GUI elements, including a list of the methods available for the element as well as attribute values.

52.1.4
Identifiers for GUI elements

All procedures of the standard library package preforming actions on native Windows applications need to determine the respective GUI element as the first step and then perform the action in a second step. You find the procedures in the package qfs.autowin.component. Because all procedures use qfs.autowin.component.getControl to identify the GUI element, the parameters of this helper procedure are valid for all the procedures performing an action on a GUI element.

The following parameters (and combinations) are valid (in the order of evaluation):

AutomationId
The AutomationId is a unique identifier for the GUI element within a window. It has to be set explicitly during application development, which unfortunately does not always happen.
Name
The name usually corresponds to the text displayed. Names do not have to be unique and you may have to specify the ControlType or the ClassName of the GUI element additionally.
Names will be evaluated as regular expressions. For more information about regular expressions please see Regular expressions.
ControlType
The ControlType is a value from a predefined list of component types, e.g. Button, CheckBox, ComboBox, DataGrid, Edit, List, Tab, Text. The procedure qfs.autowin.helpers.dumpComponent shows the name and the numeric value of the respective ControlType. In order to identify a GUI element via its ControlType you usually need to specify its name or its index (relative to the GUI elements in the window of that ControlType), too, except there is just the one GUI element of that ControlType in the window.
ClassName
ClassNames are framework specific. Additionally to the ClassName you may specify the name or the index (relative to the GUI elements in the window of that ClassName) of the GUI element.
52.1.5
Actions on GUI elements

You will find procedures in the package qfs.autowin.component of the standard library for the most common actions. You are free to enhance the package. We recommend to use a separate test suite for the enhancement and not to change the qfs.qft since we continuously update the standard library and ship a new version with every QF-Test release.

Mouse click
Procedure: qfs.autowin.component.click

The procedure tries to replay a click event to the GUI element. In case this is not implemented the procedure replays a hard mouse click to the position of the GUI element.
Wait for component
Procedure: qfs.autowin.component.waitForComponent

The procedure waits for the given component and returns control to the calling node as soon as it finds the component. The given timeout (in milliseconds) is the maximum time to wait. It throws an exception if the component is not found within the given time.
Wait for window
Procedure: qfs.autowin.checkForExistence

The procedure waits for the given window and returns control to the calling node as soon as it finds the window. The given timeout (in milliseconds) is the maximum time to wait. The parameter 'errorLevel' specifies whether to log a message, warning, error or an exception in case the the window is not found within the given time.
Text input
Procedure: qfs.autowin.component.setText

The procedure uses the method setText() of the IUIAutomationElement interface to enter a text to the given component. In case the setText() method has not been implemented for the component please use setValue().
Keyboard events
The Package qfs.autowin.keyevents provides procedures for replaying the keyboard events ENTER, TAB and DELETE. The procedure qfs.autowin.keyevents.sendKey lets you replay any key like a single letter, a digit, a function key, etc, also combined with the modifiers SHIFT, CTRL and ALT. The event is replayed to the component with the focus in the given window.

Fetch text
Procedure: qfs.autowin.component.getText

The text of a GUI element cannot be accessed directly. The name of a GUI elements usually corresponds to the text displayed. Some elements have a value corresponding to the text, independently of the name.The procedure getText() first tries to determine the value of the element and, in case this fails or the value is an empty string, returns the name of the element.

The procedures getName() and getValue() are provided additionally.
Fetch geometry
Procedure: qfs.autowin.component.getGeometry

Check text
Procedure: qfs.autowin.component.checkText

The procedure fetches the text of the GUI elements via the procedure getText() and compares the value returned with the given text.

The procedures checkName() and checkValue() are provided additionally.
Check geometry
Procedure: qfs.autowin.component.checkGeometry

The procedure fetches the geometry data via getGeometry() and compares them to the given values.
Image check
Procedure: qfs.autowin.component.checkImage

The procedure relies on a file with a reference image. The file needs to have a png format. The procedure determines the screen coordinates of the element via qfs.autowin.component.getGeometry. The actual comparison is done via the procedure getPositionOfImage() of the qfs.autoscreen package of the standard library.

Select an item in a menu
Procedure: qfs.autowin.menu.selectItem

Especially when single-stepping through the test when debugging it is useful to have a procedure which clicks to a menu and its menu item which can be executed in one step. Thus the application will not loose the focus between steps which might cause the menu to close.