TruClient Functions

The below functions can be used in every field in TruClient that can evaluate JavaScript, such as in Step arguments, Objects, and descriptor fields.

Note: Use escape backslashes in path arguments. For example, c:\\temp\\myFile.ps1.

Vuser
Browser
VTS
Environment

Tip: The following arguments can be used with any method:

  • object. The step's object as defined in the application.

  • AUT.window. Points to the global window object of the application. Note that AUT.window.location cannot be used with Internet Explorer. Use AUT.document.URL instead.

  • AUT.document. The global document object of the application.

The AUT API provides a common mechanism for handing the AUT window and AUT document for all TruClient protocols. For details, see Using JavaScript in the AUT Window.

 

IO.createDir(path)

Creates the specified folder. If needed, creates all the folders necessary to complete the path.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path of the folder.

Example

IO.createDir(TC.outputDir + "mydir")  

Back to top

IO.delete(path)

Deletes the specified folder or file. If a folder is specified, deletes all the files in the folder, including sub-directories.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path of the folder or file.

Example

IO.delete(TC.outputDir + "mydir") 

Back to top

IO.isExist(path)

Returns true if the specified folder or file exists, and false if it does not, or for a disconnected or unauthenticated mapped drive.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path of the folder or file.

Example

IO.is Exist(TC.outputDir + "mydir")

Back to top

IO.read(path, charset)

Returns all the data from the specified file. Converts the data from the specified charset to unicode.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path of the file.

charset. The charset of the file, if it is not UTF-8.

Example

var log = IO.read(TC.scriptDir + "mylog.txt");
TC.log(log);

Back to top

IO.write(path, string, append, charset)

Writes the string to the specified file. If the file does not exist it is created.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path to the file.

string. The string to write to the file.

append. Boolean.

  • true. (default) Append the string to the end of the file.
  • false. Overwrite the file with the string.

charset. The charset of the file, if it is not UTF-8.

Example

IO.write(TC.scriptDir + "mylog.txt", "first msg\n", false);

IO.write(TC.scriptDir + "mylog.txt", "second msg");

The result content in the mylog.txt file:

first msg

second msg

Back to top

TC.addNetworkFilter(filters, include, applyTo)

Adds a filter for URL requests.

Caution: Relevant only for steps that have a network-related end event, or that do not have any end event.

Arguments

filters. String representing one or more URLs. Separate multiple URLs with a semi-colon (;). The URL can have the wildcard (*) which can match 0 or more characters.

include. True to include URL requests that match the filter; false otherwise (default). Optional argument.

applyTo. Optional argument. Specify the type of request the filter applies to:

  • Xhr. Filters XHR requests only.

  • NonXhr. Filters non-XHR requests only.

  • All. (default) Filters all requests.

Note: You cannot use exclude and include filters at the same time.

Example:

TC.addNetworkFilter("http://www.hpe.com/*", true, "All")

From the point that you add this API call, until you call the remove filter or the end of the iteration, TruClient will not wait for requests to get a response unless the URL has a http://www.hpe.com/ prefix.

Back to top

TC.clearNetworkFilters

Removes all URL request filters.

Caution: Relevant only for steps that have a network-related end event, or that do not have any end event.

Arguments

None

Example

None

Back to top

TC.startLogRequests

Starts logging URL requests.

Caution: Relevant only for steps that have a network-related end event, or that do not have any end event.

Arguments

None

Example

None

Back to top

TC.stopLogRequests

Stops logging URL requests.

Caution: Relevant only for steps that have a network-related end event, or that do not have any end event.

Arguments

None

Example

None

Back to top

TC.advanceParam(name)

Advances the specified parameter to the next value in the file.

Arguments

name. The name of the parameter to advance. Must be a parameter of type file or unique number.

Example

TC.advanceParam("multi_row_param");

Back to top

TC.getAttr (name)

Returns the value of the command line parameter passed to the test or the default value set for it.

Note: Not supported in TruClient Lite.

Arguments

name. The name of the command-line parameter.

The command-line parameter name is generally assigned by the user in the Additional Attributes tab in Run-Time Settings or in the Controller in the group command line argument.

When the test is run, the additional attribute or the group command line argument is passed to the test as a parameter in the command line. During test run, the value can be accessed with this function.

Example

To get the Controller command line argument, -MyServerURL http://myserver.com, call:

TC.getAttr(“MyServerURL”);

Back to top

TC.getUserIP

Returns the IP address when IP spoofing is enabled and the script is running in load mode in Controller.

Note: This function has no effect when replayed in TruClient Lite.

Arguments

None

Example

None

Back to top

TC.setParam(name, value)

Saves a string to a parameter, creating a temporary parameter value in the memory if it does not exist (it does not create a parameter that can be read in the next run).

Arguments

name. The name of the parameter in which to save the value.

value. The value.

Example

TC.setParam("myparam", "paramVal");

Back to top

TC.crossTransactionStart(name, value)

Begins a transaction in a Vuser script that will be ended in another Vuser script.

Note: This function has no effect when replayed in TruClient Lite.

Arguments

name. The name of the transaction.

value. A pointer to a parameter list.

Example

None

Back to top

TC.outputMessage(text)

Same as TC.log at the Standard log level with the additional ability to show the message in the Controller's Output window as a notification.

Arguments

text. The message text.

Example

TC.outputMessage("My output message");

Back to top

TC.crossTransactionEnd(name, value, status)

Ends a transaction in a Vuser script that has been started in another Vuser script.

Note: This function has no effect when replayed in TruClient Lite.

Arguments

name. The name of the transaction.

value. A pointer to a parameter list.

status. One of the following: "Pass" or "Fail".

Example

None

Back to top

TC.transactionDuration(name)

Returns the duration of a specific transaction, in seconds.

Note: Not supported in TruClient Lite

Arguments

name. The name of the transaction

Example

None

Back to top

TC.getParam(ParamName)

Returns the value of the specified parameter.

Arguments

name. The parameter name.

Example

Back to top

TC.evalC(funcname)

Runs the specified function whose definition is found in the specified file.

Note: Not supported in TruClient Lite.

Arguments

funcname. The function name.

Note: Use the #include command to include the file where the function is defined.

Example

TC.evalC("myFunc");

Back to top

TC.log(text, level)

Logs a message.

Arguments

text. The message.

level. One of the following:

  • "Error"
  • "Warning"
  • "Standard"
  • "Extended"
  • "Status" Setting the TC.log level to Status sends a string to the Status area of the Controller. It also sends the string to the Vuser log. When run from VuGen, the message is sent to output.txt.

Example

TC.log("my warning", "Warning");

Back to top

TC.unmask(text)

Returns the text after unmasking.

Note: Not supported in TruClient Lite.

Arguments

text. The masked text.

Example

TC.unmask(str);

Back to top

TC.userDataPoint(name, value)

Records a user-defined data point for analysis.

Note: This function has no effect when replayed in TruClient Lite.

Arguments

name. The name of the data point. Do not begin a data-point name with any of these strings: HTTP, NON_HTTP, RETRY, mic_, stream_, mms_

value. The numeric value.

Example

TC.userDataPoint("myDP", 1);

Back to top

evalXPath(path)

Returns an array of the objects defined by the XPath in the argument.

Arguments

xpath. The xpath query.

Example

evalXPath("//a[text()=\" New Mercury Tours \"]");

Back to top

TC.startTransaction (name)

Starts a LoadRunner transaction.

Arguments

name. The name of the transaction to start.

Example

TC.startTransaction("login_tr1");

Back to top

TC.endTransaction(name, status)

Ends a LoadRunner transaction.

Arguments

name. The name of the transaction to end

status. One of the following values: “Pass”, “Fail”, “Auto”

Example

TC.endTransaction("login_tr1", status);

Back to top

TC.vuserStatusMessage(string)

Indicates which Vuser is handling a specific script.

Note: This function has no effect when replayed in TruClient Lite.

Arguments

string. Any string.

Example

TC.vuserStatusMessage("FlightStatus");

Back to top

Utils.clearCookies()

Removes all cookies currently stored by the Vuser.

Note: Not supported in the Chromium browser

Arguments

None

Example

None

Back to top

Utils.clearCache()

Clears the contents of the cache simulator.

Note: Not supported in the Chromium browser

Arguments

None

Example

None

Back to top

Utils.getEnv(name)

Returns the value of the specified environment variable. Returns an empty string if the specified variable does not exist.

Note: Not supported in TruClient Lite.

Arguments

name. The name of the environment variable.

Example

var path = Utils.getEnv("PATH"); path + ";C:\\loadrunner\\");

Back to top

Utils.import(path)

Evaluates the specified JavaScript file in the arguments context.

Note: Not supported in TruClient Lite.

Arguments

path. The absolute path to the JavaScript file.

Example

Utils.import(TC.scriptDir + "myjs.js");

Back to top

Utils.isEnvExists(name)

Returns true if the specified environment variable exists and false if it does not exist.

Note: Not supported in TruClient Lite.

Arguments

name. The name of the environment variable.

Example

Utils.isEnvExists("PATH"); // returns true
Utils.isEnvExists("TC_kukuku"); // returns false

Back to top

Utils.setEnv(name, value)

Sets the named environment variable to the specified value. If the variable already has a value it is overwritten.

Note: Not supported in TruClient Lite.

Arguments

name. The name of the environment variable.

value. The value to set the environment variable to.

Example

Utils.setEnv("PATH", "C:\\loadrunner\\");

Back to top

Utils.addAutoFilter(url, isIncluded)

Adding a filter to one of the black list or white list lists of URLs. The URL of each HTTP request will be checked first against the black list, and then the white list. HTTP requests that do not pass the check will be blocked.

Arguments

url. String or regular expression representing the URL.

isIncluded. True to add the URL to white list. False to add the URL to black list.

Example

Set that only hpe domain will on the white list. All other domains are blocked.

String example:

Utils.addAutoFilter("http://www.hpe.com/*", true);

Regular expression example:

Utils.addAutoFilter(/^http:\/\/www\.hpe\.com\/.*/, true);

Back to top

Utils.cleanupAutoFilters(filter, isInclude)

Remove all filters from both the black list and white list lists of URLs.

Arguments

filter. String representing the URL.

isInclude. True value indicates the white list, false otherwise.

Example

Utils.cleanupAutoFilters();

Back to top

Utils.addAutoHeader (header, value, merge)

Adding an HTTP header to every consecutive HTTP requests following this function call.

Arguments

header. The name of the header to be added.

value. The value of the header to be added.

merge. True value indicates to merge the value with an existing header by the same name, false indicates to overwrite it.

Example

Utils.addAutoHeader("someCustomHeader", "someValue", true);

Back to top

Utils.cleanupAutoHeaders (header)

Removes all HTTP headers and stops adding HTTP headers to every consecutive HTTP request following this function call.

Arguments

header. The name of the header to be stopped from being added.

Example

Utils.cleanupAutoHeaders();

Back to top

TC.setProxy(option, settingsString)

Enables you to set a proxy address manually in the script.

Arguments

option. Specify the type of proxy do you want to use.

  • "PROXY_NONE". No proxy
  • "PROXY_SYSTEM". Use system proxy, settingsString will be ignored.
  • "PROXY_MANUAL" .manually set proxy
  • "PROXY_PAC". use PAC

settingsString. The details of the proxy setting.

Example

  • Manually set proxy and set separate proxy for different protocols (http & https)

    TC.setProxy("PROXY_MANUAL", '{"proxyShare":false,"proxyHttp":" proxy.xxx.com ","proxyHttpPort":8080,"proxySsl":" proxy.yyy.com ","proxySslPort":8080}');

  • Manually set proxy and share the proxy settings for all protocols (http, https, …)

    Note: If you also specify an address for “proxySsl”, it will be ignored because “proxyShare” is set to true.

    TC.setProxy("PROXY_MANUAL", '{"proxyShare":true,"proxyHttp":"proxy.xxx.com","proxyHttpPort":8080}');

  • Use system proxy settings. The second argument is ignored, so it can be any string value, usually empty.

    Note: Because schema needs two arguments, the second one cannot be omitted.

    TC.setProxy("PROXY_SYSTEM", "");

  • Do not use any proxy.

    Note: The proxy address/port that are set in the options sections are not removed. The settings in memory can be activated in another call (refer to the next example).

    TC.setProxy("PROXY_NONE", "");

  • Use manually set proxy which is already in memory (maybe set previously, maybe nothing is set)

    Note: If you are not sure which setting is in memory, it is recommended that you explicitly specify the proxy settings you want to use every time.

    TC.setProxy("PROXY_MANUAL ", "");

Back to top

TC.setLogLevel(logLevel, log_flags)

Enables you to change the log level during script replay. To restore initial log level setting, use TC.restoreLogLevel.

Note: Not supported in TruClient Lite.

Arguments

logLevel. Specify the log level

  • Disabled. No log file captured.
  • Standard. Standard log captured.
  • Extended. Extended log file captured.

log_flags. If the log level is set to extended, you can specify which data is captured using Boolean(true/false) flags as properties of json_object.

Any flag which is omitted will be considered as “false”

  • log_http
  • log_AUT
  • log_parameters

Example

  • Disable the log level

    TC.setLogLevel(“Disabled”);

  • Enable the standard log

    TC.setLogLevel(“Standard”);

  • Enable the extended log

    TC.setLogLevel(“Extended”);

  • Enable the extended log and specify which logs to capture

    TC.setLogLevel(“Extended”,{ log_http : true, log_AUT: true, log_parameters: true});

Back to top

TC.restoreLogLevel()

Restore log level to the initial setting.

Note: Not supported in TruClient Lite.

Arguments

None

Example

TC.restoreLogLevel();

Back to top

TC.vtcAddCell(colName, value, VtsName)

Sets the last field of a column to a value.

Equivalent method in LoadRunner: lrvtc_send_message

Arguments

colName.The name of the column.

value.The value as a string.

VtsName.The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the column will be created and the cell content is set to the argument value.

Example

TC.vtcAddCell("MyColumn","myValue","MyVts");

Back to top

TC.vtcAddCells(colNames, values, option, VtsName)

Sets the data in multiple columns. If option selected is 2, returns a value of 0 if value inserted. Returns a value of 1 if the value already exists.

Equivalent method in LoadRunner: vtc_send_row1

Arguments

ColNames. The column names delimited by a semi-colon.

values. The values as a string delimited by a semi-colon.

option. Define how the values are added

  • 0. Add as same row in all columns based on the column with the highest row count. The created row will be n+1 for all columns.
  • 1. Add as stack - last row in every column.
  • 2. Add as unique stack - last row in every column only if the value is unique in the column.

VtsName. The alias of the VTS server.

Remarks

If the columns specified in the argument do not exist, the columns will be created and the cell contents are set to the argument values.

Example

TC.vtcAddCells( "MyColumn1;MyColumn2;MyColumn2", "MyValue1;MyValue2;MyValue3", 0, "MyVts");

Back to top

TC.vtcAddUniqueCell(colName, value, VtsName)

Sets the last field of a column to a value if the value does not exist in the column. Returns a value of 0 if a value is inserted. Returns a value of 1 if the value already exists.

Equivalent method in LoadRunner: lrvtc_send_if_unique

Arguments

colName.The name of the column.

value.The value.

VtsName.The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the column will be created and the cell content is set to the argument value.

Example

TC.vtcAddUniqueCel("MyColumn",1,"MyVts");

Back to top

TC.vtcClearColumn(colName, VtsName)

Clears all data in a column.

Equivalent method in LoadRunner: lrvtc_clear_column

Arguments

colName.The name of the column.

VtsName.The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the step will run without returning an error and no data in the VTS is changed.

Example

TC.vtcClearColumn("MyColumn","MyVts");

Back to top

TC.vtcClearCell(colName, rowIndex, VtsName)

Clears the data in a field.

Equivalent method in LoadRunner: lrvtc_clear_message

Arguments

colName. The name of the column.

rowIndex. The index number of the field as an integer. 1 is the first field in the column.

VtsName. The alias of the VTS server.

Remarks

If the column or the row index specified in the argument does not exist, the step will run without returning an error and no data in the VTS will be changed.

Example

TC.vtcClearCell("MyColumn",1,"MyVts");

Back to top

TC.vtcColumnSize(colName, VtsName)

Returns the number of fields that contain data in a column.

Equivalent method in LoadRunner: lrvtc_column_size

Arguments

colName. The name of the column.

VtsName. The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the step will run without returning an error and the return value is 0.

Example

TC.vtcColumnSize("MyColumn","MyVts");

Back to top

TC.vtcConnect(serverName, port, VtsName)

Creates a connection to the server.

Equivalent method in LoadRunner: vtc_connect

Arguments

serverName. Either the IP or server name.

port. The port number

VtsName. The alias of the VTS server.

Remarks

None

Example

TC.vtcConnect("MyServer", 8888, "MyVts");

Back to top

TC.vtcDisconnect(VtsName)

Disconnects from the server.

Equivalent method in LoadRunner: lrvtc_disconnect

Arguments

VtsName. The alias of the VTS server.

Remarks

None

Example

TC.vtcDisconnect( "MyVts");

Back to top

TC.vtcDropIndex(colName, VtsName)

Deletes the index on a column.

Equivalent method in LoadRunner: lrvtc_drop_index

Arguments

colName. The column name.

VtsName. The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the step will run without returning an error.

In addition, if the index has already been dropped on the column, the step will run without returning and error.

Example

TC.vtcDropIndxe("MyColumn","MyVts");

Back to top

TC.vtcEnsureIndex(colName, VtsName)

Creates an index on a column.

Equivalent method in LoadRunner: lrvct_ensure_index

Arguments

colName .The name of the column.

VtsName. The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the step will run without returning an error.

In addition, if the index has already been created on the column, the step will run without returning and error.

Example

TC.vtcEnsureIndex("MyColumn","MyVts");

Back to top

TC.vtcIncrement(colName, rowIndex, value, VtsName)

Increments a counter stored in a field.

Equivalent method in LoadRunner: ltvtc_increment

Arguments

colName .The name of the column.

rowIndex. The index number of the field as an integer. 1 is the first field in the column.

value. The value as a string.

VtsName. The alias of the VTS server.

Remarks

If the column name specified in the argument does not exist, the column will be created and the cell referenced by the index will be set to the argument value.

If the index specified in the argument exceeds the column size, the cell is created by the specified index and the cell contents is set to the argument value.

If the column referenced by the index contains a string, the cell contents are replaced with the value argument.

Example

TC.vtcIncrement("MyColumn",1,1,"MyVTS");

Back to top

TC.vtcGetCell(colName, rowIndex, VtsName)

Returns the data in a field.

Equivalent method in LoadRunner: lrvtc_query_column

Arguments

colName .The name of the column.

rowIndex .The index number of the field as an integer. 1 is the first field in the column.

VtsName. The alias of the VTS server.

Remarks

If the column name or index name specified in the argument does not exist, a null value will be returned.

Example

TC.vtcGetCell("MyColumn",1,"MyVts");

Back to top

TC.vtcGetRowCells(rowIndex, VtsName)

Returns the data in a row as a javascript object. The properties of the object will be set to the column names

Equivalent method in LoadRunner: lrvtc_query_row

Arguments

rowIndex. The index number of the field . 1 is the first field in the column.

VtsName. The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, a null value will be returned for every column.

Example

TC.vtcGetRowCells(1,"MyVTS");

Back to top

TC.vtcPopCell(colName, VtsName)

Pops the first field from a column.

Equivalent method in LoadRunner: lrvtc_retrieve_message

Arguments

colName .The name of the column.

VtsName. The alias of the VTS server.

Remarks

None

Example

TC.vtcPopCell("MyColumn","MyVts");

Back to top

TC.vtcPopMultipleCells(colNames, VtsName)

Pops the first fields from specified columns. Returned as a javascript object. The properties of the object will be set to the column names.

Equivalent method in LoadRunner: vtc_retrieve_messages1

Arguments

colNames. The names of the columns.

VtsName. The alias of the VTS server.

Remarks

If the column name specified in the argument does not exist, a null value will be returned.

Example

TC.vtcPopMultipleCells("MyColumn","MyVts");

Back to top

TC.vtcUpdateCell(colName, rowIndex, value, VtsName)

Replaces the data in a field.

Equivalent method in LoadRunner: lrvtc_update_message

Arguments

colName .The name of the column.

rowIndex .The index number of the field as an integer. 1 is the first field in the column.

value. The value as a string.

VtsName. The alias of the VTS server.

Remarks

If the column name or index does not exist, the column and/or the cell referenced by the index will be created and the cell contents set to the argument value.

Example

TC.vtcUpdateCell("MyColumn",1,"MyValue","MyVTS");

Back to top

TC.vtcUpdateEqualsCell(colName, rowIndex, value, comparedValue, VtsName)

Replaces the data in a field if the current data equals a given value. Returns a value of 0 if the value is updated. Returns a value of 1 if the value does not match the compare value.

Equivalent method in LoadRunner: lrvtc_update_message_ifequals

Arguments

colName .The name of the column.

rowIndex. The index number of the field as an integer. 1 is the first field in the column.

value. The replacement value as a string.

comparedValue. If the current cell contents are the same as the comparedValue, the cell contents are replaced with value.

VtsName. The alias of the VTS server.

Remarks

None

Example

TC.vtcUpdateEqualsCell("MyColumn",1,"MyValue","MyCompareValue",MyVTS");

Back to top

See also: