Skip to main content

The Eggplant Performance Data API

This topic discusses the nature of the API used by Eggplant Performance to handle test data and dynamic data. The API reference manuals can be found here:

Data Components

There are several different types of data components:

  • Data Dictionary: Contains the data that has been set against the VU through whatever means possible (see below). The Data Dictionary is unique per VU.
  • Data Source: Input data stored on disk. this can be any of the following:
    • Dictionary: Key/value pairs (one-to-one).
    • Data table: A file containing a header row listing keys followed by multiple rows of data (one-to-many).
    • Data file: A file, where the entire contents of the file is a single piece of data.
  • Data Source Binding: This term refers to the process of linking test data to a given test, and also is a generic name for linked data.
  • Global variables: A section in a test’s Data tab that allows you to set key/value pairs within a test rather than in a script or dictionary file. This capability can be convenient for overriding hostnames, setting boolean debug flags, etc.

API Methods

Although there are many different methods available in the APIs, by far the most common is the method GetString() (C#) / getString() (Java). GetString(), as the name suggests, allows you to fetch a string stored in the Data Dictionary based on the key under which it was stored.

This example uses GetString() to fetch user credentials using the C# API:

string myUsername = GetString("username");

WriteMessage("Using credentials: " + myUsername);
// example output
// Using credentials: testAccount01

If the key exists in the Virtual User's Data Dictionary, the method will return the value.

If the key doesn’t exist, or there is nothing assigned to the key, an exception is raised in the VU’s event log:

Facilita.Exception.NoSuchValueException: No data found for key "username".
Please check your data bindings for this group.
at Facilita.Fc.Runtime.CompoundDataDictionary.GetFirstDataDictionaryContainingKey(String key)
at Facilita.Fc.Runtime.CompoundDataDictionary.GetString(String key)
at Facilita.Fc.Runtime.VirtualUser.GetString(String key)
at com.testplant.testing.DataTesting.Script()

The GetString() method also appears in any web script generated from recordings, to make it easy to change the hard-coded value.

This is an example from a Pre() method where the WebBrowser is initialized:

WebBrowser.DefaultUserAgent = GetString("User-Agent","Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; Touch; rv:11.0) like Gecko");

The Get commands allow for a default value to be used when no data exists for the given key. This also prevents the call from raising an exception. In the above example, a default User Agent string is provided for when a key for User-Agent does not exist. Another good example where this is used is in the definition of IpEndPoint objects in web scripts:

myEndpoint = new IpEndPoint(GetString("endpointHost", ""), GetInt("endpointPort", 443));

If the hostname (or port) were to change, you could create the corresponding key (endpointHost in this case) and set the new value in the Global variables:

The Global variables section in an Eggplant Performance test

There are other versions of the Get commands for different data types; in the above example, we also used GetInt() to get a port number. You can Get or Set any type of object, as shown in this example:

// a simple, arbitrary object:
public class MyObject
public string MyProperty { get; set; }

MyObject obj1 = new MyObject();
obj1.MyProperty = "Hello, World!";

// store the object in the Data Dictionary:
Set<MyObject>("storedObject", obj1);

// later, or even in a different script:
MyObject obj2 = Get<MyObject>("storedObject");
WriteMessage("obj2.MyProperty: " + obj2.MyProperty);

// example output
// obj2.MyProperty: Hello, World!

Here, we create an arbitrary object and store it in the VU’s data dictionary for later use. All that needs to be done is to reference the object’s Type between the angle brackets in both the Get and Set statements.

Default values

All variations of the Get commands can also take an optional defaultValue parameter, which is the value returned if the Virtual User's data dictionary does not contain a value for the specified key. To help diagnose problems with missing data bindings, a message is written to the VU Event Log when a default value is used:

MessageDefault data warningNo value found for key: myString, using default value instead: abcd

To turn this feature off, go to the Data tab of the Test view in Eggplant Performance Studio and uncheck the option Enable default data warnings.

Variable Scope

Each Eggplant Performance script is a separate class, so variables defined in one script will not automatically be available to other scripts. There are two ways to create global variables:

  • using the Get and Set commands (including GetString(), GetInt(), etc.)
  • using the Custom VU Source script

In most cases, using the Get and Set commands is the easier approach to achieving variables with a global scope.

The Custom VU Source script is created by default whenever a new custom VU is created. Examples are shown in the image below, where we have two custom VUs: one for C# web and the other for Java web.

Custom virtual users in the Eggplant Performance Web VUs folder

To create a global variable, put it within the class definition. The convention is to place global variables toward the top of the script for easy identification:

public class CSCustomVU:AVirtualUser
public string username = "testUser01";
public string password = "testPass01";
public CSCustomVU()
// Do not call any methods of VirtualUser from here
// Put any code that needs to execute at the start of the test in the pre() method

Mark the variables as public. To subsequently access these variables from any script based on the custom VU, prefix the variable name with the VU reference as follows:

using (Request request4 = WebBrowser.CreateRequest(HttpMethod.POST, url4, 4))
// Matching form with index=0 found on page index: 3, URL: ''
Form form_2_0 = Get<Form> ("form_2_0").Copy();
form_2_0.GetInputElement("Email").Value = VU.username;
form_2_0.GetInputElement("Password").Value = VU.password;
using (Response response4 = request4.Send())