WhiteLibrary

WhiteLibrary is a Robot Framework library for automating Windows GUI.

It is a wrapper for TestStack.White automation framework, which is based on Microsoft UI Automation API (UIA).

Applications and windows

To interact with UI items, the correct application and window must be attached to WhiteLibrary.

When application is started with Launch Application, the keyword also attaches the application to WhiteLibrary. Attaching a running application is done with Attach Application By Name or Attach Application By Id.

Once the application is attached, the window to interact with is attached with Attach Window.

Examples:

# Launch application, no separate step for attaching application needed
Launch Application C:/myApplication.exe
Attach Window Main window
# Switch to an application that is already running
Attach Application By Name calc1
Attach Window Calculator

UI items

WhiteLibrary uses the same names for UI items (=controls) as White. See White's documentation for details about mapping UIA control types to White's UI item classes.

For example, the UIA control type Text maps to the Label class in White (e.g. in WhiteLibrary's keyword Verify Label).

Item locators

Keywords that access UI items (e.g. Click Button) use a locator argument. The locator consists of a locator prefix that specifies the search criteria, and the locator value.

Locator syntax is prefix:value. The following locator prefixes are available:

Prefix Description
id (or no prefix) Search by AutomationID. If no prefix is given, the item is searched by AutomationID by default.
text Search by exact item text or name.
index Search by item index.
help_text Search by HelpTextProperty.
class_name Search by class name.
control_type Search by control type.

Examples:

Click Button myButton # clicks button by its AutomationID
Click Button id:myButton # clicks button by its AutomationID
Click Button text:Click here! # clicks button by the button text
Click Button index:2 # clicks button whose index is 2

Note: Old locator syntax prefix=value is also valid but it is recommended to use the prefix:value syntax since the old syntax will be deprecated in the future.

Item object as a locator

It is also possible to use an item object reference as the locator value. An item object can be obtained with e.g. Get Item or Get Items keywords.

The need to use an item object reference can arise for instance when multiple items match the same locator and one of the items is selected for further action. When using an item object, the action on the item can be executed regardless of the window it is in, i.e. the window where the item is located does not necessarily need to be attached. However, this does not change the attached window and the operation continues in the attached window after action on the referred item is complete.

Example using item object:

@{my_buttons}= Get Items class_name:MyButtonClass
Click Button ${my_buttons[2]} # clicks button object at index 2 of the list

Workflow example

*** Variables ***
${TEST APPLICATION} C:/path/to/my_application.exe
*** Settings ***
Library WhiteLibrary
*** Test Cases ***
Small Example
Launch Application ${TEST APPLICATION}
Attach Window Window Title
Button Text Should Be my_button press this button
Click Button my_button
Close Application

Waiting and timeouts

White handles a lot of the required waiting automatically, including waiting while the window is busy and waiting for a window to appear.

White's internal waits use timeouts that can be read and configured with keywords:

In situations that require additional waiting for UI items, see keywords Wait Until Item Exists and Wait Until Item Does Not Exist.