Advanced UFT 12 for Test Engineers Cookbook

Perform the following steps to create the DataTable parameter LocalParam1 for the local sheet:

If we open the Default.xls file in the test folder (which, as its name suggests, is the default data source for a new test), we will notice that there are two worksheets, namely, Global and Action1. In each of these, the first row holds the name of the parameters, so we will see GlobalParam1 in the Global worksheet and LocalParam1 in the Action1 worksheet. You will also notice that the used rows have borders at the bottom of the worksheet (the borders have no real function; UFT identifies the used range by the number of used rows and columns based on the content range).

For information about setting and retrieving values for a DataTable parameter, refer to the next two recipes, Retrieving data from a DataTable and Storing data in a DataTable.

Prior to getting started with this recipe, please ensure that you have followed the Creating a DataTable parameter recipe.

We will retrieve the value of a DataTable parameter, namely, LocalParam1, from the Action1 local sheet with the following code written in the code editor inside Action1:

Dim MyLocalParam

MyLocalParam = DataTable.Value("LocalParam1", dtLocalSheet)
Print MyLocalParam

Similarly, the following code snippet shows how to retrieve the value of a DataTable parameter from the test global sheet:

Dim MyGlobalParam
MyGlobalParam = DataTable("GlobalParam1", dtGlobalSheet) 
'We can omit the explicit .Value property as given above since it is the default property 
Print MyGlobalParam
MyGlobalParam = DataTable("GlobalParam1")  
'We can omit the second parameter as given above (dtGlobalSheet) since the Global sheet is the default
Print MyGlobalParam 

The result of this code in UFT's console is as follows:

Of course, we need to ensure beforehand that the parameter exists in the DataTable class as outlined in the previous Creating a DataTable parameter recipe.

By using the DataTable.Value property we are referring to the column by the parameter name in the underlying Excel worksheet (be it global or local):

MyLocalParam = DataTable.Value("LocalParam1", dtLocalSheet)
MyGlobalParam = DataTable("GlobalParam1", dtGlobalSheet)

As we entered just a single value into the datasheet, the command retrieves just the value in the first row. If multiple values were entered and action iterations were set to run on all rows, then it would have retrieved the values from each row with each iteration.

Proceed with the following steps:

When we run the test, UFT first executes Action1, and a new parameter named CustomerID will be added to GlobalSheet (a property of the DataTable object that refers to the GlobalSheet object) with the value given by the second parameter.

DataTable.GlobalSheet.AddParameter "CustomerID", "990011234"

We then immediately assign a variable with the retrieved value and print it to the console (for illustration purposes, we also concatenate the current action's name from the Environment object's built-in variables).

CustomerID = DataTable("CustomerID")
Print Environment("ActionName") & ": " & CustomerID

Next, UFT executes Action2 same as Action1.

There are other alternative ways of keeping and sharing data during a run session. The simplest is by using public variables declared in a function library attached to the test. The disadvantage of this approach is that these variables must be declared in advance and they are hard coded, but the nature of automation often demands more flexibility to manage such data.

For information on advanced methods to share data among sessions, refer to the Using a global dictionary for fast shared data access recipe.

Ensure that a new test is open and create a new action. Ensure that an external Excel sheet exists with one global worksheet and worksheets named after each action in the test. The Excel sheet will contain three worksheets, namely, Global, Action1, and Action2. The Action2 worksheet will contain data shown in the following screenshot. In our example, we will use the Excel sheet named MyDynamicallyLoadedExcel.xls, and to simplify matters, we will put it under the same test folder (it should be placed in a separate shared folder):

In the Flow pane, make sure that the Action Call properties are set to Run on all rows.

In order to load the MyDynamicallyLoadedExcel.xls file to the test, perform the following steps:

In Action1, the DataTable.Import method replaces Default.xls with the target Excel file. The code in Action2 retrieves and prints the values for each parameter, and as the action was set to Run on all rows, the code repeats this for all rows with data.

To import just a worksheet for an action, use the DataTable.ImportSheet method as follows:

DataTable.ImportSheet("MyDynamicallyLoadedExcel.xls", "Action1", "Action1")  

Here, the first parameter is the Excel filename and the last two are the source datasheet and target datasheet respectively.

For information on saving values collected during a run session, refer to the next recipe, Exporting a DataTable.

To save the DataTable in its current state before the run session ends, we will use the DataTable.Export method, which takes the path and name of an Excel file as an argument. There are two options to save the data table:

The preceding statement saves the current contents of the DataTable (all worksheets) to a new Excel file (if not existent, otherwise it is overwritten). The statement Environment("TestDir") returns a string with the path of the current test to which a string with the name of the file we wish to create is concatenated (TestDir is one of the built-in Environment variables covered in detail later in this chapter).

To export just a single worksheet (in our example, the global sheet) for an action, use the DataTable.ExportSheet method, as follows:

call DataTable.ExportSheet(Environment("TestDir") & "\MyDynamicallySavedSheet1.xls", "Global")

Here, the first parameter is the Excel filename and the second is the source datasheet. The target datasheet will take the same name as the source.

In this recipe, we will take the Google+ Sign In button, which carries a different text value for each localized version. In our example, we will learn about the button in one language (Afrikaans), store the TO in a single Object Repository (OR), and make it get the value for its name attribute from an Environment variable named Google_Sign_In. The Environment variables for the test will be loaded according to the application language (refer to the Using global variables (Environment) recipe in Chapter 8, Utility and Reserved Objects).

Proceed with the following steps:

When running the test, OR will take the value of the name property from the Environment variable. Hence, if we have a set of such values for each language, then we will be able to test an application in whichever language we choose, without having to change a single line of script code!

The same basic approach can be used for object identification with the Using Descriptive Programming inline recipe of Chapter 5, Object Identification.

The Importing an Excel file to a test and Using a configuration file to manage test environments recipes.

Ensure that you have the Flight Reservation sample application shipped with the installed UFT. You can check this by navigating to Start | All Programs | HP Software | Unified Functional Testing | Sample Applications. You should have a shortcut named Flight GUI that launches flight4a.exe. Create a new test by navigating to File | New | Test from the menu, or by using the Ctrl + N keyboard shortcut. Rename Action1 to FR_Login (optional).

Proceed with the following steps:

Now, we will explain the flow of the FR_Login action and the local functions.

We declare the variables that we need for the Login operation, namely, AgentName, Password, and Button. We then initialize them by retrieving their values from the local sheet in the DataTable. The button value is parameterized to enable further elaboration of the code to incorporate the cases of clicking on the Cancel and Help buttons.

Next, we call the openApp() function and check the returned value. If it is False, then the Flight Reservation application did not open, and therefore we exit the test.

We attempt to log in and pass the AgentName, Password, and Button parameters to the function. If it returns true, then login was successful and the else block of code is executed where we call the verifyMainWndInitialState() function to assert that the main window opened as expected.

If the login did not succeed, we check the first message with a checkpoint that compares the actual text with the text recorded in the DataTable, which is correct in the context of the planned flow.

If the first message check passes, then we check to see if there is another message. Of course, we could have used a counter for the actual password failures to see if the second message is shown exactly by the fourth attempt. However, as we set the input data, the flow is planned such that it must appear at the right time. This is the true sense of defining test cases with input data. If a message appears, then the checkMessage(id) function closes the message box. We then check if the login dialog box is closed with the code If not Dialog("Login").Exist(0) Then, and it then calls openApp() to begin again for the last iteration.

In the last iteration, with the input data on the seventh row (refer to the table in the previous section), the script performs a successful login, and then calls the function verifyMainWndInitialState(), as mentioned in the previous section.

Proceed with the following steps:

What does it mean? A user-defined variable is Internal when we define it through the UFT GUI. It becomes External when either we export the variables to an XML file or define them directly in such a file and later, load the file with the variables and values to the test.

Definitions of the types of variable classifications are as follows:

We can also store a value to an Environment variable dynamically from the code. Such a variable will have global scope but will be accessible during runtime only. This means that you will not see it in the list of Internal variables, as shown in this recipe. The procedure is equivalent to using the default Add method of the Scripting.Dictionary object, as shown in the following line of code:

Environment("MyEnvParam") = "MyEnvValue"

Refer to an article by Yaron Assa at http://www.advancedqtp.com/reservedobjects-as-an-env-object-replacement.

Create a user-defined Environment variable named MyEnvParam (see the previous recipe, Storing data in the Environment object).

The following code shows how to retrieve either a built-in or a user-defined variable:

Print Environment("TestDir")
'Prints the Built-in TestDir (path) Environment variable to the console
Print Environment("MyEnvParam")
'Prints the User-defined MyEnvParam Environment variable to the console

Similar to the workings of the Scripting.Dictionary object, by accessing an existing key, the Environment object returns its paired value.

User-defined Environment variables can be stored in an XML file and dynamically loaded during the runtime session. Refer to the Using global variables (Environment) recipe of Chapter 8, Utility and Reserved Objects.

To complete this recipe, we need to use the global Extern object, which with proper use provides the UFT with access to the methods of an external Dynamic Link Library (DLL). We will define a variable and assign it a reference to the global Extern object (this is done to avoid persistence, as Extern is a reserved object not released from memory until UFT closes):

Dim oExtern
set oExtern = Extern

Then, we will declare the method or methods we wish to call from the relevant Win32API. In this case, the method is GetPrivateProfileString, which retrieves the value of a given key within a specific section:

oExtern.Declare micInteger,"GetPrivateProfileString", "kernel32.dll","GetPrivateProfileStringA", _
               micString, micString, micString, micString+micByRef, micInteger, micString

After defining the connection to the DLL with its returned value and arguments, we can retrieve the value of any key within a given section. In the following example, the ConfigFileVersion key specified in the file wrls.ini is located in the UFT/bin folder. In the end, the Extern object reference is destroyed at the end of the run:

call oExtern.GetPrivateProfileString("ProgramInformation", "ConfigFileVersion", "", RetVal, 255, "C:\Program Files\HP\Unified Functional Testing\bin\wrls_ins.ini")
print  RetVal

set oExtern = nothing

The output to the console in this case was the string 1.05.

Follow the same steps stated in the Getting ready section of the Reading values from an INI file recipe.

Create a new file with the name QA-env-settings.ini. Enter the following entries to create three sets of parameters corresponding to three test environments QA1, QA2, and QA3:

[QA1]
InputDataSrc= "RegressionData1.xls"
Username  	= "user1"
URL       	= "http://www.url1.com"
Description = "Data for QA1 environment"

[QA2]
InputDataSrc= "RegressionData2.xls"
Username  	= "user2"
URL       	= "http://www.url2.com"
Description = "Data for QA2 environment"

[QA3]
InputDataSrc = "RegressionData3.xls"
Username  	= "user3"
URL       	= "http://www.url3.com"
Description = "Data for QA3 environment"

In our test, we will load the input data based on the value of the Environment variable QA_ENV, which will take one of the following environments: QA1, QA2, or QA3. Before running the test, ensure that the variable exists, and provide the value for the required testing environment (see the Storing data in the Environment object recipe). Therefore, our code in Action1 will look like the following code snippet:

Dim sDataSourcePath, sURL, sUsername

oExtern.GetPrivateProfileString(Environment("QA_ENV"), _
"InputDataSrc", "", sDataSourcePath, 255, _
"QA_env_settings.ini")

oExtern.GetPrivateProfileString(Environment("QA_ENV"), _
"InputDataSrc", "", sURL, 255, "QA_env_settings.ini")

oExtern.GetPrivateProfileString(Environment("QA_ENV"), _
"InputDataSrc", "", sUsername, 255, "QA_env_settings.ini")

DataTable.Import(sDataSourcePath)

We retrieve the value of the QA_ENV Environment variable, and accordingly load the values of the variables in the corresponding section in the .ini file. The value of the InputDataSrc key within the corresponding section is then retrieved (note that the parameter is passed by reference and filled by the target method) and is used to import the Excel file (as you can see in the Importing an Excel file to a test recipe) that contains the input data for the given testing environment.

In UFT, create a new function library by navigating to File | New | Function Library (or use the key shortcut Alt + Shift + N) and save it as UFT_Globals.vbs. It is recommended to save it in a folder, which would be shared later by all tests.

Navigate to File | Settings and attach the function library to the test.

As any public variable declared in a function library attached to a test can be accessed by any action, we will define a global variable and two functions to initialize initGlobalDictionary and dispose disposeGlobalDictionary:

Dim GlobalDictionary

Function initGlobalDictionary()
    If not (lcase(typename(GlobalDictionary)) = "dictionary") Then
        Set GlobalDictionary = CreateObject("Scripting.Dictionary")    
    End If    
End Function
Function disposeGlobalDictionary()
    Set GlobalDictionary = nothing
End Function

The initGlobalDictionary() function will check if the public variable GlobalDictionary was not initialized earlier, and then set it with a reference to a new instance of a Dictionary object, as mentioned in the previous code. The disposeGlobalDictionary() function is given for the sake of completeness, as in any case, memory is released when the test stops. However, we may wish to empty the GlobalDictionary variable in certain cases, so it is recommended to include this function as well.

Now, in Action1 (or whichever action runs first in our test), we will write the following code:

If cint(Environment("TestIteration")) = 1 and cint(Environment("ActionIteration")) = 1 Then    
    call initGlobalDictionary()
End If

The previous code will ensure that the GlobalDictionary variable is instantiated only once at the beginning of the run session. If we need a new instance for every test iteration, then we just need to change the code to the following lines of code, so that we get a new instance only at the start of the first Action1 iteration:

If CInt(Environment("ActionIteration")) = 1 Then    
    call initGlobalDictionary()
End If

With our test set up this way, we can now use this global object to share data as in the following example. Create a new Action2 DataTable and make it run after Action1 (at the end of the test). Now, write the following code in Action1:

GlobalDictionary.Add "CustomerID", "123456789"
Print Environment("ActionName") & ": " & GlobalDictionary("CustomerID")

In Action2, write the following code:

Print Environment("ActionName") & ": " & GlobalDictionary("CustomerID")

It is strongly recommended to remove a key from the dictionary when it is no longer required:

GlobalDictionary.Remove "CustomerID"

Alternatively, to remove all keys from the dictionary altogether at the end of a test iteration or at the beginning of a test iteration greater than the first, use the following line of code:

GlobalDictionary.RemoveAll

As mentioned earlier, keys must be unique and if we use the same keys in each test iteration, it would cause a runtime error with the first key found to exist in the dictionary. Another way, as mentioned earlier, is to call the disposeGlobalDictionary at the end of each test iteration and the initializeGlobalDictionary() method at the start.

When you run this test, in Action1, it first creates a new Dictionary instance and assigns a reference to the public variable GlobalDictionary. Then, it adds a new key CustomerID with the value 123456789, and prints the action name from the Environment built-in runtime variables ("Action1") and the value, by referring to the CustomerID key we just added. Then, it executes Action2, where it again prints in the same manner as in Action1. However, as the ActionName Environment variable is dynamic, it prints "Action2". This is to prove that Action2 actually has access to the key and value added in Action1. The output of this test is as shown in the screenshot:

Refer to the Using a global dictionary for fast shared code access recipe.

Refer to the Getting ready section of the Using a global dictionary for fast shared data access recipe. Basically, we can just add the code to the same function library and actions.

The first steps of defining the GlobalDictionary variable and the functions to manage its instantiation and disposal are identical, as in the recipe Using a global dictionary for fast shared data access, so we can just skip to the next step.

The remaining implementation deserves special attention. In the Globals.vbs function library that we attached to the test, we will add the following pieces of code:

Class MyOperation1
    Function Run()
        Print typename(me) & " is now running..."
    End Function
End Class

Class MyOperation2
    Function Run()
        Print typename(me) & " is now running..."
    End Function
End Class

Function GetInstance(cls)
    Dim obj
    
    On error resume next
    Execute "set obj = new " & cls
    If err.number <> 0 Then
        reporter.ReportEvent micFail, "GetInstance", "Class " & cls & " is not defined (error #" & err.number & ")"
        Set obj = nothing
    End If
    Set GetInstance = obj
End Function

The two classes follow the command wrapper design pattern. Note that they both contain a Run function (any name would do). This follows a pattern, which enables us to load an instance of each class and store it in our GlobalDictionary variable.

The GetInstance(cls) function acts as a generic constructor for our encapsulated functions. It is absolutely necessary to have such a constructor in the function library because UFT does not support instantiating classes with the operator new within an action. We use the Execute function to make the line of code, resulting from concatenating the command string with the cls parameter passed to the function, and hence, it can return an instance of any class contained in any other associated function library. The function checks if an error occurs while trying to create a new instance of the given class. This could happen if the string naming the class is inaccurate. In such a case, the function returns nothing after reporting a failure to the test report. In such a case, we may wish to halt the test run altogether by using the ExitTest command.

In Action1, we will add the following code:

GlobalDictionary.Add "Op1", GetInstance("MyOperation1")
GlobalDictionary.Add "Op2", GetInstance("MyOperation2")

In Action2, we will add the following code:

GlobalDictionary("Op1").Run
GlobalDictionary("Op2").Run

The output of the test is now as shown in the following screenshot:

When you run this test, the initial process of GlobalDictionary instantiation is executed, as in the previous recipe. Then, we simply add two keys to the GlobalDictionary and assign a reference to each value to an instance of the command wrapper classes MyOperation1 and MyOperation2. When the test flow reaches Action2, we access these instances by retrieving the items (or the values) we stored with the keys, and then have access to the classes' public methods, fields, and properties. The code line is as follows:

GlobalDictionary("Op1").Run

First, it retrieves the reference to the MyOperation1 object, and then, it applies to the Op1 operator to access the public Run method, which just prints the name of the class and a string.

Of course, the Run method of the command wrapper pattern may need a variable number of arguments, because different functions meet different requirements. This can easily be resolved by defining the Run method as accepting one argument and passing a Dictionary object with the keys and values for each variable that is required.

For example, assuming that the dic argument is a dictionary:

Class MyOperation1
    Function Run(dic)
        Print typename(me) & " is now running..."
        Print dic("var1")
        Print dic("var2")
        Print typename(me) & " ended running..."
    End Function
End Class

Now, we would use the following code in Action2 to call the Run method:

Set dic = CreateObject("Scripting.Dictionary")
dic.Add "var1", "Some value"
dic.Add "var2", "Some other value"
GlobalDictionary("Op1").Run

Also refer to the Using a global dictionary for fast shared data access recipe in this chapter. We will also delve more in depth into the command wrapper design pattern in Chapter 7, Using Classes.