How to use classes in QTP revisited

Classes in QTP are a bit tricky if you want to use them for the first time. You have to know and understand the principle that a class got local scope for the QTP Function Library (.qfl file) it is in, and that if you want to use it in another library, you’ll have to create a constructor (I have shown this before, but I’ll do it again):


' Constructor:
Public Function [new CustomClass]()
     Set [new CustomClass] = new cls_CustomClass
End Function

' Class definition:
Class cls_CustomClass
     Private Sub Class_Initialize()
         Print "Custom Class: I am created!"
     End Sub
End Class

' using the object in another library:
Dim myClass
Set myClass = [new CustomClass]

This seems like a drawback, but it creates a great possibility. Normally, it is not possible to pass initialisation parameters into a new class, because Class_Initialize does not accept parameters. But using the constructor function, we can!

Option Explicit

' Make a private variable that we can pass into the class
Private PARAMETER_ARRAY

' Create a function that returns the requested class. Accepts
' a parameter array. Note: Do not use paramArray, it is reserved!
Public Function [new customClass](ByVal parameterArray)

     PARAMETER_ARRAY = parameterArray

     ' Return a clsCustomClass object
     Set [new CustomClass] = new cls_CustomClass

End Function

' Create the custom class. Classes are always declared Private in QTP
Class cls_CustomClass

     ' The sub Class_Initialize is used to initialize the object with the
     ' parameters passed into the constructor
     Private Sub Class_Initialize()
         ' Do something with the parameters
         Print join(PARAMETER_ARRAY, vbNewLine)
     End Sub

End Class

' Test code
Dim myClass
Set myClass = [new customClass](array("first parameter", "second parameter", "etc."))

Notice what we just did: We created a Private variable, that can only be used by CustomClass classes. So with the use of Private variables with local scope to the library where you put the class in, you create a static variable for the class!
A static variable in this context is a variable that keeps its value and can be used over multiple objects of the same class:

' Declaring the static variables
Private INSTANCE_COUNTER : INSTANCE_COUNTER = 0

' Constructor:
Public Function [new CustomClass]()
     Set [new CustomClass] = new cls_CustomClass
End Function

' Class definition:
Class cls_CustomClass
     Private Sub Class_Initialize()
         Print "I am created and I have " & INSTANCE_COUNTER & " sister(s)."
         INSTANCE_COUNTER = INSTANCE_COUNTER + 1
     End Sub

     Private Sub Class_Terminate()
         INSTANCE_COUNTER = INSTANCE_COUNTER – 1
     End Sub
End Class

' using the object in another library:
Dim a, b, c
Set a = [new CustomClass]
Set b = [new CustomClass]
Set c = [new CustomClass]

Results in:
I am created and I have 0 sister(s).
I am created and I have 1 sister(s).
I am created and I have 2 sister(s).

By using the static variable as a reference for the object itself, we can create a singleton object. A singleton is an object whereof only one instance at a time can exist. In object oriented languages, singletons are normally used for large objects, or objects that will go bad if multiple instances exists like deadlocks or instability.

Option explicit

Private SINGLETON : Set SINGLETON = Nothing

Public function [new Singleton]()
     If SINGLETON Is Nothing Then
         set SINGLETON = new cls_Singleton
     End If

     Set [new Singleton] = SINGLETON
End Function

Class cls_Singleton

     Private Sub Class_Initialize
         Print "I am unique!"
     End Sub

End Class

Dim st1, st2, st3
Set st1 = [new Singleton]
Set st2 = [new Singleton]
Set st3 = [new Singleton]

Results in only one:
I am unique!

There is a drawback: Once a singleton object is created this way, it is not possible to destroy it without the use of some code violating the object oriented principle.

QTP variable name conventions

When you start with a new test automation project, your code is conveniently arranged and you still have a clear overview over the locations and naming of variables and functions. But later on it will become a disaster if you don’t manage it a little bit.
That is why I wrote a name convention article. It is not an official how-you-should-do-it document, it is just the way I do things and written from experience.

' Public and Private constants in capitals
Public Const MOUSEEVENTTF _MOVE = 1
Private Const APPLICATION_MAIN_WINDOW = "name:=My Application"

' Functions, Subs and local variables in lowerCamelCase
Public Function myCustomFunction(thisVariable, thatVariable)

     ' Variables with a known type can be declared with the type abbreviation in front of it
     Dim arrStaticArry(5), objFile, intCounter, blnReadOnly

     ' Variables with a unknown type are declared without a type abbreviation, This is also applicable for variables used in self commentary code.
     Dim customContainer, fileWasFound

     ' Consts with local scope are declared with the same format as variables
     Const cannotBeChanged = True

End Function

' Classes in UpperCamelCase. In QTP I use the cls_ tag in front of it for reasons explained later.
Class cls_EventListener

     ' Public variables are in UpperCamelCase too
     Public BufferLength

     ' Private variables with class scope are lowerCamelCase with an underscore behind it
     Private updateCounter_, eventNumber_

     ' Properties, Subs and Functions (public and private) are all in UpperCamelCase
     Public Property Get EventNumber()
         EventNumber = eventNumber_
     End Property
End Class

In QTP, a class gets a local scope. To make it global, you have to add a function returning that class. As a side effect, this gives you the opportunity to initialize the class. Of course you have to add an init method to your class if you do it this way.

Public Function [new EventListener](initializationParameters)
     Set [new EventListener] = new cls_EventListener
     [new EventListener].Init(initializationParameters)
End Function

Now, you can set a new class with the following code in another library:
Set EventListener = [new EventListener]("codebase:=Unicode")

Side note: The square brackets around a variable lets you enter every character for a variable, including spaces, special characters etc. If you find that inconvenient, you can use an underscore: new_EventListener to mimic normal VB functionality.
I use the square brackets when I want to express importance for example:

' Call the main routine of this script:
[___ !MAIN! ___]

' Or to enjoy my co workers (and to see if they ever peer review my code):
Dim [ O\-<>-/O ], [ ¿Que? ]

A few ways to use arrays

When you first encounter Arrays in QTP it is not very easy to understand quickly. VBScript makes use of a few types of arrays: Static, Dynamic, Assigned to a normal variable and Dictionary objects (the dictionary object is not discussed in this article.). Static and Dynamic arrays can be one dimensional or multidimensional.

First the simple static array. Static because it can only contain a fixed amount of items; Simple because we only put strings in it referred by the indexnumber (or subscript) of the array:

' Simple static array
Dim weekdays(6)

weekdays(0) = "Mon"
weekdays(1) = "Tue"
weekdays(2) = "Wed"
weekdays(3) = "Thu"
weekdays(4) = "Fri"
weekdays(5) = "Sat"
weekdays(6) = "Sun"

When you don't have plans to use the subscript, you can also create the array directly. And yes, it works the same with index numbers as with the weekdays array, but it is good programming practice to use the former method if you want to call the array items by subscript number.

' Simple assigned array
Dim workdays
workdays = array("Mon", "Wed", "Thu", "Fri")

As you can see, the variable does not have to be declared as an array, so theoretically every variable can be set as an array just as every variable can be set as an object. Although, with arrays you don't need the set statement.

Sometimes it is more convenient to dynamically increase and decrease the array size. Then you have to create a dynamic array. This is an array declared the same way as in the simple static array, but without the number of elements, just empty parenthesis: dim myArray()
To set the amount of array items, you have to use ReDim like ReDim myArray(n) where n is the amount of items you want to use +1 (The first subscript is always 0). Other then in a static array declaration (like Dim myArray(5)), the number of subscripts in a ReDim statement can be a variable or constant.
Whenever you use ReDim, the array is reïnitialized, except when you use the Preserve command, indicating you want to reuse the already set values:

' Simple dynamic assigment of an array
Dim myPets()
ReDim myPets(2)
myPets(0) = "Dog"
myPets(1) = "Cat"
myPets(2) = "Hippopotamus"

ReDim Preserve myPets(3)
myPets(3) = "Rabbit"

msgbox "My pets: " & join(myPets, ", ")

The join(array[, separation character(s)]) function lets you easily merge an array to a string.
Another trick is to use join to make an html table easily:
newTableRow = "" & join(arrElements, "") & ""

Multidimensional arrays
A multidimensional array is used to store data or objects in a matrix. You can create virtually create as much dimensions if you want (not really unlimited of course, but keep in mind this good rule with programming: If you have to ask what the limit is for some kind of instance, probably there is something wrong with your design)

' Multidimensional static array, the next code is pure and alone for demonstration purposes
' it is not optimised, maybe even not correct and there are better ways to achieve this
Dim bcCalendar(2100, 12, 31)
Dim dayCounter, maxDay, cYear, cMonth, cDay
dayCounter = 6

For cYear = 0 to 2100
    For cMonth = 1 to 12
        Select Case cMonth
            Case 1,3,5,7,8,10,12    maxDay = 31
            Case 4,6,9,11           maxDay = 30
            Case 2                  maxDay = 28 + abs((cYear mod 400 = 0) or ((cYear mod 4 = 0) and not (cYear mod 100 = 0)))
        End Select

        For cDay = 1 to maxDay
            bcCalendar(cYear, cMonth, cDay) = weekday((dayCounter mod 7)+1)
            dayCounter = dayCounter + 1
        Next
    Next
Next

msgbox "Charles Darwin was born on a " & WeekdayName(bcCalendar(1809, 2, 12))


Passing arrays
Arrays are passed the same way as variables are:

Default: By Reference
With ByRef in the function declaration: By Reference
With ByVal in the function declaration: By Value
With parenthesis around the argument in the function call: always By Value (ByRef in the function declaration is omitted)

Arrays filled with objects
Arrays do not only have to contain variables, they can also contain objects, which is great to make a collection of QTP gui objects, dictionaries, but also class objects to create child classes under a parent.
Arrays can even contain other arrays. This is useful if you want to create a fully dynamic multidimensional array. (Normally, in a multidimensional array, only the last item is expandable with a redim preserve statement.)