TruWeb scripts

This topic describes the TruWeb script structure.

You write TruWeb scripts using the TruWeb JavaScript SDK. You can write standard JavaScript code as part of your script, or reuse any other pure (for example, third party) JavaScript file.

You can use a variety of IDEs or text editors to build and test your TruWeb script. For more information, see Build TruWeb scripts.

TruWeb script files

The TruWeb script folder includes the following files:

Tip: A template script folder, EmptyScript, is available in <TruWeb_installation folder>\examples.

  • main.js. Contains the code of the script.

  • scenario.yml. Responsible for the TruWeb scenario settings when running a TruWeb script in load mode. For details, see Run TruWeb scripts.

    Note: This file is used for the standalone version of TruWeb only. When running a test in LoadRunner or Performance Center, the scenario is defined in the testing tool itself.

    Example of a scenario.yml file:

    # All times are defined in seconds
    vusers: 1        #The number of Vusers that will be run during the test
    pacing: 2        #The number of seconds to wait between iterations of each Vuser
    rampUp: 2        #The number of seconds it will take to start all the Vusers
                     #The starting of Vusers that will be distributed equally throughout this time frame
    duration: 20     #The number of seconds to run Vuser iterations after all the Vusers have started running
    tearDown: 0      #Not used
    
  • rts.yml (optional). TruWeb is installed with default runtime settings for TruWeb test runs. The runtime settings are specific to each Vuser, such as logger or proxy settings. You can see descriptions of the runtime settings alongside each setting. This file is called rts.yml, and resides in the TruWeb installation folder.

    If you want to customize these settings, you can do so in a local runtime settings file that you create in the script's folder. When the script runs, the customized runtime settings take precedence over the default runtime settings. To customize:

    1. Copy rts.template.yml from your TruWeb installation folder to your script's folder, and rename it rts.yml.
    2. Customize the copied file and save your changes.
  • parameters.yml (optional). Contains parameters for your script. This file is optional and is user-defined in the script's folder.

    The parameters file defines the parameters that can be used in the script and various aspects of how and when new values are retrieved.

    Parameter Description
    name

    The name of the parameter that can later be used in the code.

    type

    The type of data source for the parameter.

    Supported type: CSV, a comma-separated table of values where each column represents one parameter. The CSV must contain a header row defining the names of the columns.

    fileName

    The name of the CSV file in the script folder that contains the parameter data.

    columnName The name of the column (in the CSV file) from which to draw the values for the parameter that it represents - defined in the first row of the CSV file.
    nextValue

    The logic used to know when to collect the next value, determined as follows:

    •  once. The value is retrieved only once per the entire test run, and remains the same value throughout the run.

    • iteration. A new value is retrieved per each iteration and remains the same value throughout the iteration.
    • always. The value is retrieved every time the parameter is used.
    nextRow

    The logic used to know how to select the next value, determined as follows:

    • sequential. The next value is the value directly following the current value in the same column.

    • random. The next value is a random value from the same column.
    • same as <parameter name>. The next value is taken from the same row as the current value of <parameter name>. This is useful, for example, when matching a password for a username.

      When same as <parameter name> is used, nextValue and onEnd are ignored.

    • unique. The next value is chosen from a unique block within the parameters file that is unique to the current Vuser. To control the size of the block, set the blockSize parameter (see below).
    blockSize

    Used only when nextRow (above) is set to unique.

    •  auto. The block size is automatically calculated by the engine based on the total number of Vusers scheduled to run. Relevant only when running your script using the standalone version of TruWeb (single or load mode). See Run TruWeb scripts.
    •  <number>. The size of the block.
    onEnd

    Determines what happens when all the values have been used but the script still needs more values.

    • loop. The first value is used as the next value.

    If this property is left undefined, an error will be reported.

Example of a parameters.yml file:

parameters:                     #The parameters header, it must be the first line of the file
  - name: myParam1              #The name of the parameter that can later be used in the code
    type: csv                   #The type of the data source of the parameter. The valid values are: csv 
    fileName: myParam1.csv      #The name of the file that has all the values for this parameter
    columnName: Column1             #The column name used to draw values for this parameter
    nextValue: iteration        #The logic used to know when to retrieve new values
    nextRow: sequential         #The logic used to know how to retrieve new values
    onEnd: loop                 #What happens when there are no more values remaining and the script needs another value
  - name: myParam2              #Another parameter...
    type: csv
    fileName: myParam1.csv
    columnName: Column2
    nextValue: iteration
    nextRow: sequential
    onEnd: loop
  - name: myParam3 //Another parameter...
    type: csv
    fileName: myParam1.csv
    columnName: Column3
    nextValue: iteration
    nextRow: same as myParam2
    onEnd: loop
  - name: myParam4 //Unique parameter...
    type: csv
    fileName: myParam1.csv
    columnName: Column4
    nextValue: always
    nextRow: unique
    blockSize: 5
    onEnd: loop
  • transactions.yml (optional). For StormRunner Load users only.

    To enable the SLA feature of StormRunner Load, populate this file with a list of transaction names for which to calculate the SLA.

    Note: The script must contain transactions with matching names

    Format the list as shown in the following example, where two transactions are defined, named foo and bar:

    - name: foo

    - name: bar

 

Back to top

main.js layout

This section describes the layout of the main.js file.

main.js can contain three types of sections: initialize, action, and finalize. These can appear more than once and are executed in the order that they appear in the script.

initialize

(optional)

Executed only once at the beginning of the script.

action

(mandatory)

Executed in iterations throughout the duration of the script.

Note: The script must contain at least one action section.

finalize

(optional)

Executed only once at the end of the script, when all the action sections are finished running.

The following is an example of a typical TruWeb script that sends an HTTP request to a server and then uses some values from the response to determine if the transaction around that HTTP request has passed.

load.action("Main", () => { //(A)

  const productTransaction = new load.Transaction("Product"); //(B)

  productTransaction.start(); //(C)
  const myPageRequest = new load.WebRequest({ //(D)
	url: "http://myServer.com/main/product.html", //(E)
	method: "GET",
	returnBody: true,
	headers: {
	   "Accept-Language": "en-US,en;q=0.8",
	   "Accept-Encoding": "gzip, deflate, sdch",
	   "Accept": "*/*"
	},
	resources: [
	   "http://my.server.net/sources/Caching/oldnavy.css"
	]
  });

  const myPageResponse = myPage.sendSync(); //(F)

  /*Expected result is :
  <html>
     <body>
	<h1>My product</h1>
	<span productId="12">Very nice product</p>
     </body>
  </html>
  */

  const productId = load.utils.getByBoundary(myPageResponse.body,'productId="','"'); //(G)
  if (productId === null){ //(H)
     productTransaction.stop(load.TransactionStatus.Failed);
  }  else {
     productTransaction.stop(load.TransactionStatus.Passed);
  }
});

The flow:

  1. Declare a new action (A), Main, with a function containing all the code that will be executed as part of this action.

    Note:  

    • All the elements of the SDK are within the load namespace (object), therefore the load. prefix is needed to access them.
    • The action name is mandatory and used internally only.
  2. Declare a new transaction (B), Product, and store it in the productTransaction variable. This variable allows for obtaining information about the transaction and performing operations on it.
  3. Start the transaction (C).
  4. Declare a web request using the WebRequest constructor (D). The WebRequest constructor takes an object that configures the web request.

    For example, you can declare the URL for the web request (E). You can also set other properties for the request such as the header and extra resources. See WebRequest in the TruWeb JavaScript SDK.

  5. Send the request synchronously (F). The script stops and waits to receive a response, and stores the response in the myPageResponse variable. Because the returnBody property is set to true in the web request options, you can access the full response body.
  6. Use the getByBoundary function (G) to extract the product ID from the response. Using the product ID (H), you can determine if the Product transaction should pass or fail.

Back to top

Third party modules and libraries

You can load third party Common.js-type modules via the require() function.

Load an external module in one of the following ways:

Loading a single file

You can load a single file written in Common.js format by copying the file into the script folder and requiring it.

For example, if the file is myLibrary.js and it is in the script folder, add the following line to the script:

const myLibrary = require('./myLibrary.js');

Loading an npm module

You can load an npm module as long as it can run on any JavaScript runtime (namely, a browser).

To use this method, Node.js must be installed on your computer.

For example, use the following procedure to install the lodash library (https://www.npmjs.com/package/lodash) :

  1. Open the command prompt and navigate to the script folder.

  2. Type npm install lodash and wait for the process to finish. The node_modules folder is created in the script folder.

  3. In your script, add the following line: (Do not add the .js extension)

    const lodash = require('lodash');

Tip: If Node.js is not installed, you can download an npm module using standalone npm or using a third party package manager such as Yarn.

Managing multiple modules via package.json (advanced use case)

If you are using multiple third party npm modules and want to manage their dependencies, you can create a package.json file and manage all the dependencies with npm.

To use this method, Node.js must be installed on your computer.

  1. Create the package.json file using the npm init command as follows:

    1. Open the command prompt and change to the script folder.

    2. Type npm init --yes and wait for the process to finish.

  2. To install any supported package, type npm install <packagename> and wait for the process to finish. The node_modules folder is created in the script folder.

  3. In your script, add the following line (Do not add the .js extension):

    const <packagename> = require('<packagename>');

Tip: If Node.js is not installed, you can download an npm module using standalone npm or using a third party package manager such as Yarn.

Back to top

See also: