QTP: Understanding the Description Object (Description.Create)

photo credit: SideLong

Introduction

In this article, we will cover the basics of Description Object and the ChildObjects method. This is a very powerful approach to creating robust automation test suites. It is also a very important principle of Descriptive Programming in QTP.

We will see how we can create an object description with a single property, with multiple properties, by using regular expressions and finally putting all these concepts into their application with the ChildObjects method.

Before we see how it is done, we must first understand the following statement:

Set oDesc = Description.Create

Above, we are using the variable oDesc to create a description of something. Since, oDesc is preceeded by a Set statement, it must be an object reference. Therefore, when the above statement executes, oDesc will become an object reference to a description object. We will use the description object with the ChildObjects method to retrieve object collections. These object collections are nothing but arrays of objects with the exact properties of the description object.

If you are starting with DP, please read the article on Descriptive Programming Concepts on Relevant Codes for a quick walk-through on Descriptive Programming before continuing with this article.

Creating a Description Object for a Parent (Browser/Window)

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.

But, 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.

Creating a Description Object for an 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.

Creating a Description Object for an 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, its 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

Creating a Description Object using 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 )

You may want to read the article on Regular Expressions to better understand how these work in Descriptive Programming.

After executing the snippet above, we will have a collection object with all object 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:

Dim oDesc        'Description Object
Dim colObject    'Object Collection

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

Below are our outputs:

Interesting, isn’t it? Our description for the text property matched all links that had the letters ma in them.

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.

Creating a Description Object for 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:

Object Spy Snapshot: Images Link (Google)

Dim oDesc        'Description Object
Dim colObject    'Object Collection

Set oDesc = Description.Create
oDesc( "micclass" ).value = "Link"
oDesc( "x" ).value = 51             'It should always be 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:

(Mis)Using Integers as Strings

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:

Using Description.Create to Set Value

I hope this article will help you guys understand the concepts of one of the most important concepts in Descriptive Programming: the Description Object. Thanks for visiting Relevant Codes :)

Tagged as: ChildObjects, Description Object, Description.Create, DP, QTP, QTP Description Object, QTP Description.Create, Set oDesc, Set oDesc = Description.Create