Data Sources

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

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

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"/order", {
  payload: {
    productId: session.ds.generateFrom(productIds)

There is also an equivalent shorthand-version for one-time generators:"/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"/submit", {
  payload: {
    token: session.ds.generateFrom(token)

There is also an equivalent shorthand-version for one-time generators:"/submit", {
  payload: {
    token: session.ds.generate("random_string", { length: 42 });

There are also more specific functions to generate random strings, e.g. for 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.


  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.

Note: You can also manage your data-sources with our forge CLI.


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 the value of the columnName column. row must be obtained via pickFrom() as explained above.

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 choose random when selecting a product out of a catalog, once when using onetime signup codes and exclusive for user logins.

You should never rely on the order picked values! Currently the order of items will be the same as in the uploaded source. But the pool of rows is also partitioned across the test cluster, thus different nodes will pick different rows.


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


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"});"/user/login", {
    payload: JSON.stringify({
      email: user.get("email"),
      password: user.get("password"),

Raw Files

We also support raw files e.g. to for file uploads.


  1. Upload a file and select Raw as file type.
  2. Provid 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"),


On March the 31th of 2020 all legacy data sources have been automatically archived. The following examples should help you to migrate the data source API in your test case.

In 2018 we introduced a new way to manage your file-based data sources. Also the API in your test cases has been changed to generate random data from data sources.

Before this change you would define a data source in a global configuration block like this:

  nonce: {
    type: "random_number", range: [1, 100],

  user: {
    type: "file",
    source: "authentication/admin_users.csv",
    fields: ["id", "username", "password"],
    delimiter: ","

definition.session("user registration", function(session) {
  // ...

And you could use the defined data sources like this:

definition.session("user registration", function(session) {
  var user = session.pick("user");"/user/login", {
    payload: JSON.stringify({
      login: user.username(),
      password: user.password(),
      nonce: session.pick("nonce")


The new API works a bit different. Instead of defining fields and delimiter in your test case you can now define this per uploaded structured file. It is no longer required to define all data sources outside of your sessions beforehand. This makes it simpler to copy and move session definitions around for example.

Using these new structured data sources works like this:

definition.session("user registration", function(session) {
  // create a reference to the uploaded data source
  var users = session.ds.loadStructured("authentication/admin_users.csv");

  // pick a random entry
  var user = session.ds.pickFrom(users);"/user/login", {
    payload: JSON.stringify({

      // reference fields by their defined aliases
      email: user.get("email"),
      password: user.get("password"),

      // generate a random number ad-hoc
      nonce: session.ds.generate("random_number", { range: [1, 100] })

Icon Support Are you stuck? Or do you have any feedback? Get in touch with us – we are happy to help you.
Icon Schedule a demo Schedule a personal, customized demo. We'll show you around and introduce you to StormForger.
Icon Talk to a human To build and run reliable applications is complex – we know. Schedule a call and we’ll figure things out.

We are using cookies to give you the best online experience. If you continue to use this site, you agree to our use of cookies. By declining we will disable all but strictly required cookies. Please see our privacy policy for more details.

Accept Decline