Data Sources

Many tests require special test data. We provide multiple options to extend your otherwise static tests using data sources:

1. Random Numbers
2. Random Strings
3. File Fixtures (structured and raw)

You can define and access data sources inside your sessions using functions exposed under session.dataSources or session.ds. The following examples will use the shorthand form for brevity.

Random Numbers

random_number will generate a uniformly distributed number within a given range:

// Step1: Define the random number generator
var productIds = session.ds.define("random_number", {
  range: [1000, 2000],
  name: "productIds", // Optional identifier for later debugging usage
});

// Step2: Generate and use number in request
session.post("/order", {
  payload: {
    productId: session.ds.generateFrom(productIds)
  }
});

There is also an equivalent shorthand-version for one-time generators:

session.post("/order", {
  payload: {
    productId: session.ds.generate("random_number", { range: [0, 999] })
  }
});

Note that the range is inclusive: [1,3] can generate the numbers 1, 2 and 3.

Random String

random_string will generate a random alpha-numeric string with the specified length. This can be useful if you need some kind of token:

// Step1: Define the random string generator
var token = session.ds.define("random_string", {
  length: 42,
});

// Step2: Generate and use string in request
session.post("/submit", {
  payload: {
    token: session.ds.generateFrom(token)
  }
});

There is also an equivalent shorthand-version for one-time generators:

session.post("/submit", {
  payload: {
    token: session.ds.generate("random_string", { length: 42 });
  }
});

There are also more specific functions to generate random strings, e.g. UUIDs.

Structured Files (CSV)

Structured files are served from a previously uploaded file (e.g. Character Separated Values, “CSV”). We recommend using tabs for separating values, but an export from Excel should work fine as well.

Please note:

• files must be ASCII or UTF-8 encoded
• all lines must have the same number of columns

After uploading a structured file, you can define names for columns which you can use as reference in your test cases.

Uploading

1. Upload a new data source file and select CSV/structured as file type. You can also choose a delimiter and whether to parse the first row as field names
2. Provide a unique name for later reference in your test cases
3. Check the First row in CSV contains field names if you have a header line defined. Header names must only contain lower case alphanumeric characters and underscore (a-z, 0-9? and _).

After clicking upload, you can change/update the field names for later reference in your test cases.

Usage

To use the data source in your test case definition, you have to call two functions: session.ds.loadStructured() and session.ds.pickFrom().

1. session.ds.loadStructured(datasourceName) returns a handle to the data source during runtime. The datasourceName parameter must match the name defined when uploading the data source.

2. session.ds.pickFrom(handle, [options]) picks a row from the data source. handle is the return value of loadStructured(). options allow further customization how to pick a row and is optional.

   For now, only the mode option is available. The modes random (default if not provided), once and exclusive are available.

   See Picking Modes below for clarification on the different modes.

3. row.get(columnName) returns a placeholder for the value of the columnName column. row must be obtained via pickFrom() as explained above.

   The placeholder can be used in all places where you actually want to send the value. It will be replaced during the test run execution with the actual value. See the Javascript Runtime for more details.

Picking Modes

The mode parameter supports the following behaviors:

• random (default) picks a random row out of the whole dataset
• once ensures that any row picked via once will not be returned ever again during this test run when using mode once or exclusive
• exclusive blocks the picked row from being used by other sessions / users at the same time while the session that picked the row is still alive

Note that once and exclusive share a pool of available rows. While exclusive returns the row to the pool at the end of session, once consumes it. If no rows are available, the session/user will be aborted and this will be reported in the report as DataSource is exhausted.

Example: You may want to choose random when selecting a product out of a catalog, once when using onetime signup codes and exclusive for user logins.

Example

Given a CSV file with the following contents, the name users.csv and field names id, email and password are parsed from the CSV.

id,email,password
1,user1@example.com,super-secret
2,user2@example.com,funwithflags

To fetch a random user row for a login in your test case you can use the following code snippet:

definition.session("login only", function(session) {
  var users = session.ds.loadStructured("users.csv");
  var user = session.ds.pickFrom(users, {mode: "exclusive"});

  session.post("/user/login", {
    payload: JSON.stringify({
      email: user.get("email"),
      password: user.get("password"),
    })
  });
});

Raw Files

We also support raw files through file uploads.

Usage

1. Upload a file and select Raw as file type.
2. Provide a unique name for the uploaded file.

To use the raw file for an upload you need to load and set the raw file as a payload_from_file parameter in your request options:

session.put("/user/profile_picture", {
  payload_from_file: session.ds.getRawFile("picture.png"),
});