QTP FUNCTIONS

Utility Functions

SystemUtil.Run:

Description:

Runs a file or application.

Syntax:

object.Run file, [params], [dir], [op], [mode]

Object	A test object of type SystemUtil.
File	Required. A String value. The name of the file you want to run.
Params	Optional. A String value. If the specified file argument is an executable file, use the params argument to specify any parameters to be passed to the application.
Dir	Optional. A String value. The default directory of the application or file.
Op	Optional. A String value. The action to be performed. If this argument is blank ( ""), the open operation is performed.

Mode:

Optional. An Integer value. Specifies how the application is displayed when it opens. You can specify one of the modes in the table below. Default = 1 Mode Description 0 Hides the window and activates another window. 1  Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. Specify this flag when displaying the window for the first time. 2  Activates the window and displays it as a minimized window. 3  Activates the window and displays it as a maximized window. 4  Displays the window in its most recent size and position. The active window remains active. 5  Activates the window and displays it in its current size and position. 6  Minimizes the specified window and activates the next top-level window in the Z order. 7  Displays the window as a minimized window. The active window remains active. 8  Displays the window in its current state. The active window remains active. 9  Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. Specify this flag when restoring a minimized window. 10  Sets the show-state based on the state of the program that started the application.

-------------------------------------------------------------------------------------------------

Environment.Value:

Description :

Enables you to work with environment variables.

You can set or retrieve the value of environment variables using the Environment object. You can retrieve the value of any environment variable. You can set the value of only user-defined, environment variables.

Syntax :

To set the value of a user-defined, environment variable:

Environment (VariableName) = NewValue

To retrieve the value of a loaded environment variable:

CurrValue = Environment (VariableName)

Argument	Type	Description
VariableName	String	The name of the environment variable.
NewValue	Variant	The new value of the environment variable.
CurrValue	Variant	The current value of the environment variable.

-------------------------------------------------------------------------------------------------

Environment.ExternalFileName:

Description :

Returns the name of the loaded external environment variable file specified in the Environment tab of the Test Settings dialog box. If no external environment variable file is loaded, returns an empty string.

Syntax:

Environment.ExternalFileName

Example :

The following example uses the ExternalFileName property to check whether an environment variable file is loaded, and if not, loads a specific file and then displays one of the values from the file.

'Check if an External Environment file is loaded and if not, load it.

fileName = Environment.ExternalFileName

If (fileName = "") Then

       Environment.LoadFromFile("C:\Environment.xml")

End If

'display value of one of the Environment variables from the External file

msgbox Environment("MyVarName")

-------------------------------------------------------------------------------------------------

Environment.LoadFromFile filename

Description:

Loads the specified environment variable file. The environment variable file must be an XML file using the following syntax:

<Environment>

       <Variable>

              <Name>This is the first variable's name</Name>

              <Value>This is the first variable's value</Value>

       </Variable>

</Environment>

Note: You can also continue to use your QuickTest Professional 6.5 environment files (.ini format).

For more information about environment variable files, refer to the QuickTest Professional User's Guide.

Syntax :

Environment.LoadFromFile(Path)

Argument	Type	Description
Path	String	The path of the environment file to load.

Example

The following example loads the MyVariables.xml file.

Environment.LoadFromFile("C:\QuickTest\Files\MyVariables.xml")

-------------------------------------------------------------------------------------------------

Reporter.ReportEvent:

Description:

Reports an event to the test results.

Syntax :

Reporter.ReportEvent EventStatus, ReportStepName, Details [, Reporter]

Argument	Type	Description
EventStatus	Number or pre-defined constant	Status of the report step: 0 or micPass: Causes the status of this step to be passed and sends the specified message to the report. 1 or micFail: Causes the status of this step to be failed and sends the specified message to the report. When this step runs, the test fails. 2 or micDone: Sends a message to the report without affecting the pass/fail status of the test. 3 or micWarning: Sends a warning message to the report, but does not cause the test to stop running, and does not affect the pass/fail status of the test.
ReportStepName	String	Name of the intended step in the report (object name).
Details	String	Description of the report event. The string will be displayed in the step details frame in the report.
Reporter	N/A	Not in use.

Example:

The following examples use the ReportEvent method to report a failed step.

Reporter.ReportEvent 1, "Custom Step", "The user-defined step failed."

or

Reporter.ReportEvent micFail, "Custom Step", "The user-defined step failed."

-------------------------------------------------------------------------------------------------

DataTable.Value:

Description :

DataTable default property. Retrieves or sets the value of the cell in the specified parameter and the current row of the run-time Data Table.

Note: This property returns the computed value of the cell. For example, if the cell contains a formula, the method returns True or False.

Syntax :

To find the value:

DataTable.Value(ParameterID [, SheetID])

Argument	Type	Description
ParameterID	Variant	Identifies the parameter (column) of the value to be set/retrieved. Index values begin with 1.
SheetID	Variant	Optional. Identifies the sheet to be returned. The SheetID can be the sheet name, index or dtLocalSheet, or dtGlobalSheet. If no Sheet is specified, the first sheet in the run-time Data Table is used (global sheet). Index values begin with 1

-------------------------------------------------------------------------------------------------

Parameter.Item (parametername):

Parameter:  A value that is defined or generated separately from the step and is retrieved when the specific step runs.

Configuring a Parameter Value :

If you select Parameter for a value that is already parameterized, the Parameter box displays the current parameter definition for the value. If you select Parameter for a value that is not yet parameterized, the Parameter box displays the default parameter definition for the value.

Setting Test and Action Parameter Options

Test and action parameters enable you to use parameter values that have been passed from the external application that ran (called) your test. The Parameter options that are available depend on where you are currently located in your test, and whether test or action parameters are defined

When Test/action parameter is selected as the parameter type, you can select the required parameter in the Parameter Options dialog box. You open the Parameter Options dialog box by clicking the Parameter Options button in any Checkpoint Properties dialog box

Defining the Settings for a Test or Action Parameter

The following options are available for configuring test or action parameters:

• Test parameters or Parent action parameters. Parameter defined in the test or parent action. (If no output parameters are defined in the test or parent action, this area is disabled.) Test parameters are available only for top-level actions. They are defined in the Parameters tab of the Test Settings dialog box. Parent action parameters are available for subsequent steps and for nested actions. They are defined in the action containing the steps or in the action that calls the nested action.
• Parameter. Specifies the name of the input parameter. The read-only list of available parameters contains the names and full descriptions of the currently defined input parameters for the action. You can resize the display, as needed, and, if the list of parameters is long, you can scroll through the list.
• Output from previous action call(s). Any previous action in the same hierarchical level for which output parameters are defined. (If no output parameters are defined in previous actions, this area is disabled.)
• Action. Specifies the previous action from which you can choose an output parameter. You can choose any action in the list.
• Parameter. Specifies the name of the output parameter. The read-only list of available parameters contains the names and full descriptions of the currently defined output parameters from the previous action(s). You can resize the display, as needed, and, if the list of parameters is long, you can scroll through the list.

-------------------------------------------------------------------------------------------------

Test Object Functions

GetROProperty:

GetROProperty method to retrieve the current value of a test object property from a run-time object in your application.

For example:

you can retrieve the target value of a link during the run session as follows:

link_href = Browser("Mercury Technologies").Page("Mercury Technologies").Link("Jobs").GetROProperty("href")

-------------------------------------------------------------------------------------------------

GetTOProperty:

Description:

Returns the value of the specified property from the test object description.

Syntax:

object.GetTOProperty (Property)

Argument	Description
object	A test object of type WinTreeView.
Property	Required. A String value. The property whose value is retrieved from the object description.

Return Value:A Variant value.  

Remarks:

GetTOProperty differs from the GetROProperty method. GetTOProperty returns the value from the test object's description. GetROProperty returns the current property value of the object in the application during the test run.

-------------------------------------------------------------------------------------------------

Exist:

Description :

Checks that an object exists.

Syntax :

DbTable(description).Exist([Timeout])

Argument	Type	Description
Timeout	Number	Optional. The length of time to search for the object before returning a True or False value. If a timeout value is specified, QuickTest waits until it finds the object or until the timeout is reached. If the value 0 is specified, the method returns the True or False value immediately. If no value is specified, the value specified in the Test Settings dialog box for the Object Synchronization Timeout is used for tests. For more information on the Object Synchronization Timeout, refer to the QuickTest Professional User's Guide

 

Return Value : Boolean

Example:

The following example creates a database checkpoint and then checks that the database table object exists.

DbTable("DbTable").Check CheckPoint("DbTable")

IsExists = DbTable("DbTable").Exist (0)

-------------------------------------------------------------------------------------------------

CheckProperty:

Description:

Checks whether the specified object property achieves the specified value within the specified timeout.

Syntax:

object.CheckProperty (PropertyName, PropertyValue, [TimeOut])

Argument	Description
Object	A test object of type ActiveX.
PropertyName	Required. A String value. The name of the property whose value is checked. The available properties are listed in the Identification Properties page under the Properties section for each test object.
PropertyValue	Required. A Variant value. The expected value against which the actual property value should be checked. You can either use a simple value or you can use a comparison object together with the value to perform more complex comparisons.
TimeOut	Optional. An ULong object. The time, in milliseconds, within which QuickTest should check whether the actual value of the property matches the specified expected value. If no value is specified, QuickTest uses the time set in the Object Synchronization Timeout option in the Run tab of the Test Settings dialog box.

Return Value

A Boolean value.  Returns TRUE if the property achieves the value, and FALSE if the timeout is reached before the property achieves the value.

A TRUE return value reports a Passed step to the test results; a FALSE return value reports a Failed step to the test results.

-------------------------------------------------------------------------------------------------

WaitProperty:

Description:

Waits until the specified object property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Syntax:

object.WaitProperty (PropertyName, PropertyValue, [TimeOut])

Argument	Description
Object	A test object of type ActiveX.
PropertyName	Required. A String value. The name of the property whose value is checked.
PropertyValue	Required. A Variant value. The value to be achieved before continuing to the next step.
TimeOut	Optional. A Long value. The time, in milliseconds, after which QuickTest continues to the next step if the specified value is not achieved. If no value is specified, QuickTest uses the time set in the Object Synchronization Timeout option in the Run tab of the Test Settings dialog box.

Return Value

A Boolean value.  Returns TRUE if the property achieves the value, and FALSE if the timeout is reached before the property achieves the value. A FALSE return value does not indicate a failed step.

-------------------------------------------------------------------------------------------------

GetContent:

Description:

Returns all of the items in the combo box list.

;’[

Syntax:

object.GetContent

Argument	Description
object	A test object of type AcxComboBox.

Return Value

A String value.  The returned string contains all of the items in the list separated by VBScript line feed characters.

-------------------------------------------------------------------------------------------------

Select:

Description:

Selects the specified item in the list, replacing any previously selected values.

Syntax

object.Select Item

Argument	Description
object	A test object of type WebList.
Item	Required. A Variant value. The value to select. The value can either be one of the items in the list or an index. To specify the index of the item to select, use "#index". Index values begin with 0.

Return Value:None.  

-------------------------------------------------------------------------------------------------

GetItemsCount:

Description

Returns the number of items in the combo box list.

Syntax

object.GetItemsCount

Argument	Description
object	A test object of type AcxComboBox.

Return Value : A Long value.  

-------------------------------------------------------------------------------------------------

GetItem:

Description

Returns the value of the item specified by the index.

Syntax

object.GetItem (Item)

Argument	Description
object	A test object of type AcxComboBox.
Item	Required. A Variant value. Numeric index of the item. Index values begin with 0.

Return Value:A String value.  

-------------------------------------------------------------------------------------------------

RowCount:

Description:

Returns the number of rows in the table.

Syntax:

object.RowCount

Argument	Description
object	A test object of type WebTable.

Return Value: A Long value.  

-------------------------------------------------------------------------------------------------

ColumnCount:

Description:

Returns the number of columns in a (report-style) list-view control.

Syntax:

object.ColumnCount

Argument	Description
object	A test object of type VbListView.

Return Value:A Long value.  

Remarks: Only the visible columns are counted.

-------------------------------------------------------------------------------------------------

GetCellData:

Description

Retrieves the contents of the specified cell from the table.

Syntax

object.GetCellData (Row, Column)

Argument	Description
Object	A test object of type AcxTable.
Row	Required. A Variant value. The 0-based index of the row containing the cell whose data you want to retrieve. The index value is recorded in the format "#N" where N is the 0-based row index. When entering the argument value manually, you can use any of the following string or number formats: "#N", "N", or N.
Column	Required. A Variant value. The name or 0-based index of the column containing the cell whose data you want to retrieve. The column value is recorded in the format "#N" where N is the 0-based column index. When entering the argument value manually, you can use any of the following string or number formats: "ColumnName", "#N", "N", or N.

Return Value: A String value.  

-------------------------------------------------------------------------------------------------

DataTable Method

GetRowCount:

Description :

Returns the total number of rows in the longest column in the first sheet in the run-time Data Table (global sheet).

Syntax

DataTable.GetRowCount

Return Value : Number

Example :

The following example uses the GetRowCount method to find the total number of rows in the longest column of the MySheet run-time data sheet and writes it to the report.

rowcount = DataTable.GetSheet("MySheet").GetRowCount

Reporter.ReportEvent 2, "There are " &rowcount, "rows in the data sheet."

-------------------------------------------------------------------------------------------------

SetNextRow:

Description:

Sets the row after the current (active) row as the new current row in the run-time Data Table.

Note: You can only set a row that contains at least one value. If the current row is the last row in the Data Table, applying this method sets the first row in the Data Table as the new current row.

Syntax :

DataTable.SetNextRow

Example :

The following example uses the SetNextRow method to change the active row to the next row in the run-time Data Table.

DataTable.SetNextRow

SetCurrentRow:

 

Description :

Sets the specified row as the current (active) row in the run-time Data Table.

Note: You can only set a row that contains at least one value.

Syntax :`

DataTable.SetCurrentRow(RowNumber)

Argument	Type	Description
RowNumber	Number	Indicates the number of the row to set as the active row. The first row is numbered 1.

 

Example

The following example uses the SetCurrentRow method to change the active row to the second row in the global run-time Data Table.

DataTable.SetCurrentRow (2)

GetSheet:

 

Description :

Returns the total number of sheets in the run-time Data Table.

Syntax :

DataTable.GetSheetCount

Return Value : Number

Example :

The following example uses the GetSheetCount method to find the total number of sheets in the run-time Data Table and writes it to the report.

sheetcount = DataTable.GetSheetCount

Reporter.ReportEvent 0, "Sheet number", "There are " & sheetcount & " sheets in the Data Table."

-------------------------------------------------------------------------------------------------

GetParameterCounts:

 

Description :

Returns the total number of parameters (columns) in the run-time Data Table sheet.

Syntax : DTSheet.GetParameterCount

Return Value :Number

Example

The following example uses the GetParameterCount method to find the total number of parameters (columns) in the run-time Data Table sheet (MySheet) and writes it to the report.

paramcount = DataTable.GetSheet("MySheet").GetParameterCount

Reporter.ReportEvent 2, "There are " &paramcount, "columns in the data sheet."

-------------------------------------------------------------------------------------------------

AddSheet:

Description :

Adds the specified sheet to the run-time Data Table and returns the sheet so that you can directly set properties of the new sheet in the same statement.

Syntax :

DataTable.AddSheet(SheetName)

Argument	Type	Description
SheetName	String	Assigns a name to the new sheet.

Return Value : DTSheet Object.

 

Example :

The following example uses the AddSheet method to create the new sheet, "MySheet" in the run-time Data Table and then adds a parameter to the new sheet.

Variable=DataTable.AddSheet ("MySheet").AddParameter("Time", "8:00")

-------------------------------------------------------------------------------------------------

DeleteSheet:

Description :

Deletes the specified sheet from the run-time Data Table.

Syntax :

DataTable.DeleteSheet SheetID

Argument	Type	Description
SheetID	Variant	Identifies the sheet to be returned. The SheetID can be the sheet name or index. Index values begin with 1.

Example

The following example uses the DeleteSheet method to delete the sheet, "MySheet" from the run-time Data Table.

DataTable.DeleteSheet "MySheet"

-------------------------------------------------------------------------------------------------

GetSheetCount:

Description : Returns the total number of sheets in the run-time Data Table.

Syntax :  DataTable.GetSheetCount

Return Value : Number

Example

The following example uses the GetSheetCount method to find the total number of sheets in the run-time Data Table and writes it to the report.

sheetcount = DataTable.GetSheetCount

Reporter.ReportEvent 0, "Sheet number", "There are " & sheetcount & " sheets in the Data Table."

AddParameter:

Description :

Adds the specified parameter (column) to the sheet in the run-time Data Table, sets the value of the first row to the specified value, and returns the parameter so that you can directly set or retrieve properties of the new parameter in the same statement.

Syntax : DTSheet.AddParameter(ParameterName, Value)

Argument	Type	Description
ParamterName	String	Assigns a name to the new parameter. If another parameter in the sheet has the same name, a number (i.e. '1') will be appended to the assigned ParameterName. If the ParameterName contains illegal characters, the illegal characters will be replaced with '_' characters.
Value	String	Assigns a value to the first row of the parameter.

 

Return Value :DTParameter Object

Example

The following example uses the AddParameter method to create the new Parameter, "Arrival" within the new sheet, MySheet of the run-time Data Table, and sets the first cell in the column as "New York". Because the method also returns the newly created parameter, it is possible to use methods or check properties of the new sheet within the same statement.

ParamName=DataTable.AddSheet("MySheet").AddParameter("Arrival", "New York").Name

Note that if a parameter with the name "Arrival" already exists in the sheet, the example above will return "Arrival1" as the actual name assigned to the new parameter.