UITestSD external object

Official Content
This documentation is valid for:

The UITestSD external object allows for the development of automated User Interface (U.I.) Tests for Smart Device Applications in GeneXus





Several of the methods described below and used for UI Test receive a string that may stand for both a text on screen and for a control name as well.

Control Name

Control name is the name of a control as shown in the Control Name property in the GeneXus object where it is defined.

Control Name examples: "&numeric" (for a variable), "CustomerName" (for an attribute), "Save" (for a button).

Note: the casing is not important, because GeneXus ignores it.


In some cases, it is necessary to disambiguate the name of the control. For example, in the case of an SD Component on screen, there may be two controls with the same control name.

In such case, all the functions that receive a control name will also receive a context optional parameter indicating where the control is.

For example, if you want to tap on a button called "button1" located in the second row of the "grid1" grid, you must write:

tap("button1", "grid1.item(2)")

Note: this context defines a route where controls should be found, though it is not necessary for the route to be complete. For example, in the above case, the "button1" button could also be inside a "Grid1Table" table, which will not have to be indicated.

Note: For controls representing collections (Grid, Horizontal Grid, Tab Control, etc.), there is the "function" item to indicate an element within the collection.

Predefined contexts

In many cases, the context depends on the names of the controls –for example, "Grid1"– but there are also cases in which the context can be predefined.

This happens with the controls in the Application Bar.
To this end, an enumerated domain is defined: UITestingContext.

UITestingContext Domain

The domain is based on the same data type as the context in the function parameters, i.e. VarChar(40).
This enumerated domain has only one value (for the moment):
ApplicationBar (value: "applicationbar"): represents the context of the Application Bar; when this context is indicated, only elements found there will be searched.

Note: If the Application Bar context is indicated, in addition to searching for the elements that are visible there, the elements that were placed in the Application Bar at design time should also be searched. Because there is not enough space, they were grouped by the flexible client and it is necessary to press an additional button to find them.  


In the context of this document, we refer to "target" or "action target" when the action may be done on:

a control name, or
any text shown on screen.


In a search for elements on screen, you first search by control name, and in the event that none is found, then you search by text.

If there is more than one control fulfilling the conditions, then you use the first one found (non-deterministic).

Methods for Actions


Simulates the action of the back  button in the device for the case of Android, and it is a tap in the button for that purpose in the case of iOS.



It does a tap on a given point on screen. The point is given by an action target.

tap(<target> [, <context>])


It does a long tap on a given point on screen. This point is given by an action target.

longTap(<target> [, <context>])


It does a double tap on a given point on screen. This point is given by an action target.

doubleTap(<target> [, <context>])


It enters a value in a given control of the Edit type.

fill(<control name>, <value> [, <context>])


It enters a value in a field of the Date type using the corresponding picker.

pickDate(<control name>, <year>, <month>, <day>, [, <context>])


It enters a value in a field of the DateTime type using the corresponding picker.

pickDateTime(<control name>, <year>, <month>, <day>, <hour>, <minutes>, [, <context>])


It enters a value in a field of the Time type (a.k.a. DateTime without Date part) using the corresponding picker.

pickTime(<control name>, <hour>, <minutes>, [, <context>])


It enables the selection of a value from a list of values of a Combo Box or Radio Button, given by its Control Name. The value to be selected is indicated in the "value" parameter.

selectValue(<control Name>, <value> [, <context>])


It does a swipe over the screen in the direction indicated by the parameter. The starting point of the swipe depends on the parameter. There is also the option to indicate the control where it should start. In the absence of an indication, the swipe will start at a fixed point on the screen (the fixed point will depend on the direction).

swipe(<direction> [, <control name>] [, <context>])

where <direction> may be "Up", "Down", "Left", or "Right".

  • Up - does a swipe upwards from the center of the lower margin on the device (some pixels above the border) or from the control if it is indicated.
  • Down - does a swipe downwards from the center of the upper margin on the device (some pixels under the border) or from the control if it is indicated.
  • Left - does a swipe to the left from the center of the right margin on the device (some pixels to the left of the border) of from the control if it is indicated.
  • Right - does a swipe to the right from the center of the left margin on the device (some pixels to the right of the border) or from the control if it is indicated.

Note: In iOS, it is not possible to indicate from which position the swipe should start. It is always done (apparently) from the center of the control.


Waits for a given number of milliseconds.



Methods for Verifications

Verifications will cause the test case to fail in the case of non-compliance. When conditions are fulfilled, they do not cause the test to fail.


Verifies whether a text is on screen, anywhere, unless a context has been indicated.

verifyText(<string> [, <expected>] [, <context>])


Verifies whether the number of rows on a grid equals the given value.

verifyGridRowsCount(<grid control name>, <value> [, <expected>] [, <context>])


Verifies whether a control of the checkbox type has been checked or not, according to the (Boolean) "value" indicated.

verifyCheckbox(<control name>, <value> [, <expected>] [, <context>])


Verifies whether a control has the value indicated or not.

verifyControlValue(<control name>, <value> [, <expected>] [, <context>])


Verifies whether a control is enabled to edit or not (readonly)

verifyControlEnabled(<control name> [, <expected>] [, <context>])

In iOS, this verification is always successful. In theory, in the API of Xcode you have an isEnabled properpty, but in the cases tested, it returns true every time.


Verifies whether an alert with a specific message sent with the msg command of GeneXus is presented.

This verification must be done both in the title and in the text of the alert.

verifyMsg(<string> [, <expected>])


Verifies whether the control is visible on screen or not.

verifyControlVisible(<control name> [, <expected>] [, <context>])


Takes a screenshot of a control or the entire screen and compares it to a reference image. If the comparasion fails, the test fails.

verifyScreenshot(<reference> [, <control name> [, <context>]])

The reference parameter is of string type and identifies the reference image within the current test.

Note: Using this function requires some additional setup. You can find more information in Visual testing in Native Mobile applications.

The verifyScreenshot method is available as of GeneXus 17 upgrade 7.<meta charset="utf&#45;8"/>


Similar to VerifyControlEnabled but returns a boolean instead of failing the test.

If the control is not found, the command fails with an assert.

IsControlEnabled(<control name> [, <context>]): Boolean


Similar to VerifyControlVisible but returns a boolean instead of failing the test.

If the control is not found, the function returns False.

IsControlVisible(<control name> [, <context>]): Boolean


Returns True if an alert is being displayed on screen.

Note: does not take into account system alerts, for example if it is asking for permission to receive notifications. 

IsShowingMessage(): Boolean


Gets the value of the control and returns a string.

If the control is not found, the command fails with an assert.

GetControlValue(<control name> [, <context>]): VarChar


Similar to VerifyCheckbox, returns a boolean with the value of the checkbox.

If the control is not found, the command fails with an assert.

GetCheckboxValue(<control name> [, <context>]): Boolean


Similar to VerifyGridRowsCount, returns an integer with the number of rows in the Grid.

If the Grid is not found, fails the test with an assert.

GetGridRowsCount(<control name> [, <context>]): Numeric(8)


If there is an alert on the screen, it gets the text of the alert. Similar to VerifyMsg.

If the alert is not found, the command fails with an assert.

GetMessageText(): VarChar


Receives a boolean and optionally a message, if the boolean is False then it fails the test and uses the message as the reason for the failure.

VerifyCondition(<boolean value> [, <message>])