Addressing Objects in AIR Applications

Applies to TestComplete 14.80, last modified on April 13, 2021

The information in this topic applies to web tests that locate web objects by using internal identification properties provided by TestComplete and run in local environments.

There are several ways to refer to objects in AIR applications. If you use Name Mapping in your test project, you can refer to application objects using their names specified in Name Mapping. For objects not in Name Mapping, you can use the naming syntax that directly includes identification properties and values of these objects. This topic explains both approaches.

About Object Names in the Object Browser

You can explore the object structure of the tested application in the Object Browser. Here is a sample view of the AIR application hierarchy displayed in the Object Browser:

A view of an AIR application in the object tree

Click the image to enlarge it.

Here, the Process("Orders") branch of the Sys object corresponds to your tested AIR application and further objects correspond to the application’s windows, controls and objects.

To refer to an individual object in a tested AIR application, select the needed object in the Object Browser or Object Spy. These tools display the selected object’s name above the member list. From the right-click menu, you can copy this name to the clipboard and then insert it into your test.

Copying the object name from the Object Browser

You may notice that this name is 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 differences between the two object naming syntaxes are explained in the Addressing AIR Objects Using Name Mapping and Aliases and Addressing AIR Objects Without Name Mapping sections 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 for the object by default 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.

Addressing AIR Objects Using Name Mapping and Aliases

By default, TestComplete uses object names from Name Mapping (the object repository) to refer to individual objects in AIR applications under test. These names are called aliases. When you record a test, TestComplete automatically adds recorded objects to Name Mapping and generates aliases for them.

You can see available object aliases and add new aliases in the Name Mapping editor.

Sample Name Mapping for an AIR application

Here, Mapped Objects and Aliases display the hierarchy of mapped objects and their aliases, respectively. The fully-qualified alias that can be used to refer to an object is displayed in the top right 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 buttonNewOrder object using the following name:

JavaScript, JScript

Aliases.Orders.wndOrders.buttonNewOrder

Python

Aliases.Orders.wndOrders.buttonNewOrder

VBScript

Aliases.Orders.wndOrders.buttonNewOrder

DelphiScript

Aliases.Orders.wndOrders.buttonNewOrder

C++Script, C#Script

Aliases["Orders"]["wndOrders"]["buttonNewOrder"]

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

The following example shows a sample click on the buttonNewOrder button specified by an alias:

A keyword test operation over an AIR object addressed using its alias
Note: For simplicity, keyword tests do not display the Aliases identifier at the beginning of object aliases.

Also, keyword tests may not display intermediate objects in the application’s object hierarchy. To view the full name of an operation’s target object, double-click the operation or increase the Maximum depth option in Keyword Test Editor - Groups options.

JavaScript, JScript

Aliases.Orders.wndOrders.buttonNewOrder.ClickButton();

Python

Aliases.Orders.wndOrders.buttonNewOrder.ClickButton();

VBScript

Call Aliases.Orders.wndOrders.buttonNewOrder.ClickButton

DelphiScript

Aliases.Orders.wndOrders.buttonNewOrder.ClickButton();

C++Script, C#Script

Aliases["Orders"]["wndOrders"]["buttonNewOrder"]["ClickButton"]();

Note that the fully-qualified mapped name for this object is as follows:

JavaScript, JScript

NameMapping.Sys.Orders.wndOrders.ordersOrders0.buttonbarButtonbar11.buttonNewOrder

Python

NameMapping.Sys.Orders.wndOrders.ordersOrders0.buttonbarButtonbar11.buttonNewOrder

VBScript

NameMapping.Sys.Orders.wndOrders.ordersOrders0.buttonbarButtonbar11.buttonNewOrder

DelphiScript

NameMapping.Sys.Orders.wndOrders.ordersOrders0.buttonbarButtonbar11.buttonNewOrder

C++Script, C#Script

NameMapping["Sys"]["Orders"]["wndOrders"]["ordersOrders0"]["buttonbarButtonbar11"]["buttonNewOrder"]

Since ordersOrders0 and buttonbarButtonbar11 objects are of no interest for our test, we exclude them from the path to the buttonNewOrder object in the Alias tree, so the object hierarchy becomes shorter. Using aliases lets you make your scripts shorter and more readable.

For more information about using Name Mapping and aliases, see Name Mapping and Access Objects by Aliases.

Addressing AIR Objects Without Name Mapping

Your tests can work not only with applications and objects added to Name Mapping, but also with any other running applications, their windows and controls. These objects can be addressed using a syntax that directly includes identification property values.

The following sections describe how you can address objects in Flex-based AIR applications and HTML-based AIR applications:

Addressing Objects in Flex-based AIR Applications

Addressing Objects in HTML-Based AIR Applications

Addressing Objects in Flex-based AIR Applications

Consider the following sample code and keyword test that illustrate how you can refer to an object in your Flex-based AIR application:

A keyword test operation over a Flex-based AIR object that is not in Name Mapping

JavaScript, JScript

Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton();

Python

Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton();

VBScript

Call Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton

DelphiScript

Sys.Process('Orders').Window('ApolloRuntimeContentWindow', 'Orders', 1).Orders(0).ButtonBar(0).ButtonBarButton('New Order').ClickButton();

C++Script, C#Script

Sys["Process"]("Orders")["Window"]("ApolloRuntimeContentWindow", "Orders", 1)["Orders"](0)["ButtonBar"](0)["ButtonBarButton"]("New Order")["ClickButton"]();

To learn the exact syntax for referring to a particular object, use the Object Browser - the object tree and the FullName property of objects always use this naming syntax. See the About Object Names in the Object Browser section above.

Let’s have a closer look at this notation and its components.

  • The notation starts with the Sys object that represents the operating system.

  • The next object, Process("Orders"), represents the AIR application. The name of the process corresponds to the name of the application’s executable file.
  • The next object, Window("ApolloRuntimeContentWindow", "Orders", 1), is the hosting window for the AIR application.

  • Further objects represent top-level visual containers and visual objects in the AIR application. In Flex-based AIR applications the syntax for the objects representing controls is as follows:

    ObjectType(ObjectIdentifier)

    Here, ObjectType is the object class name specified by the object’s FlexObject.className property. ObjectIdentifier is the object name (value of the ObjectIdentifier property). This name is specified by the object’s native properties in the following way:

    • TestComplete tries to address Flex-based AIR objects by the value specified in the native FlexObject.id property.
    • If TestComplete does not find any value in the FlexObject.id property, the object is addressed in tests by the native FlexObject.name property.
    • If the name of an AIR object is not specified in the application (or if it is generated automatically), TestComplete tries to address such an object by its FlexObject.label.
    • If TestComplete does not find any value in the label, name and id object properties, the object is addressed in tests by the object type name and index among other objects of the same type that are located on the same hierarchy level (for instance, CheckBox(0)).

For examples of this syntax applied to objects in your tested AIR application, examine your application in the Object Browser. You can also copy this syntax from the Object Browser and paste it to your test to avoid having to type it manually.

Addressing Objects in HTML-based AIR Applications

Consider the following sample code and keyword test that illustrate how you can refer to an object in your HTML-based AIR application:

A keyword test operation over an HTML-based AIR object that is not in Name Mapping

JavaScript, JScript

Sys.Process("MainHTML").Window("ApolloRuntimeContentWindow", "WebTest Sample Page", 1).Button("MultiSelect").ClickButton();

Python

Sys.Process("MainHTML").Window("ApolloRuntimeContentWindow", "WebTest Sample Page", 1).Button("MultiSelect").ClickButton();

VBScript

Call Sys.Process("MainHTML").Window("ApolloRuntimeContentWindow", "WebTest Sample Page", 1).Button("MultiSelect").ClickButton

DelphiScript

Sys.Process('MainHTML').Window('ApolloRuntimeContentWindow', 'WebTest Sample Page', 1).Button('MultiSelect').ClickButton();

C++Script, C#Script

Sys["Process"]("MainHTML")["Window"]("ApolloRuntimeContentWindow", "WebTest Sample Page", 1)["Button"]("MultiSelect")["ClickButton"]();

To learn the exact syntax for referring to a particular object, use the Object Browser - the object tree and the FullName property of objects always use this naming syntax. See the About Object Names in the Object Browser section above.

Let’s have a closer look at this notation and its components.

  • The notation starts with the Sys object that represents the operating system.

  • The next object, Process("MainHTML"), represents the AIR application. The name of the process corresponds to the name of the application’s executable file.
  • The next object, Window("ApolloRuntimeContentWindow", "WebTest Sample Page", 1), is the hosting window for the AIR application.

  • Further objects represent visual objects in the AIR application. In HTML-based AIR applications the syntax for the objects representing controls is as follows:

    ObjectType(ObjectIdentifier)

    Here, ObjectType is the tagName attribute of the HTML element. If tagName is equal to INPUT, ObjectType is the type attribute of the HTML element. ObjectIdentifier is the id attribute of the HTML element.

    If the Id attribute is not specified for the element, ObjectIdentifier is the sequential position of the element among its siblings with the same ObjectType within the parent element. The index is zero-based, that is the first child element has the index of 0, the second is 1 and so on.

For examples of this syntax applied to objects in your tested AIR application, examine your application in the Object Browser. You can also copy this syntax from the Object Browser and paste it to your test to avoid having to type it manually.

Combining Mapped and Unmapped Object Names

You can combine aliases specified in Name Mapping and the ObjectType(ObjectIdentifier) notation when referencing an object hierarchy in tests. For example, you can use aliases for parent objects and the ObjectType(ObjectIdentifier) notation for child objects:

JavaScript, JScript

Aliases.Orders.wndOrders.Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton();

Python

Aliases.Orders.wndOrders.Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton();

VBScript

Aliases.Orders.wndOrders.Orders(0).ButtonBar(0).ButtonBarButton("New Order").ClickButton

DelphiScript

Aliases.Orders.wndOrders.Orders(0).ButtonBar(0).ButtonBarButton('New Order').ClickButton();

C++Script, C#Script

Aliases["Orders"]["wndOrders"]["Orders"](0)["ButtonBar"](0)["ButtonBarButton"]("New Order")["ClickButton"]();

However, keep in mind that aliases must always precede the ObjectType(ObjectIdentifier) notation in the object hierarchy. Aliases cannot be used after the ObjectType(ObjectIdentifier) notation within the same statement. That is, the following statement is invalid:

JavaScript, JScript

Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).buttonbarButtonbar11.buttonNewOrder.ClickButton();

Python

Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).buttonbarButtonbar11.buttonNewOrder.ClickButton();

VBScript

Sys.Process("Orders").Window("ApolloRuntimeContentWindow", "Orders", 1).Orders(0).buttonbarButtonbar11.buttonNewOrder.ClickButton

DelphiScript

Sys.Process('Orders').Window('ApolloRuntimeContentWindow', 'Orders', 1).Orders(0).buttonbarButtonbar11.buttonNewOrder.ClickButton();

C++Script, C#Script

Sys["Process"]("Orders")["Window"]("ApolloRuntimeContentWindow", "Orders", 1)["Orders"](0)["buttonbarButtonbar11"]["buttonNewOrder"]["ClickButton"]();

See Also

Testing AIR Applications
Testing AIR Applications - Overview
Support for AIR Applications' Controls
Accessing Native Properties and Methods of AIR Objects

Highlight search results