Controls Repository - AppMask

The AppMask File

To make use of UIAutomation and WebAutomation actions, use of AppMasks is required. AppMasks, contains the selectors of the elements of Web and Desktop Applications used.

An AppMask file has the extension “.appmask” and can be generated using the UISpy Application.

An AppMask file is in the form of a tree structure in JSON which contains an Application. The application then contains multiple screens. Likewise, every screen contains multiple controls.

Both Screens and Controls use selectors to locate elements on the applications.

graph LR; A(AppMask) --> B B(Application) B -->| 1st | D(Screen 1) B -->| 2nd | E(Screen 2) B --> V(...) B -->| nth | F(Screen 3) D --> G(Control 1) D --> H(Control 2) E --> I(Control 3) E --> J(Control 4) E --> K(Control 5) F --> L(Control 6) F --> M(Control 7) style V opacity:0; linkStyle 3 opacity:0;

Adding Screens and Controls to an AppMask

Adding Screens

To add a screen to the AppMask, click on the “Add screen” button and the “Tracking Session Window” will appear. Hovering over windows of the machine, a red rectangle will appear allowing you to select the window of your preference. Hold down the Control Key and click on the Window to select it. Once the Window is selected, it will appear under the UI Spy Editor.

Adding Controls

Similarly, Controls can be added to an AppMask by clicking the “Add Control” button. Hovering the mouse over elements on the screen will show the red rectangles around them. By holding the Control key and clicking on an element, the respective control will be added on the “Tracking Session Window”.

Once you click on “DONE”, all the Controls will be sorted under the respective Screen of the Robin UISpy Editor.

Importing the AppMask

To import an AppMask file to an automation the term import needs to be used followed by the path to the file in quotes.

The AppMaskFile located under the “C:” drive is imported to the automation.

import "C:\AppMaskFile.appmask"

The import statement should always be at the top.

Referring to the AppMask

Once a file is imported, the controls can be refered using the elements of the tree structure. In the following example, the calculator application is used.

The application is called CalcMaskApp and the application set is Calculator. The Screens captured are named Window_Main and Second_Window. Button_1, Button_2 and Button_3 belong to the Window_Main Screen, while Button_4 is Second_Window’s control.

  • AppMask = CalcMaskApp
  • Application = Calculator
  • Screen = Window_Main,
  • Controls
    • Window_Main
      • Button_1
      • Button_2
      • Button_3
    • Second_Window
      • Button_4

To call a control of the AppMask in an action the name of the AppMask, the Screen and Control are required. However, the Application is not mandatory.

In AppMasks containing only one Screen, the Screen value can be omitted as well.

As a result the syntax of the control of Button_2 and Button_4 would look as follows.

CalcMaskApp.Calculator.Window_Main.Button_1
CalcMaskApp.Calculator.Second_Window.Button_4

or

CalcMaskApp.Window_Main.Button_1
CalcMaskApp.Second_Window.Button_4

Below the control of Button_3 is used within the UIAutomation, “Click Element” action.

UIAutomation.Click Element:CalcMaskApp.Calculator.Window_Main.Button_3  ClickType:ClickType.LeftClick MousePositionRelativeToElement:RectangleEdgePoint.MiddleCenter OffsetX:0 OffsetY:0