Using the VuGen JavaScript engine

Applies to: Web - HTTP/HTML and SAP - Web Vuser scripts written in C only.

What is the VuGen JavaScript engine?

Typically, Web Vuser scripts contain C code. The built-in JavaScript engine enables you to insert snippets of JavaScript code into the C code.

What can I do with JavaScript in a Vuser script?

You can insert JavaScript code into a Web - HTTP/HTML or SAP - Web Vuser script to manipulate text strings that are included in the request and response messages that are sent between the client and server. Manipulating strings is often useful for correlation and parameterization purposes. Typical string manipulations include converting decimal to hexadecimal, encoding and decoding Base64, URL encoding and decoding, and accessing object values inside JSON-formatted data.

Note: It is possible to perform many of these string manipulation procedures by using the built-in DFEs (Data Format Extensions). For details, see Data format extensions (DFEs) overview.

Inserting JavaScript code into a Vuser script may also be useful when client-side logic is implemented in JavaScript. Inserting snippets of the original client-side JavaScript code into the Vuser script removes the requirement of having to re-write the JavaScript logic into C code to be included in the Vuser script.

You can use JavaScript code in a Vuser script to execute an XMLHTTPRequest. This allows you to generate and send HTTP or HTTPS requests using standard Javascript APIs. Such APIs include, for example, sending asynchronous requests, assigning callbacks to handle responses, reading responses in XML format. An XMLHTTPRequest used this way may replace a call to an action step such as web_url or web_custom_request.

Back to top

Why use JavaScript snippets?

Although it may be possible to achieve the required functionality by using C code alone, including JavaScript in a Vuser script may be beneficial for the following reasons:

  • JavaScript often offers a more intuitive, easier to implement solution than C.
  • The JavaScript regular expression library simplifies the challenge of working with regular expressions.
  • There are numerous JavaScript libraries that assist with string manipulation.
  • Client-side logic is often implemented in JavaScript. Inserting snippets of the original JavaScript code removes the requirement of having to translate the JavaScript client logic into C code.

Back to top

Can I use the JavaScript engine in Vuser scripts of all protocols?

No, the JavaScript engine enables you to insert JavaScript into Web - HTTP/HTML and SAP - Web Vuser scripts only.

Back to top

What are some scenarios in which the JavaScript engine may be useful?

Including JavaScript code in a Vuser script may be useful in the following scenarios:

In this scenario, the response that a Vuser sends to the server must include a 13-digit timestamp in hexadecimal format. For example, the date/time stamp "1234567891234" must be converted by the Vuser into hex and sent as "11F71FB0922". LoadRunner Professional does not include any standard functionality to perform this conversion, and developing the required C code is not trivial. This problem can be resolved by inserting the following JavaScript code into the Vuser script:

Copy code 
web_js_run("Code= myFunc(1, 2);",
    "ResultParam=Sum",
    SOURCES,
    "Code= var myFunc = function(x,y) { return x+y; }", ENDITEM,
    LAST);

The request and response messages that are sent between the client and server include data that is encoded using a Base64 coding scheme. Because the data is encoded, it is often difficult or impossible to parameterize or correlate the raw data. The data must be decoded before it can be parameterized or correlated, and then re-encoded before being sent to the server. By including JavaScript snippets in a Vuser script, you can access external JavaScript libraries that implement the required Base64 decoding and encoding functionality.

Note: It is possible to implement Base64 decoding and encoding using the built-in Base64 DFE (Data Format Extension). For details, see Data format extensions (DFEs) overview.

In this scenario, the request and response messages that are sent between the client and server include URLs that are encoded using JavaScript URL encoding. By including a JavaScript snippet in a Vuser script, you can access the JavaScript encodeURI() and decodeURI() functions that perform the required decoding and encoding procedures.

Note: It is possible to implement URL decoding and encoding using the built-in URL Encoding DFE (Data Format Extension). For details, see Data format extensions (DFEs) overview.

In this scenario, the request and response messages that are sent between the client and server include data in JSON format. To access objects inside the JSON formatted data, you can include a JavaScript snippet inside the Vuser script to access the JavaScript eval() function.

Note: It is possible to access objects inside JSON-formatted data by using the built-in JSON-To-XML DFE (Data Format Extension). For details, see Data format extensions (DFEs) overview.

You can use JavaScript code in a Vuser script to execute an XMLHTTPRequest to download stock quotes from a specified site. For an example of how to execute an XMLHTTPRequest, see JavaScript Engine: XMLHTTPRequest example.

To access a particular website, the Vuser must submit a user name and an encrypted password. The server sends a server hash to the browser to enable the browser to generate the required encrypted password. The code to generate the hash is complicated, and exists in JavaScript. This JavaScript code can be included in the Vuser script, removing the requirement to re-write the JavaScript logic into C code.

Back to top

What are the API functions that I can use in a Vuser script to execute Javascript code?

The following API functions are available for including JavaScript in a Vuser script:

  1. web_js_run: Runs the specified JavaScript code.

  2. web_js_reset: Clears the JavaScript context.

You use the web_js_run function to include JavaScript code in a Vuser script. Using the web_js_run function, you can either insert the required JavaScipt code into the Vuser script, or you can reference a file that contains the required JavaScript code.

The following is an example of how to include JavaScript code directly from the Vuser script:

web_js_run(
	"Code=xor((LR.getParam('buffer'), 0xFFFF));",
	"ResultParam=param",
LAST);

The following is an example of how to include JavaScript code by calling a file that contains the JavaScript code:

web_js_run(
	"File=XMLHTTPRequest_sync_sample.js;",
	"ResultParam=param",
LAST);

For details on the above functions, and examples of how they can be used, see the Function Reference (select the relevant version).

Back to top

Can I use JavaScript to access any "internal" API functions?

JavaScript in a Vuser script gives you access to a number of "internal" API functions that can be called directly from a web_js_run function in the JavaScript code. These functions are used primarily for managing parameters, but also enable you to log specified messages, record data, and run XMLHTTPRequest.

API Function Description Arguments
LR.advanceParam
(parameter)
Advances the specified parameter to the next value in the file.
parameter. The name of the parameter to advance. Must be a parameter of type file or unique number.
LR.setParam(name, value)
Saves a string to a parameter, creating the parameter if it does not exist.
name. The name of the parameter in which to save the value.
value. The value.
LR.freeParam(name) Deletes a dynamic parameter at runtime, freeing its buffer.
name. The parameter name.
LR.getParam(name)
Returns the value of the specified parameter.
name. The parameter name.
LR.log(text, level)
Logs a message.
text. The message.
level. One of the following:

  • "Error"

  • "Warning"

  • "Standard"

  • "Extended"

  • "Status"

example: LR.log("text", "Error");
LR.userDataPoint(name, value)
Records a user-defined data point for analysis.
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.

Back to top

How do I enable the Javascript engine for Vusers?

To run JavaScript from within a Vuser script, you must enable the JavaScript engine for the Vuser script. To enable the JavaScript engine, open the Replay > Runtime Settings > Internet Protocol > Preferences view. Go to the JavaScript section and select the Enable running JavaScript code option.

Note: Enabling this option causes the creation of a JavaScript Runtime engine, even if there are no JavaScript steps in the script.

Back to top

How do I configure the JavaScript engine?

You use the Vuser script's runtime settings to configure the product's custom JavaScript engine.

To access the JavaScript engine (JSE) runtime settings, select Replay > Runtime Settings > Internet Protocol > Preferences, and expand the JavaScript section.

  • JavaScript Engine runtime size: Specifies the size of the allocated JavaScript engine Runtime memory, in kilobytes. This value may need to be increased when running a large number of Vusers.
  • JavaScript Engine stack size per-thread: Specifies the size of each Vuser thread in the JavaScript engine memory, in kilobytes. This value may need to be increased for large objects or deep stack calls.

For user interface details, see Preferences view - Internet protocol.

Back to top

What is the connection between the VuGen's JavaScript engine and VuGen's JavaScript protocol?

There is no connection between VuGen's JavaScript engine and VuGen's JavaScript Protocol.

Back to top

Troubleshooting

If you encounter difficulties when implementing JavaScript engine support, review the items below for possible solutions.

  1. Make sure that VuGen's JavaScript engine is enabled. For details, see How do I enable the JavaScript Engine?
  2. Javascript limits you to adding up to 9,000 operands in one function. For example, if you are combining strings, "str1"+"str2"+"str3"+..."str9000", you can only add up to 9,000 strings.

  3. Memory issues

    • If the Simulate a new user on each iteration > Clear cash on each iterationruntime setting is selected, web_js_reset is called automatically at the start of each iteration.
    • If Simulate a new user on each iteration > Clear cash on each iteration is not set, avoid excessive memory consumption by inserting web_js_reset calls in your Vuser script at points where you no longer need the saved context.

    For details on the runtime settings, see the hints below the option in the runtime settings view.

  4. Performance issues

    If you are experiencing performance issues, modify the JavaScript runtime settings. For details, see Preferences view - Internet protocol.

Back to top