A Description Object in QTP is a collection of test object property and value pairs. Each object in the app classifies to be part of a collection. It is a very powerful approach to create object collections – each object in the collection will resemble each other by the property-value pairs specified by a description object.
Set oDesc = Description.Create
Description.Create is used to create a 0-based Properties collection object. The variable oDesc is preceded by the Set statement. Usage of Set statement binds an object as a reference to another object. Therefore, oDesc becomes an object reference to the description object represented by Description.Create. A description object does not have a stand-alone use, but coupled with the ChildObjects method, it becomes an extremely powerful approach in dealing with AUT’s objects.
Contents
ChildObjects Method
The ChildObjects method is used to create object collections using a parent object.
Set colObject = ParentObject.ChildObjects(oDesc)
The variable colObject is preceded by the Set statement, thus, just like the description object, colObject (collection object) is also an object reference. When executed, it will hold a collection of objects which have the same properties as the description object. The collection can be as small as 0 (if the properties supplied to a description object match no objects in the AUT), and as large as the total number of objects in the AUT (if no properties are supplied and a null description object is used).
To understand the principle further, we can create a description object of a window and retrieve the count of similar windows through the use of ChildObjects. Each open application Window has a common parent: the Desktop. Therefore, our need to create a parent for the collection is met. The syntax for a collection object would then be:
Set colObject = Desktop.ChildObjects(oDesc)
The above statement will create a collection object, but, we are yet to specify the properties of the description object to be able to retrieve the expected collection. Properties can be added to a description object in the following way:
Set oDesc = Description.Create
oDesc("property_1").Value = value_1
oDesc("property_2").Value = value_2
oDesc("property_n").Value = value_n
Therefore, to create a collection of all windows, our description object would become:
Set oDesc = Description.Create
oDesc("micclass").Value = "Window"
'colObject holds all open Windows on the Desktop
Set colObject = Desktop.ChildObjects(oDesc)
Parent Object (Browser/Window) Collection
To create an object description for a parent, we will simply use the “Class” of the parent object and add the property-value combination:
Dim oDesc 'Description Object Dim colObject 'Object Collection Set oDesc = Description.Create 'Remember to always use 'micclass' and not 'class name' oDesc( "micclass" ).value = "Browser" 'We used Desktop as the parent here because, the Desktop Object holds all the Windows Set colObject = Desktop.ChildObjects( oDesc )
When the above snippet execute, colObject will contain a collection of all browsers visible on the desktop.
Since we have done this, how will we know how many browser objects exist on the desktop through code? Also, how will we retrieve their information? The answer is quite simple: colObject contains the necessary information and methods we can use to perform events on our target objects.
'Retrieve # of open browsers
MsgBox colObject.Count
'Retrieve Titles of all open browsers
For x = 0 to colObject.Count - 1
MsgBox colObject(x).GetROProperty("title")
Next
As I mentioned above, colObject is nothing but an array of all objects having the exact same properties as the description object. Therefore, colObject(0) points to the first object in the collection, colObject(1) points to the second object in the collection, and so on. This is demonstrated in the For..Next loop in the snippet above.
Object contained in a Browser/Window
Using the same approach above, we will retrieve collection of all Link objects on a page. Notice here that instead of Desktop, we have used the entire Browser-Page hierarchy. This is because, a link object is present somewhere inside the Page, instead of the desktop :).
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
'Using the entire Browser-Page hierarchy
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
By executing the snippet above, we will use colObject to perform some events on these objects. Let’s retrieve the number of link objects present in our browser:
'Returns 30 MsgBox colObject.Count
The above example is created for the Google page, and if you want to test it for some other browser, do not forget to change the Browser and Page titles to the correct values.
Object contained in a Browser/Window Using Multiple Properties
If you saw the above example, we created a description object using only the class of the Link object. Now, we will retrieve a more specific object collection. We are going to specify an additional property and narrow down the search results- this is because, even though there can be multiple Link objects on a page, it’s not necessary that there would be the same number of objects with the text “Hello, I am a Link!”.
This approach helps us retrieve only the objects that we really want for our automation, since having a collection of all objects can be quite cumbersome to work with. Also, if we provide relevant information to our Description Object, QTP will return a narrowed-down collection, which is the easiest to work with. This is similar to how you search Google. If you specify “QTP” in Google Search, you will have a huge array of search results. You can narrow down the search results (and find information faster) if you add “QTP + Browser + DP” instead.
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
'Additional property- for more focused and controlled collection
oDesc( "text" ).value = "Images"
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
Msgbox colObject.Count 'Returns 1
Now, colObject will only contain the Link objects that have the text: Images. Also, if you notice Google page, there is only one link with the Images text. This is a good example of finding the target object dynamically. Suppose, if there were 2 links on the page instead, we would have both of them in our collection colObject. Let’s highlight our found object:
colObject(0).Highlight
Executing the statement above, we will highlight the first object in the collection. I know there is only one object in the collection, but we can make sure by doing this:
For x = 0 to colObject.Count - 1
colObject(x).Highlight
Next
WildCards
If we have dynamic objects in our application, then we may not always have the luxury to feed their properties as we have done in the example above. Sometimes, we would need to create dynamic descriptions and retrieve our target objects from resulting (dynamic) collections. I say dynamic collections because at one time, your collection may hold 9 objects, whereas during the next session, it may hold 10.
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "text" ).value = "I.*age.*"
'Images'.regularExpression is 'True' by default
oDesc( "text" ).regularExpression = True
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
After executing the snippet above, we will have a collection object with all objects that match the regular expression. Let’s see the count of the objects:
'Returns 1 because our supplied pattern only matches with the word: Images MsgBox colObject.Count
Let’s replace the “text” with “ma” instead and see if we still retrieve a collection with a single object:
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "text" ).value = ".*ma.*"
'Images'.regularExpression is 'True' by default
oDesc( "text" ).regularExpression = True
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
To see what has changed, let’s execute the following:
'Will return 4 MsgBox colObject.Count
If you do execute the snippet above, the count would be 4. Why is that? To see the new objects in our collection, let’s do this:
For x = 0 to colObject.Count - 1
MsgBox "x:" & x & " || " & colObject(x).GetROProperty("innertext")
Next
Negating WildCards
Sometimes we have an object description with wildcards in it. Here, we want to turn off the Description Object’s ability to register the description as a regular expression. This is quite simple, and we do it by turning regular expression as False:
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "text" ).value = ".*ma.*" 'Images
oDesc( "text" ).regularExpression = False
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
MsgBox colObject.Count 'Returns 0
Now, the above snippet will not identify Images or Maps. Instead, it will only identify objects that have the exact text .*ma.* which really doesn’t exist anywhere on the Google homepage.
Integer-Types
So far, we have only learned various ways to work with description objects using Strings. Here, we will see how they transform into integer-types. Let’s bring up the properties of the Images link again using the Object spy and feed its “x” coordinate to see whether we can find the link:
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "x" ).value = 51 '51, not "51".
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
'Will return 1
MsgBox colObject.Count
'Will return Images
For x = 0 to colObject.Count - 1
MsgBox colObject(x).GetROProperty("innertext")
Next
Notice that 51 above is not within quotation marks. This should always be the case. Notice when we replace it with a string-type below:
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "x" ).value = "51"
Set colObject = Browser( "title:=Google").Page("title:=Google").ChildObjects( oDesc )
MsgBox colObject.Count
For x = 0 to colObject.Count - 1
MsgBox colObject(x).GetROProperty("innertext")
Next
The collection is an empty one:
So, always remember to treat integers as they are. This always holds true for x, y, abs_x, abs_y.
Building Object hierarchy with ChildObjects
We will use the Browser Object Collection to set a value in a text box to demonstrate this:
Dim oDesc 'Description Object
Dim colObject 'Object Collection
Set oDesc = Description.Create
oDesc( "micclass" ).value = "Browser"
oDesc( "title" ).value = "Google"
'Notice we used the Desktop Object again for retrieving Window collection
Set colObject = Desktop.ChildObjects( oDesc )
'Retrieve the count
iCount = colObject.Count
'Set value in the WebEdit of the last Window object in the collection
For x = 0 to iCount - 1
'Verify if the Browser title equals "Google"
If Browser("creationtime:=" & x).GetROProperty("title") = "Google" Then
'Set Description.Create in the search TextBox
Browser("creationtime:="&x).Page("micclass:=Page").WebEdit("name:=q").Set "Description.Create"
End If
Next
When the above snippet executes, we will have the following value set in the Search TextBox in Google HomePage.