Addressing Objects in iOS Applications

About Object Hierarchy

How to Know the Object Name

Addressing Objects Without Name Mapping and Aliases

Addressing Objects Using Name Mapping and Aliases

To explore the object structure of a tested iOS application, run the application on your iOS device and connect the device to your computer. In order for TestComplete to be able to “see” the application, your computer and the application must be prepared for testing.

You can view the object hierarchy in the Object Browser panel. Here is a sample view of iOS objects in this panel:

Click the image to enlarge it.

Here, the top-level object is Mobile. It is a root object in the hierarchy of mobile test objects. Its Device branch corresponds to your iOS device. The Process node corresponds to the tested application that you have launched on the device. The items below the Process node corresponds to the application’s windows and controls. To simplify the object hierarchy, TestComplete does not display auxiliary objects (like containers) unless they represent application windows or controls. Details of object naming are described below.

To find the name of a test object, choose the desired object in the object tree. The name will be above the Properties page:

It may be difficult to determine what item in the object tree corresponds to the desired control. In this case, to know the test object name, use the Object Spy window:

1. Launch your iOS application and connect the device to TestComplete.

2. Click Show Mobile Screen on the TestComplete Test Engine toolbar. This will invoke the Mobile Screen window.

3. Now, on the Tools toolbar, click Display Object Spy. This will invoke the Object Spy window.

4. Select the desired onscreen object in the Mobile Screen window. You can either pick it with the target glyph ( ) or use the 'Point and Press a Shortcut' mode. See Working With Object Spy Window.

5. After you picked the control, TestComplete will display the name of the appropriate test object above the Properties tabbed page in the Object Spy window.

   

We would like to note that the name you copied in the Object Browser or Object Spy can be different from what you see in the object tree on the left of the Object Browser. This is because the name displayed at the top of the panel uses object aliases if they are defined, whereas the object tree uses the naming syntax that includes identification properties. The difference between the two object naming syntaxes is explained below.

You can also learn object names in different syntaxes by looking at the following object properties:

• MappedName - The object’s fully-qualified alias (including aliases of all parent objects). This name is used by default for the object in your tests. Note that if the selected object is not in Name Mapping, this property is empty.

• Name - The object name that includes its identification properties. This is the same name you see in the Object Browser’s object tree. For an explanation of this syntax, see below.

• FullName - the object’s fully-qualified name in the syntax that includes identification properties. This name consists of the object’s Name property value and the Names of all of its parent objects. See below.

To identify objects of iOS applications, TestComplete uses specific object properties like class names and text. The full name of an object includes names of all of its parent objects, for example:

Let’s take a closer look at this notation and its components:

• Mobile - This is the Mobile object that is a root object in the hierarchy of mobile test objects.  It contains methods and properties for accessing and enumerating mobile devices to which TestComplete is connected.

• Device("iPhone John Smith") - This is the name of the Device test object that corresponds to your device. The device name is specified in parentheses as a parameter (in our example, it is iPhone John Smith. If there are several devices with the same name connected to your computer, TestComplete appends an index to the name: Device("iPhone John Smith", 2), Device("iPhone John Smith", 3) and so on.

  Important: You can skip the device name, that is, use Mobile.Device().Process… In this case, the Mobile.Device() method will correspond to the device that is defined as the current device for testing by the Mobile.SetCurrent script method or Select Device or Device Loop keyword-test operation. By using Device() with no parameters, you can create object names that do not depend on the device, and therefore, make the test easily portable between devices. See Running Tests on Multiple Devices.

• Process("MyAppName") - This is the name of the Process test object that corresponds to the application running in the iOS operating system.

• Window(0), Window(1) - These are test objects that correspond to application windows (strictly speaking, to objects of the UIWindow class). If an application displays an alert box, it will be treated as a Window text object.

  To distinguish multiple windows that exist in the application, TestComplete adds an index (0, 1, 2 and so on) to the object name.

• View(), NavigationBar(), Button("Save") - These are names of test objects that correspond to controls in the tested iOS application.

  TestComplete determines the control type (button, edit text, list view and others) and uses it to form the name. To determine the type, TestComplete analyzes the control’s class name (see below for details).

  If a control contains some read-only text, TestComplete uses this text as a parameter: Button("Save") or Label("Customer Info"). If there are several objects that have no text (or if there are several objects having the same class name and text), TestComplete includes indexes into the object name.

  If a control is a text box or has no “persistent” text, TestComplete does not use the text in the name. To distinguish the objects, it uses the control type and indexes: TextField(0), TextField(1) and so on.

How TestComplete Determines the Object Type

To determine the control type, TestComplete analyzes the control’s class name and the names of the classes that this class inherits. For example, it uses the name Button for controls of the UIButton and UIRoundedButton classes (the UIRoundedButton class is a descendant of UIButton).

Using the control types masks control implementation details and makes the naming scheme simpler and more transparent.

Note on Custom Objects

To make the object tree simpler, TestComplete hides intermediate objects. If the class name of your custom object is not in Object Mapping, your object may also be hidden. In this case, it is not displayed in the Object Browser, nor can it be selected with the Object Spy. However, you still can access it by using the methods and properties of the higher-level control. For example, you can use the TouchItem action to touch an item within the toolbar.

Default object names can be long and it can be difficult to understand to which object on the screen this or that object corresponds.

To work around these issues, you can assign custom names to objects. This is called name mapping. During name mapping, you can choose meaningful object names and also exclude non-significant intermediate objects (like Views) from the object hierarchy. You can view and modify aliases in the Name Mapping editor. For example, here is a sample hierarchy for the buttonSave object from the previous section. As you can see, the alias names are shorter and meaningful and the object tree does not contain intermediate View objects that are typically of no interest for tests:

The fully-qualified alias that can be used to refer to an object is displayed in the top right part of the Name Mapping editor (see the image above). It starts with Aliases and includes aliases of all of the object’s parent objects separated by dots (in VBScript, JScript, Python and DelphiScript projects) or square brackets (in C++Script and C#Script projects). For example, in the image above you can see that you can refer to the buttonSave object using the following name:

You can copy object aliases from the Name Mapping editor to the clipboard and use them when manually adding test operations over the tested application’s objects.

For instructions on mapping objects of iOS applications, see Mapping iOS Object Names.

For complete information on the name mapping concept, see topics of the Name Mapping section in the TestComplete help system.

Note on Mapping Device Objects

By default, the Device objects are mapped only by their type (the OSType property value); the mapping settings do not include the device name or other device-specific characteristics. The purpose of this is to create device-independent aliases. The resultant aliases help you create tests that work with any device connected to your computer. The only requirement is that your tested iOS application be running on this device. If your test works with two or more applications running on several devices concurrently, you can change the default mapping criteria and use device-specific aliases for the Device objects.