Use Visual Relation Identifiers (VRIs)


Visual Relation Identifiers (VRIs) are a set of definitions that enable you to distinguish between similar objects in your application according to the relative location of their neighboring objects. This can be useful when there are multiple identical objects displayed in your application, such as two copies of a logo or multiple buttons with the label, 'Buy now'.

You must provide a set of normal description properties that enable UFT Developer to identify at least one object in your application, and then add VRI definitions of neighboring or related objects to make your test object unique.

You should select related objects that are expected to maintain the same relative location to your object over time, even if the user interface design changes.

This enables you to help UFT Developer identify similar objects much as a human tester would, and helps create more stable tests that can withstand predictable changes to the application's user interface.

There are a number of possible horizontal and vertical relationships you can define. For a visual demonstration of these relationships, see Horizontal and vertical visual relations below.

VRIs are supported in all UFT Developer technologies, including mobile native applications and mobile hybrid applications.

Note: You cannot create a VRI definition for a test object that is already defined as a related object for another test object.

  • In the application model, the + Reference Object button is unavailable for such a test object.

  • If you create such a definition programmatically, UFT Developer fails to identify the test object during the run and a VriDescriptionException is thrown.

Back to top

Create VRI definitions programmatically

Your VRI definition is comprised of a set of VisualRelation objects. For each VisualRelation, you indicate an existing test object and what that test object's visual relation is to the test object you are now defining.

The possible relations are defined in the HorizontalVisualRelation, VerticalVisualRelation, and ProximityVisualRelation enumerations.

For example, in the Windows calculator application, the '1' button has '2' and '3' buttons to the right of it and a '4' button above it. You could use these relations to describe the '1' button as shown in the following C# example:

//Create the Calculator description
var calculatorDescription = new WindowDescription { WindowClassRegExp = "CalcFrame", WindowTitleRegExp = "Calculator" }; //Create the calculator parent Window test object
IWindow calculator = Desktop.Describe<IWindow>(calculatorDescription); //Create test objects for buttons 2, 3 and 4
var button2 = calculator.Describe<IButton>(new ButtonDescription { WindowId = 132, NativeClass = "Button" }); var button3 = calculator.Describe<IButton>(new ButtonDescription { WindowId = 133, NativeClass = "Button" }); var button4 = calculator.Describe<IButton>(new ButtonDescription { WindowId = 134, NativeClass = "Button" }); //Create a test object for button 1 based on its visual relationship to buttons 2, 3, and 4
var button1 = calculator.Describe<IButton>( new ButtonDescription { NativeClass = "Button", Vri = { new VisualRelation { TestObject = button3, HorizontalRelation = HorizontalVisualRelation.RightAndInline, }, new VisualRelation { TestObject = button4, VerticalRelation = VerticalVisualRelation.Above, } new VisualRelation { TestObject = button2, ProximityRelation = ProximityVisualRelation.ClosestOnXAxis, } } });

Back to top

Add VRI definitions to a test object in the Application Model editor

  1. Make sure the application model already includes both the test object that requires a VRI definition and any related objects you want to use in the VRI definition.

  2. In the Application Model editor, select the test object that requires the VRI definition.

  3. In the Identification section, click the All link to display all available identification properties.

  4. Scroll down to the Featured properties section.

  5. Select the VRI property and click + Reference Object.

  6. The cursor becomes a pointing hand. Point to the related test object in your application model. Details of the selected test object are displayed. Click Select to add the object.

  7. The related object is displayed under the VRI section. In the Relation box, select the relation type that describes the related object's relationship to your object.

    You can indicate the relation based on the related object's horizontal or vertical relationship (left, right, above, below), or you can describe the related object's proximity to your object (closest object on the x-axis or closest on the y-axis).

    If you specify a horizontal or vertical relationship, you can further refine the relationship by indicating whether the object is in line with your object.

    For a visual demonstration of these relationships, see Horizontal and vertical visual relations below.

  8. If needed, you can click the +Relation link to add another relationship for the same related object. For example, you can set the relation of a related object to be both left and above your object.

  9. If needed, click + Reference Object again to add another related object.
  10. Preview your VRI settings

    1. Make sure your application is open and displays both the object you want to identify and the related object.
    2. Click the VRI Preview button (located to the right of the +Reference Object link) to test whether the VRI definitions you created provides a unique description for your test object. If it does, exactly one object is highlighted. The objects recognized as the visual relations are marked in another color.
    3. If zero or multiple objects are highlighted, adjust your VRI definitions and use the VRI preview again.

Back to top

Horizontal and vertical visual relations

The following diagram illustrates the way UFT Developer interprets horizontal and vertical visual relations.

It also shows the boundaries that are used for determining in line related objects.

So how are in-line related objects identified?

When you select a related object as a horizontal and/or vertical relation, you can also fine-tune that definition by indicating that it is in line with the test object to identify.

UFT Developer identifies the related object as in line even if the area of the related object surface is only partially in line with the test object.

The following example illustrates how UFT Developer identifies related objects that are in line with the test object to identify.

Back to top

See also: