Skip to main content

The Virtual User Data Dictionary

Every virtual user (VU) within a test has its own virtual user data dictionary in Eggplant Performance.

Data Sources

A VU can have access to multiple data sources, and the data within these sources is loaded into the VU data dictionary. During a test, data items are accessed from the virtual user data dictionary by supplying a key and getting back a value.

In the figure above, assume the test has a single VU group containing many VUs. Each VU within the VU group has access to four data sources: two tables and two dictionaries. The data bindings assign the data from the data sources to the virtual users in different ways.

For simplicity's sake, only the VU data dictionaries of the first two VUs are shown.

Loading Data

As the test starts, the keys and values are automatically loaded into each VU data dictionary. The data values can be requested by key name, (e.g., getString("username") or getInteger("numAccounts"), etc., which would return "user1" or 3).

Data values loaded from data dictionaries are always the same, but data loaded from tables can be different for different VUs and on different iterations.

Binding Single Rows Across Multiple VU Groups (Tables Only)

In the example above, the data table of usernames and passwords is assigned with one row per virtual user, even across multiple VU groups. This means that during the test, each VU will have access to a different row in the table, which will not change.

For virtual user 1:

getString("username") => "user1"
getString("password") => "password1"

For virtual user 2:

getString("username") => "user2"
getString("password") => "password2"

Binding Multiple Rows to Each VU (Tables Only)

In contrast, the data table of customer details is assigned with three rows per VU, within a single VU group. This means that during the test, each VU will have access to a different row in the table on every iteration, selected from the rows assigned to that VU.

For virtual user 1, on iteration 1:

getString("custForename") => "forename1"
getString("custSurname") => "surname1"

For virtual user 1, on iteration 2:

getString("custForename") => "forename2"
getString("custSurname") => "surname2"

The next row of data is automatically loaded from the data table into the VU data dictionary at the start of the next iteration.

In this example, the different VUs are assigned non-overlapping rows from the full data table. It might be useful to think of this as splitting up the table into mini-tables, each of which is assigned to the different VUs. Note that in iteration 4, both VUs have exhausted the three rows available to them, so they start again from the first row given to them.

There are plenty of other options available when creating data bindings, such as allowing multiple VUs to share the same rows, warning when a VU has run out of rows, or selecting rows at random rather than in order. See Assigning Data Sources to Eggplant Performance Tests for more details.

If you run into problems when using data bindings from data sources in your scripts, you might need to do some additional troubleshooting. For more information about troubleshooting scripts that use data sources, see Troubleshooting Scripts by Logging Data Values.

Standard Data Dictionary Keys

As well as the keys accessible from assigned data sources, the VU data dictionary also contains a standard set of key=value pairs that provide additional information regarding the executing test. Many of them relate to the current injector, so the values may be different for virtual users running on different injectors. These key=value pairs include:

cacheHomeLocation of the directory in which the current injector stores temporary files during the test run
dataPathA directory within cacheHome where files from the data/ directory within the workspace are copied to during the test
debugWhether the Virtual User is running in diagnostic mode
downloadPathSimilar to cacheHome
engineNameName of the current engine, in which this Virtual User is executing
injectorNameName of the current injector, on which this Virtual User is executing
isLocalInjectorWhether the current injector is on the same machine as the Test Controller, i.e. its hostname is localhost or
projectNameName of the project which contains the current test
runNumberCurrent test run number
runPathLocation of the directory in which this Virtual User's event log will be stored (within the workspace directory)
scriptsPathLocation of the scripts folder within the current project directory
testNameName of the current test
testSeriesNameName of the series under which the current test run will be stored
tracePathA directory within cacheHome where runtime recordings are stored
userHomeLocation of the current project directory within the workspace directory
workspaceNameName of the workspace which contains the current test

All values for these keys are accessible using the standard data access methods, e.g., getString("injectorName").