Asynchronous functions

Available in version: TruClient 2020 SP1 and later

The below asynchronous functions can be used in step argument fields in TruClient that can evaluate JavaScript. They cannot be used in objects and descriptor fields.

For details on how to use asynchronous APIs, see Use asynchronous APIs in JavaScript code.

Note: Asynchronous APIs are not supported in TruClient - Native Mobile scripts. We recommend using Generic API Action steps instead. For details, see Replace synchronous APIs with Generic API Action steps.

In this topic:

General notes on using TruClient functions
General functions
Vuser functions
Browser functions
VTS functions
Environment functions

General notes on using TruClient functions

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

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 within the active window or tab 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 within the active window or tab of the application.
The AUT API provfides a common mechanism for handing the AUT window and AUT document for all TruClient protocols. For details, see Using JavaScript in the AUT window.

General functions

TCA.done(result)

Finishes an asynchronous operation and returns the result.

Note: The execution engine waits for completion notification after asynchronous APIs are called. It waits until TCA.done(result) is called if the execution succeeds, or until TCA.doneWithError(error) is called if the execution fails; the call should be at the end of the execution path of the JavaScript block. If neither are called, the current step fails with “Evaluate JavaScript code timeout” error.

Arguments

result. The result of the JavaScript block execution (any, optional).

Return value

None

Example:

IOA.read(TC.scriptDir + "mylog.txt").then(function(data){
  TCA.done(data);
}).catch(function (error) {  
  TCA.doneWithError(error);
});

TCA.doneWithError(error)

Finishes an asynchronous operation with an error.

Arguments

error. Any object can be used to stand for the error detail (any).

Return value

None

Example:

IOA.read(TC.scriptDir + "mylog.txt").then(function(data){
  TCA.done(data);
}).catch(function (error) {  
  TCA.doneWithError(error);
});

TCA.useAsyncAPI()

Notifies the execution engine that an asynchronous API will be invoked, so that the engine waits for completion notification.

Note: Generally there is no need to call this function because the execution engine knows to wait for asynchronous operation completion when the user calls an asynchronous API. Use this function only when an asynchronous API is invoked in an asynchronous execution block, such as setTimeout. This function should be called outside of an asynchronous execution block, preferably at the beginning of the whole JavaScript block.

Arguments

None

Return value

None

Example:

TCA.useAsyncAPI();
setTimeout(function() {
   IOA.read(TC.scriptDir + "mylog.txt").then(function(data){
     TCA.done(data); 
   }).catch(function (error) {  
     TCA.doneWithError(error);
   });

}, 1000);

Vuser functions

TCA.addNetworkFilter(filters, include, applyTo)

Adds a filter for URL requests.

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

Arguments

filters. Filter representing one or more URLs (string). 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; otherwise false (default). Optional argument (boolean).

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

Xhr. Filters XHR requests only.
NonXhr. Filters non-XHR requests only.
All. Filters all requests (default).

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

Return value

A promise that will be fulfilled with no arguments.

Example:

TCA.addNetworkFilter("http://www.myco.com/*", true, "All").then(function(){ 
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

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.myco.com/ prefix.

TCA.clearNetworkFilters()

Removes all URL request filters.

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

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.clearNetworkFilters().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.startLogRequests()

Starts logging URL requests.

Note: Relevant only for steps that have a Step completed or Step synchronous network completed end event, or that do not have any end event.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.startLogRequests().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.advanceParam(name)

Advances the specified parameter to the next value in the file. This must be a parameter of type file or unique number; this is the argument type set in VuGen.

Arguments

name. The name of the parameter to advance (string).

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.advanceParam("multi_row_param").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.getParam(name)

Returns the value of the specified parameter.

Arguments

name. The parameter name (string).

Return value

A promise that will be fulfilled with a string, which is the value of the specified parameter.

Example

TCA.getParam(“myParam”).then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

Note: You can also use parameters in the Step Arguments section of a TruClient script. For details, see Use parameters to vary arguments.

TCA.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 (string).

value. The parameter value (string).

Note: Only alphanumeric and the underscore character ("_") are supported.

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.setParam("myparam", "paramVal").then(function(){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.getUserIP()

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

Arguments

None

Return value

A promise that will be fulfilled with a string, which is the IP address when IP spoofing is enabled and the script is running in load mode in Controller.

Example

None

TCA.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 (string).

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.outputMessage("My output message").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.crossTransactionStart(name, identifier)

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

Arguments

name. The name of the transaction (string).

identifier. The identifier of the transaction (string). The same value is used by TCA.crossTransactionEnd(name, identifier, type) to identify the transaction.

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.crossTransactionStart("transactionName", "TransactionId").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.crossTransactionEnd(name, identifier, type)

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

Arguments

name. The name of the transaction (string).

identifier. The identifier of the transaction (string). The value of the parameter must be identical to the value of the identifier param that the Vuser initiating the transaction used in TCA.crossTransactionStart(name, identifier).

type. One of the following: "Pass", "Fail", "Auto", "Abort", or "Stop".

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.crossTransactionEnd("transactionName", "TransactionId", "Pass").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.transactionDuration(name)

Returns the duration of a specific transaction, in seconds.

Note: This API must be used within the scope of the transaction.

Arguments

name. The name of the transaction (string).

Return value

A promise that will be fulfilled with a string, which is the duration of a specific transaction, in seconds.

Example

None

TCA.startTransaction(name)

Starts a LoadRunner Professional transaction.

Arguments

name. (String) The name of the transaction to start.

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.startTransaction("login_tr1").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.setTransactionStatus(status)

Sets the default end status of open transactions.

Arguments

status. One of the following transaction status values: "Pass", "Fail". The "Auto" status is not applicable.

The TCA.setTransactionStatus function sets the default end status of currently open transactions which have "Auto" in their TCA.endTransaction(name, status) statement.

If you make a series of calls to functions that modify the "Auto" status, then it is the last call before TCA.endTransaction that effectively changes the status.

Return value (void)

A promise that will be fulfilled with no arguments.

Example

TCA.setTransactionStatus("Fail").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.setTransactionStatusByName(status, name)

Sets the default end status of a single open transaction by the transaction name.

Arguments

status. One of the following transaction status values: "Pass", "Fail". The "Auto" status is not applicable.

name. The name of the transaction to set.

The TCA.setTransactionStatusByName function sets the default end status of the transaction with the defined name. This transaction must have "Auto" in its TCA.endTransaction(name, status) statement.

If you make a series of calls to functions that modify the "Auto" status, then it is the last call before TCA.endTransaction that effectively changes the status.

Return value (void)

A promise that will be fulfilled with no arguments.

Example

TCA.setTransactionStatusByName("Fail", "T1").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.endTransaction(name, status)

Ends a LoadRunner Professional transaction.

Arguments

name. The name of the transaction to end (string).

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

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.endTransaction("login_tr1", status).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.evalC(funcname, functimeout)

Runs a specific function in C language, defined in the C-functions.c file.

Arguments

funcname. The function name (string).

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

functimeout. The maximum expected runtime, in seconds, of the function called by the step (number).

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.evalC("myFunc", 20).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.unmask(text)

Returns the text after unmasking.

Arguments

text. The masked text (string).

Return value

A promise that will be fulfilled with a string, which is the text after unmasking.

Example

TCA.unmask(str).then(function(result){ 
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.userDataPoint(name, value)

Records a user-defined data point for analysis.

Arguments

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

value. The numeric value (number).

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.userDataPoint("myDP", 1).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vuserStatusMessage(text)

Indicates which Vuser is handling a specific script.

Arguments

text. Any text string (string).

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.vuserStatusMessage("FlightStatus").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.log(text, level)

Logs a message as a line in TruClient’s interactive/load log.

Arguments

text. The message (string).

level. Optional argument. One of the following:

"Error"
"Warning"
"Standard" (default)
"Extended"
"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.
"Status_msg"

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.log("my warning", "Warning").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.setLogLevel(level, log_flags)

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

Arguments

level. Specify the log level:

"Disabled". Disables the log level. It still captures a log including the error level.
"Standard". Standard log captured.
"Extended". Extended log file captured.

log_flags. (Object) 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

Return value

A promise that will be fulfilled with no arguments.

Example

Disable the log level:

TCA.setLogLevel(“Set the log level to “Disabled”).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

Enable the standard log:

TCA.setLogLevel(“Standard”).then(function(){          
  TCA.done();     
}).catch(function (error) {           
  TCA.doneWithError(error);     
});

Enable the extended log:

TCA.setLogLevel(“Extended”).then(function(){          
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

Enable the extended log, and specify which logs to capture:

TCA.setLogLevel(“Extended”,{ log_http : true, log_AUT: true, log_parameters: true}).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.restoreLogLevel()

Restore log level to the initial setting.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.restoreLogLevel().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.stopLogRequests()

Stops logging URL requests.

Note: Relevant only for steps that have a Step completed or Step synchronous network completed end event, or that do not have any end event.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

TCA.stopLogRequests().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

Browser functions

TCA.setProxy(option, settings)

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

Arguments

option. Specify the type of proxy 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 a proxy auto-config (PAC) file.

settings. The details of the proxy setting (string).

Return value

A promise that will be fulfilled with no arguments.

Example

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.
```
TCA.setProxy("PROXY_SYSTEM", "").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});
```

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

TCA.setProxy("PROXY_MANUAL", '{"proxyShare":false,"proxyHttp":" proxy.xxx.com ","proxyHttpPort":8080,"proxySsl":" proxy.yyy.com ","proxySslPort":8080}').then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

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.
```
TCA.setProxy("PROXY_MANUAL", '{"proxyShare":true,"proxyHttp":"proxy.xxx.com","proxyHttpPort":8080}').then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});
```
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.
```
TCA.setProxy("PROXY_MANUAL ", "").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});
```
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).
```
TCA.setProxy("PROXY_NONE", "").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});
```

Use PAC.

TCA.setProxy("PROXY_PAC",'{"proxyPAC":"http://autocache.xyzcorp.net/"}').then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.addAutoFilter(url, isIncluded)

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

Arguments

url. String or regular expression representing the URL (string).

isIncluded. True to add the URL to allowlist, or false to add the URL to denylist (boolean).

Return value

A promise that will be fulfilled with no arguments.

Example

Set only the allowed domain on the allowlist. All other domains are blocked.

String example:

UtilsA.addAutoFilter("http://www.myco.com/*", true).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

Regular expression example:

UtilsA.addAutoFilter(/^http:\/\/www\.myco\.com\/.*/, true).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.cleanupAutoFilters()

Remove all filters from both the denylist and allowlist lists of URLs.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.cleanupAutoFilters().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.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 (string).

value. The value of the header to be added (string).

merge. "True" indicates to merge the value with an existing header by the same name; "false" indicates to overwrite it (boolean).

Note: Merge does not support modifying the following headers: "content-type", "content-disposition", "content-length", "user-agent", "referer", "host", "authorization", "proxy-authorization", "if-modified-since", "if-unmodified-since", "from", "location", "max-forwards"

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.addAutoHeader("someCustomHeader", "someValue", true).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.cleanupAutoHeaders()

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

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.cleanupAutoHeaders().then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.removeAutoHeader(header)

Removes an HTTP header added with Utils.addAutoHeader and stops adding this HTTP header to every consecutive HTTP request following this function call.

Arguments

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

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.removeAutoHeader("someCustomHeader").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.removeAutoFilter(filter, isInclude)

Remove a filter that was added using Utils.addAutoFilter from the denylist or allowlist of URLs.

Arguments

filter. String representing the URL.

isInclude. True value indicates the allowlist, false otherwise.

Remarks

Use the exact same filter URL value that was added to the list.

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.removeAutoFilter("http://www.myco.com/*", true).then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.clearCache()

Clears the cache of a single Vuser; the content of the whole cache simulator is unaffected.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

None

UtilsA.clearCookies()

Removes all cookies currently stored by the Vuser.

Arguments

None

Return value

A promise that will be fulfilled with no arguments.

Example

None

VTS functions

TCA.vtcAddCell(colName, value, vtsName)

Adds a new cell as the last field of a column to a value.

Equivalent method in LoadRunner Professional: lrvtc_send_message

Arguments

colName. The name of the column (string).

value. The value as a string (string).

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcAddCell("MyColumn","myValue","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcAddCells(colNames, values, option, vtsName)

Sets the data in multiple columns.

Equivalent method in LoadRunner Professional: lrvtc_send_row1

Arguments

colNames. The column names delimited by a semi-colon (string).

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

option. Define how the values are added (integer).

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 (string, optional).

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.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcAddCells("MyColumn1;MyColumn2;MyColumn2", "MyValue1;MyValue2;MyValue3", 0, "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcAddUniqueCell(colName, value, vtsName)

Sets the last field of a column to a value if the value does not exist in the column.

Equivalent method in LoadRunner Professional: lrvtc_send_if_unique

Arguments

colName. The name of the column (string).

value. The value (string).

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with a boolean: true if the value exists in the column, and false if the value does not.

Example

TCA.vtcAddUniqueCell("MyColumn",1,"MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcClearColumn(colName, vtsName)

Clears all data in a column.

Equivalent method in LoadRunner Professional: lrvtc_clear_column

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcClearColumn("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcClearCell(colName, rowIndex, vtsName)

Clears the data in a field.

Equivalent method in LoadRunner Professional: lrvtc_clear_message

Arguments

colName. The name of the column (string).

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

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcClearCell("MyColumn",1,"MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcClearRow(rowIndex, vtsName)

Clears the values from all fields in a row.

Equivalent method in LoadRunner Professional: lrvtc_clear_row

Arguments

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

VtsName. The alias of the VTS server (string, optional).

Remarks

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

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcClearRow(1,"MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcColumnSize(colName, vtsName)

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

Equivalent method in LoadRunner Professional: lrvtc_column_size

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with the number of fields in the column, or 0 if the column does not exist.

Example

TCA.vtcColumnSize("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcConnect(serverName, port, vtsName)

Creates a connection to the server (supports HTTP).

Equivalent method in LoadRunner Professional: lrvtc_connect

Note: To connect using HTTPS, basic or NTLM authentication, use TC.vtcConnectEx.

Arguments

serverName. Either the IP or server name (string).

port. The port number (integer).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcConnect("MyServer", 8888, "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcConnectEx(serverName, port, userName, password, domain, vtsName)

Creates a connection to the server (supports HTTP, HTTPS version VTS server, basic authentication based on user name and password entered by the user, and NTLM authentication).

Equivalent method in LoadRunner Professional: lrvtc_connect_ex

Arguments

serverName. Either the IP or server domain name (string). The protocol can be omitted; the default protocol is “https://”.

port. The port number (integer). The available range is 1-65535.

userName. The user name for basic or NTLM authentication (string, optional).

password. The password for basic or NTLM authentication (string, optional).

domain. The domain name for NTLM authentication (string, optional).

vtsName. The name of the VTS connection (string, optional).

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcConnectEx("MyServer", 8888, "MyUser", "MyPW", "MyDomain", "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcCreateColumn(colName, vtsName)

Creates a column.

Equivalent method in LoadRunner Professional: lrvtc_create_column

Arguments

colName. The name of the column (string).

VtsName. The alias of the VTS server (string, optional).

Remarks

If a column of the same name already exists, the function does nothing.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcCreateColumn("MyColumn","MyVTS").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcDisconnect(vtsName)

Disconnects from the server.

Equivalent method in LoadRunner Professional: lrvtc_disconnect

Arguments

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcDisconnect("MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcDropIndex(colName, vtsName)

Deletes the index on a column.

Equivalent method in LoadRunner Professional: lrvtc_drop_index

Arguments

colName. The column name (string).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcDropIndex("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcEnsureIndex(colName, vtsName)

Creates an index on a column.

Equivalent method in LoadRunner Professional: lrvct_ensure_index

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcEnsureIndex("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcGetCell(colName, rowIndex, vtsName)

Returns the data in a field.

Equivalent method in LoadRunner Professional: lrvtc_query_column

Arguments

colName. The name of the column (string).

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

vtsName. The alias of the VTS server (string, optional).

Return value

If data exists in the column and row specified, returns a promise that will be fulfilled with a string, which is the data in the specified cell.

If specified index does not exist, returns a promise that will be fulfilled with no arguments.

Returns a promise that will be fulfilled with Null if specified column does not exist.

Example

TCA.vtcGetCell("MyColumn",1,"MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.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 Professional: lrvtc_query_row

Arguments

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

vtsName. The alias of the VTS server (string, optional).

Remarks

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

Return value

A promise that will be fulfilled with an object, which is the field from the specified index in all columns. If the column does not have a value in the specified index, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TCA.vtcGetRowCells(1,"MyVTS").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcIncrement(colName, rowIndex, value, vtsName)

Increments a counter stored in a field.

Equivalent method in LoadRunner Professional: lrvtc_increment

Arguments

colName. The name of the column (string).

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

value. The value.

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with 0 if completed successfully; with no arguments if on error.

Example

TCA.vtcIncrement("MyColumn",1,1,"MyVTS").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcPopCell(colName, vtsName)

Pops the first field from a column.

Equivalent method in LoadRunner Professional: lrvtc_retrieve_message

Arguments

colName. The name of the column (string).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with a string, which is the value of the first index in the column row, or with null if the column is empty or does not exist.

Example

TCA.vtcPopCell("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcPopCells(vtsName)

Pops the data in a row as a JavaScript object.

Arguments

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with an object, which is the first field from the columns. If the column is empty, the value is null. Example: {col1:”larry”,col2:null}

Example

TCA.vtcPopCells( "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.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 Professional: lrvtc_retrieve_messages1

Arguments

colNames. The names of the columns (string).

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with an object, which is the first field from the specified columns. If the column is empty, the value is null. Example: {col1:”larry”,col2:null}

Example

TCA.vtcPopMultipleCells("MyColumn","MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcRotateCell(colName, option, vtsName)

Retrieves the first field from the specified column and moves the values to the bottom.

Equivalent method in LoadRunner Professional: lrvtc_rotate_messages

Arguments

colName. The name of the column (string).

option. Define how the values are rotated (integer).

1. Add as stack - Retrieve data from column, and move it to the bottom to the last valid row of every column.
2. Add as unique stack - Retrieve data from column, and move it to the bottom to the last valid row if the data is unique.

vtsName. The alias of the VTS server (string, optional).

Remarks

If the column name does not exist, null value will be retrieved.

Return value

A promise that will be fulfilled with an object, which is the first field from the specified column. If the column is empty, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TCA.vtcRotateCell("MyColumn1", 0, "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcRotateCells(option, vtsName)

Retrieves the first field from all columns and moves the values to the bottom.

Equivalent method in LoadRunner Professional: lrvtc_rotate_row

Arguments

option. Define how the values are rotated (integer).

0. Same row – Retrieve data from all columns and move it to the bottom for 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 - Retrieve data from all columns and move it to the bottom to the last valid row of every column.
2. Add as unique stack - Retrieve data from all columns and move it to the bottom to the last valid row of every column only if the data is unique.

vtsName. The alias of the VTS server (string, optional).

Remarks

If there is no data in a row, null value will be retrieved.

Return value

A promise that will be fulfilled with an object, which is the first field from the columns. If column is empty, the value is an empty string. Example: {col1:”larry”,col2:””}

Example

TCA.vtcRotateCells (0, "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcRotateMultipleCells(colNames, option, vtsName)

Retrieves the first field from the specified columns and moves the values to the bottom.

Equivalent method in LoadRunner Professional: lrvtc_rotate_messages1

Arguments

ColNames. The column names delimited by a semi-colon (string).

option. Define how the values are rotated (integer).

0. Same row – Retrieve data from all columns and move it to the bottom for 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 - Retrieve data from all columns, and move it to the bottom to the last valid row of every column.
2. Add as unique stack - Retrieve data from all columns, and move it to the bottom to the last valid row of every column if the data is unique.

vtsName. The alias of the VTS server (string, optional).

Remarks

If the column name does not exist, null value will be retrieved.

Return value

A promise that will be fulfilled with an object, which is the first field from the specified columns. If the column is empty, the value will be an empty string. Example: {col1:”larry”,col2:””}

Example

TCA.vtcRotateMultipleCells("MyColumn1;MyColumn2;MyColumn2", 0, "MyVts").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TC.vtcSearchRow(columns, values, delimiter, vtsName)

Searches for a row containing specific values in specific columns.

Equivalent method in LoadRunner Professional: lrvtc_search_row

Arguments

columns. The names of the columns to search. The column names are separated by the delimiter.

values. The values of the columns to search. The values are separated by the delimiter.

delimiter. The character that separates the column names and values in the lists. If a string, rather than a single character, is passed in delimiter, the string as a whole is the delimiter.

VtsName. The alias of the VTS server.

Remarks

If the column specified in the argument does not exist, the return value is 0. If more than one row meets the condition, the data from only one random row is returned.

Return value (number)

0: If API call was successful but no row is found.

1: If API call was successful and the row is found.

On call failure, it returns the error code.

Example

TC.vtcSearchRow("col1,col2", "a,b", ",", "test");

TCA.vtcUpdateAllMessageIfequals(colNames, Message, Ifmessage, Delimiter)

Replaces a specific value inside a set of columns with a new value.

Equivalent method in LoadRunner Professional: lrvtc_update_all_message_ifequals

Arguments

ColNames. The column names delimited by a semi-colon (string).

Message. New value inside a set of columns (string).

Ifmessage. Original value inside a set of columns (string).

Delimiter. Delimiter to separate column names. By default, the separator value is a semi-colon (;).

Return value

A promise that will be fulfilled with a number, which is 0 if completed successfully. On error returns a promise that will be fulfilled with no arguments.

Example

TCA.vtcUpdateAllMessageIfequals("MyColumn1;MyColumn2;MyColumn3", "NewVal1;NewVal2;NewVal3", "OldVal1;OldVal2;OldVal3").then(function(result){  
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcUpdateCell(colName, rowIndex, value, vtsName)

Replaces the data in a field.

Equivalent method in LoadRunner Professional: lrvtc_update_message

Arguments

colName. The name of the column (string).

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

value. The value (string).

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with a number, which is 0 if completed successfully. On error returns a promise that will be fulfilled with no arguments.

Example

TCA.vtcUpdateCell("MyColumn",1,"MyValue","MyVTS").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcUpdateEqualsCell(colName, rowIndex, value, comparedValue, vtsName)

Replaces the data in a field if the current data equals a given value.

Equivalent method in LoadRunner Professional: lrvtc_update_message_ifequals

Arguments

colName. The name of the column (string).

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

value. The replacement value (string).

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

vtsName. The alias of the VTS server (string, optional).

Return value

A promise that will be fulfilled with an boolean: false if a field with the same value exists, and true if there is no field with the same value in the column.

Example

TCA.vtcUpdateEqualsCell("MyColumn",1,"MyValue","MyCompareValue",MyVTS").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

TCA.vtcUpdateRowCells(colNames, rowIndex, values, vtsName)

Replaces the data in multiple fields.

Equivalent method in LoadRunner Professional: lrvtc_update_row1

Arguments

ColNames. The column names delimited by a semi-colon (string).

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

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

vtsName. The alias of the VTS server (string, optional).

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.

Return value

A promise that will be fulfilled with a number, which is 0 if completed successfully. On error returns a promise that will be fulfilled with no arguments.

Example

TCA.vtcUpdateRowCells("MyColumn1;MyColumn2;MyColumn2", 0, "MyNewValue1;MyNewValue2;MyNewValue3", "MyVts").then(function(result){
 TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

Environment functions

TCA.getAttr(name)

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

Arguments

name. The name of the command-line parameter (string).

The command-line parameter name is generally assigned by the user in the Additional Attributes tab in VuGen > Runtime 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.

Return value

A promise that will be fulfilled with a string, which is the value of the command line parameter passed to the test or the default value set for it.

Example

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

TCA.getAttr(“MyServerURL”).then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

IOA.createDir(path)

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

Arguments

path. The absolute path of the folder (string).

Return value

A promise that will be fulfilled with no arguments.

Example

IOA.createDir(TC.outputDir + "mydir").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

IOA.delete(path)

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

Arguments

path. The absolute path of the folder or file (string).

Return value

A promise that will be fulfilled with no arguments.

Example

IOA.delete(TC.outputDir + "mydir").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

IOA.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.

Arguments

path. The absolute path of the folder or file (string).

Return value

A promise that will be fulfilled with a boolean: true if file exists, and false if it does not.

Example

IOA.isExist(TC.outputDir + "mydir").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

IOA.read(filename, charset)

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

Arguments

filename. The absolute path of the file (string).

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

Return value

A promise that will be fulfilled with a string, which is all the data from the specified file.

Example

IOA.read(TC.scriptDir + "mylog.txt").then(function(data){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

IOA.write(filename, input, append, charset)

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

Arguments

filename. The absolute path to the file (string).

input. The string to write to the file (string).

append. (boolean)

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

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

Return value

A promise that will be fulfilled with a boolean which is always true.

Example 1

IOA.write(TC.scriptDir + "mylog.txt", "first msg\n", false).then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

Example 2

IOA.write(TC.scriptDir + "mylog.txt", "second msg").then(function(result){
  TCA.done(result);
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.getEnv(name)

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

Arguments

name. The name of the environment variable (string).

Return value

A promise that will be fulfilled with a string, which is the value of the specified environment variable.

If the specified value does not exist, returns a promise that will be fulfilled with no arguments.

Example

UtilsA.getEnv("PATH").then(function(path){
  TCA.done(path);
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.import(filename)

Evaluates the specified JavaScript file in the arguments context.

Arguments

filename. The absolute path to the JavaScript file (string).

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.import(TC.scriptDir + "myjs.js").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.isEnvExists(name)

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

Arguments

name. The name of the environment variable (string).

Return value

A promise that will be fulfilled with a boolean: true if the specified environment variable exists, and false if it does not exist.

Example

UtilsA.isEnvExists("PATH").then(function(exist){
  TCA.done(exist);  //exist is true
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.isEnvExists("TC_kukuku").then(function(exist){
  TCA.done(exist);   //exist is false
}).catch(function (error) {
  TCA.doneWithError(error);
});

UtilsA.setEnv(name, value)

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

Arguments

name. The name of the environment variable (string).

value. The value to which to set the environment variable (string).

Return value

A promise that will be fulfilled with no arguments.

Example

UtilsA.setEnv("PATH", "C:\\loadrunner\\").then(function(){
  TCA.done();
}).catch(function (error) {
  TCA.doneWithError(error);
});

TruClient step arguments
TruClient properties

Asynchronous functions

General notes on using TruClient functions

General functions

Vuser functions

Browser functions

VTS functions

Environment functions

Send Help Center Feedback