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:
- BusyTimeout defines how long to wait while the window is busy, see Get White Busy Timeout, Set White Busy Timeout
- FindWindowTimeout defines how long to wait until the specified window is found, see Get White Find Window Timeout, Set White Find Window Timeout.
In situations that require additional waiting for UI items, see keywords Wait Until Item Exists and Wait Until Item Does Not Exist.