Software Quality Assurance Forums: vbScript FAQ and Useful Resources

Function foo ()
foo=7
End Function
'
'
If (iNum=foo())=False Then
'
If isEmpty(iNum) Then
msgBox "Eval1, iNum is not initialized"
else
msgBox "Eval1, iNum returned FALSE"
End If
else
msgBox "Eval1, iNum: " & iNum
End If
msgBox "after Eval1, iNum: " & iNum

If Execute("iNum=foo()")=False Then
'
If isEmpty(iNum) Then
msgBox "Eval2, iNum is not initialized"
else
msgBox "Eval2, iNum returned FALSE"
End If
End If
msgBox "after Eval2, iNum: " & iNum

Option Explicit
'
function foo(iRetControl)
'
if iRetControl=1 then
foo="abc"
else
foo=False
end if
end function
'
dim s
'
s=foo(1)
if s=False then
msgBox "foo(1) returned boolean False"
else
msgBox "foo(1) returned string: " & s
end if
'
s=foo(2)
if s=False then
msgBox "foo(2) returned boolean False"
else
msgBox "foo(2) returned string: " & s
end if

function WriteFile (sFilespec, sBuffer)
'
if sBuffer is successfully written to sFilespec then
WriteFile=True
else
WriteFile="description of failure"
end if
end function
'
'
retCode=WriteFile("c:\a\b\myfile.txt", "blah, blah")
if NOT retCode then
use the returned string to process/log the error...
ExitTest
end if
continue on with the test...

function WriteFile (sFilespec, sBuffer, bLogError)
'
if sBuffer is successfully written to sFilespec then
WriteFile=True
else
if bLogError then
Reporter.ReportEvent ...
WriteFile=False
else
WriteFile="description of failure"
end if
end if
end function
'
'
retCode=WriteFile("c:\a\b\myfile.txt", "blah, blah", True)
if retCode=False then
'error was logged by WriteFile(), exit test now
ExitTest
end if
continue on with the test...

'*************************************************************************
'
' Implements a simulated "include" capability in a vbScript,
' using ExecuteGlobal to ensure the "included" file's contents are
' available to all.
'
' from the public domain Old Dominion University website, at
' http://www.cs.odu.edu/~wild/cs477/Spring01/Examples/Script/wrox/Chapter05
'
' *************************************************************************
'
Option Explicit
'
'
' Include() vbScript sub implements a generic "include" capability
' to your scripting library environment.
'
Sub include(file)
'
Dim fso, f, str
'
Set fso = CreateObject("Scripting.FileSystemObject")
Set f = fso.OpenTextFile(file, 1)
str = f.ReadAll
f.Close

ExecuteGlobal str
End Sub
'
'
' Once the above sub is part of your main global library, you
' can then include any number of additional libs using the
' following statement.
'
include "anotherVbScriptLib.vbs"

Subject: Working with a custom vbScript Class

This post is intended for those who have wanted to investigate writing and using custom vbScript classes to supplement their QTP scripting, or perhaps more realistically, their vbScript library development.

I am not claiming to be a vbScript expert when it comes to custom classes. Rather I wish to share the information I have learned over the last several months, information I wish I could have read about in one concise thread like this when I was getting started.

-Terry Horwath

Executing the Example

Attached to this posting is a file, classExample.txt. Save this file to your disk as classExample.vbs. While this example will run, all of the good bullet proofing for error checking have been stripped—out, so that the basic elements of a custom vbScript class can more easily explored.

As currently commented, this class code only executes under the Windows Scripting Host (WSH) runtime environment on your PC. Should you care to run it under QTP--which offers no real advantage for learning purposes--you will need to make some comment changes within the sleep() method in the class definition.

After saving the attachment as described above, double-click on the file. The code at the bottom of the file is intended to allow you to interact with the custom class, myClass, and its instantiated object, myObj. When executed you should see:

1. A small IE window is displayed.
2. A msgBox with some info about the window is displayed.
3. Thereafter following the msgBox instructions to conclusion.

Now, before diving into the full source code for this class, take the time to read the following sections which attempt to grow the example from the ground up.

vbScript Class Overview

When you see a programming language that supports “class” and “object” you tend to (or at least I tend to) think of a traditional object oriented programming (OOP) environment that supports the following general characteristics:

http://en.wikipedia.org/wiki/Object-oriented_programming

But vbScript’s support for “class” and “object” is more modest in scope:

http://www.microsoft.com/mind/1199/classes/classes.asp

To summarize, the vbScript class concept:

1. Does NOT support inheritance. So it is not possible to create a Collie class which inherits characteristics from a Dog class which inherits characteristics from a Mammal class, etc.

2. Does NOT support polymorphism. Kind of a related to inheritance, where for example a Dog class will “bark” and a Pig class will “oink” when they are asked to “speak” (in a class hierarchy where they inherited the base Speak() method from the Mammal class, then override that method to implement animal unique behavior).

3. DOES support encapsulation, an OO technique which conceals how a particular class is implemented, independent from objects that use the class’s Public Properties and Methods. Another way to think about encapsulation is to say it is the ability to hide implementation details while sharing higher level behavior.

It is this author’s opinion that the lack of inheritance and polymorphism are not major shortcomings in scripting environments such as WSH and especially QTP, where you are not trying to build large complex OO programs.

Encapsulation is then the primary reason to consider using vbScript classes. And, with encapsulation comes namespace control--which permits any number of class elements to be named foo as long as each of those elements resides in a different class (i.e. a different namespace).

vbScript Class Basics

Here is the basic syntax and keywords for the vbScript Class statement:

http://www.html.dk/dokumentation/vbscript/HTML/vsstmClass.htm

Using this syntax, lets start building a new custom class:
Code:


class myClass

end class

The above class is of course useless, but none-the-less fully formed. You instantiate (fancy word for create) an object from this class using the following syntax:
Code:


dim myObj
set myObj = new myClass

Now we have a useless but fully formed object.

A Bit Less Useless Class

Now lets start adding some meat to the class. The first capabilities we explore are the built-in, but optional, methods:

Class_Initialize()
http://www.html.dk/dokumentation/vbscript/HTML/vsevtinitialize.htm

Class_Terminate()
http://www.html.dk/dokumentation/vbscript/HTML/vsevtterminate.htm

Code:


class myClass
    Private sub Class_Initialize()
        MsgBox("myObj has been created")
    End sub
‘
    Private sub Class_Terminate()
        MsgBox("myObj has been terminated/destroyed")
    End Sub
end class
‘
dim myObj
set myObj= new myClass   ‘implicitly execute Class_Initialize()
myObj = Nothing          ‘implicitly execute Class_Terminate()

Still pretty useless, but the above class and its instantiated object can be executed interactively in the WSH environment should you care to experiment.

The idea here is to place all your object initialization code statements in Class_Initialize() and all your tear-down code, such as closing windows, sessions, etc. in Class_Terminate().

Note: my evaluation of QTP’s (version 8.2) support for custom classes shows me its runtime fails to call the Class_Terminate() method when an object is implicitly destroyed when a test terminates prior to explicitly destroying the object. I consider this a bug.

Working with Class Properties

A Property is a named data variable of a class. Properties define object characteristics such as size, color, and screen location, or the state of an object, such as enabled or disabled.

At this point we add one Public and one Private Property, and the Private Property’s associated Get() and Let() methods to our class:
Code:


class myClass
    Public  iVar
    ,
    Private iWidth
    '
    Public Property Let Width(iPixels)
            iWidth=iPixels
    End Property
    '
    Public Property Get Width()
            Width=iWidth
    End Property
end class
dim myObj
set myObj= new myClass

In the above example we are using the Private and Public keywords, which while not unique to the Class statement, offer enforcement of “visibility” external to the Class. Public Class properties are visible within the Class block, as well as by code outside the Class block, but Private Class properties are visible only within the Class block.

Class Properties provide more complex support for control and access over data variables, but their syntax is similar to working with global variables:
Code:


myObj.Width= 1234            ‘write (Private) iWidth indirectly through its Let method
myWidth    = myObj.Width     ‘read  (Private) iWidth indirectly through its Get method
‘
myObj.iVar = 1234            ‘write (Public) iVar directly
myVar      = myObj.iVar      ‘read  (Public) iVar directly
‘
myObj.iWidth=1234            ‘ERROR, (Private) iWidth is hidden from the caller
myWidth     =myObj.iWidth    ‘ERROR, ditto…

First lets discuss the Public iVar class Property. It is nothing more than a glorified global variable, and its only advantage over a global variable is namespace control (i.e. in other words we could have an iVar in multiple classes without a naming collision).

Now for the much more interesting Private iWidth Property. Why have we gone to all this trouble to read and write the iWidth variable, indirectly through its associated Get and Set methods? The short answer is data encapsulation—-the iWidth variable can’t be accessed external to the class without using its Get and Let methods, but it still looks like a typical data variable to the outside world. The longer answer is hopefully explained with the extended example below, which shows error handling and bullet proofing code added to the Width Let Property:
Code:


    Public Property Let Width(iPixels)

        if NOT isNumeric(iPixels) Then
            Exit Property
        End If
        if iPixels<250 Then                 '250 min pixel width enforced by the IE Object
            iWidth=250        
        elseif iPixels > gLib.getScreenWidth/2 Then
            iWidth=gLib.getScreenWidth/2
        else
            iWidth=iPixels
        end if
    End Property

You could of course write a class method, or a global non-class function, to achieve the equivalent bullet proofing, but this use of class Get/Let Properties adds extensible error checking and data range enforcement to a seemingly simple data assignment statement.

There is another advantage to using class Get/Let Properties as well: unlike a global variable that can be altered from anywhere in your global code, the only way to write the iWidth variable in our custom object is through its Let Width() method. This provides a centralized means to determine (and when debugging, trap) when the value is modified and by who.

Note that within the class itself the Private iWidth variable can be accessed directly. This is because class code is always considered trusted. Note also that you can have a Let method without an associated Get method and visa-versa, depending on your needs.

Working with Class Methods

A class Method is nothing more than a vbScript Function or Subroutine encapsulated within a Class code block. Here again we can use the Private and Public keywords to control visibility outside of the class:
Code:


class myClass
    Public function foo (parm1, parm2)
        do some work…
        bar()
        foo=someReturnValue
    end function
    '
    Private sub bar ()
        do some work internal to this class…
    end sub
end class

In the above example the foo() method can be called from outside the class, but not the bar() subroutine. The bar() subroutine is meant to do class internal implementation work and therefore it is intentionally hidden from the world outside of the class. Here again we have another example of encapsulation in action.

Putting It All Together – Exploring the Attached Example in Detail

All of the keywords and concepts associated with a custom vbScript class have now been introduced and explained. Returning to the attached example, we will step through each line of code at the bottom of the file; which is the code intended to execute and use the custom class:

line #178 set myObj = new myClass
A new object is created from the custom class. Anywhere from a little to a lot of work gets performed in this single statement, because the Class_Initialize() method is implicitly called.

line #188 myObj.Height = 400
line #189 myObj.Width = 200
These two lines of code explicitly set the height and width of the IE window we are about to spawn. Both of these statements are optional, and override the default window size established by the Class_Initialize() method.

line #191 myObj.Open(True)
This line of code calls the required Open() class method, which does the heavy lifting to create and then invoke an IE window. This line of code demonstrates the power of encapsulation because not only is a lot of functionality implemented in this method, but the method also initializes the hidden IE object, ieObj, on line #25 used to maintain and interact with the spawned IE window (in this manner the foreground code works with the myObj object, while the class itself works with the much more complicated “Internet.Explorer” object). The Boolean value passed to this method determines if new lines of text written to window will be pre- or post-appending in the window. (It is counter-intuitive that you most often want to pre-append new lines to this type of “watch” window, so that the newest lines are always visible).

line #195 myObj.write("one" & vbCR)
line #199 myObj.write("two" & vbCR)
Well, these lines simply demonstrate writing to the just created IE Window. In real usage this would occur for the life of a test case, from any number of Actions (that have access to the myObj object), again and again, as the test progresses through its paces, occasionally writing status/progress messages to the window.

line #203 myObj.Close
The myObj object is destroyed, which internally destroys the “Internet.Explorer” object and the IE window is deleted from the PC desktop.

Digging Deeper – The Full ieWindow Class

If you haven’t had enough yet…

The attached example is a stripped-down version of my full ieWindow class, which is available on this forum—-with a terse document—-in the following post:

http://www.sqaforums.com/showthreaded.php?Cat=0&Number=348572&page=0&vc=1

Substantially more functionality and bullet-proofing is contained in this real class--in particular--code to gracefully deal with a user interactively closing the IE window.

Note that unlike the attached example, the above full ieWindow class only executes in the QTP runtime environment.

Option Explicit
'
Dim strKey, myObj, myObj2
'
Set myObj = CreateObject("Scripting.Dictionary")
Set myObj2 = myObj
'
Environment("MyDictionary") = myObj2
Environment("MyDictionary").Add "x","value X"
Environment("MyDictionary").Add "y","value Y"
'
For Each strKey In myObj.Keys
MsgBox strKey & ": " & myObj.Item(strKey)
Next
MsgBox "myObj Items Count: " & myObj.Count
'
strKey="z"
MsgBox strKey & ": " & myObj.Item(strKey)
'
MsgBox "myObj Items Count: " & myObj.Count

'Script code START ***************************
'
Dim funcptr
'
Set funcptr = getRef("foo")
funcptr
'
'Script code END *****************************
'
'lib1.vbs code START *************************
'
Sub foo ()
msgBox "in foo()"
End Sub
'
'lib1.vbs code END ***************************

'Script code START ***************************
'
Dim funcptr
'
Set funcptr = setFuncPtr("foo")
funcptr
'
Set funcptr = setFuncPtr("bar")
funcptr
'
'Script code END *****************************
'
'lib1.vbs code START *************************
'
Sub foo ()
msgBox "in foo()"
End Sub
'
function setFuncPtr(sFuncName)
set setFuncPtr = getRef(sFuncName)
end function
'
'lib1.vbs code END ***************************
'
'
'lib2.vbs code START *************************
'
Sub bar ()
msgBox "in bar()"
End Sub
'
'lib2.vbs code END ***************************