Skip to main content

Background Scripts (Advanced)

Background scripts enable virtual users (VUs) to run two or more scripts in parallel, with some degree of synchronization between them. Background scripts work well for client-side polling (i.e., timers), like you would use to test a stock ticker site. The most common use-case of a background script is to allow you to replicate asynchronous, client-side JavaScript. But you can use them for a variety of other purposes.

The background scripts themselves are very similar to normal VU scripts. They are associated with a VU type and, therefore, inherit from the VirtualUserScript class.

Method calls to start and stop background scripts can be automatically inserted into a web script by using the Background Scripts Rule during script generation. This rule will also remove requests from the script that are expected to appear in the background script. However, a background script cannot itself be generated from a recording because it is likely to contain complex looping behavior.

Below you will find more information about background scripts.

Creating a Background Script

Creating a background script is similar to creating other VU scripts. The difference is that you create background scripts by selecting the Create background script option on the Properties page in the New Script Specification wizard (shown below). To access the New Script Specification wizard, right-click Scripts and select New empty script in the Eggplant Performance Studio Project tree. For general information about creating VU scripts, see Developing Virtual User Scripts for more information.

Create Background script option in the New Script Sepcification wizard

Background scripts are designed to be started from within normal VU scripts. They cannot be added to a workflow or assigned to a VU group in a test. Conversely, only background scripts can be run in parallel with the main VU script using the methods described below.

A background script in Eggplant Performance Studio

VirtualUser and VirtualUserScript classes provide a variety of background script methods you can use in your own custom VU code and script code.

Starting Background Scripts

You can create background scripts using the createBackgroundScript() method. You must specify an ID string, which is used to refer to the background script instance when calling any of the other methods. You also must include the name of the background script class, preceded by the package/namespace (such as com.testplant.testing.MyBackgroundScript). The background script you want to start must be of the same VU type as the main script, or a parent of that VU type.

When you create background script, it automatically starts unless you specify ExecutionFlags.JustCreate. In that case, you can start the background script by calling the startBackgroundScript(ID) method.

Stopping Background Scripts

A background script can stop automatically at the end of its script() method, or it can continue executing if you set ExecutionFlags.Loop. There is another set of flags, AutomaticStopCriteria, which determine whether the background script will stop if it is still executing at the end of the current script or iteration, or at the point where the VU has finished executing its workflow.

To stop the background script manually, you can use the methods requestToStopBackgroundScript(ID), stopBackgroundScriptImmediately(ID), or waitForBackgroundScriptToFinish(ID). See the API documentation for more details.


Background scripts run in parallel to any scripts within the VU's workflow. Therefore, using the ID string, you can call any of these methods from any of the scripts in the workflow.

Synchronizing Background Scripts

There are three methods which are particularly useful for synchronization:

  • setSynchronizationPoint(id)
  • unsetSynchronizationPoint(id)
  • waitForSynchronizationPoint(id)

Using these methods guarantees that a background script will not continue executing until the main script has reached a certain point (or vice-versa). This can be useful if the script behaviors are linked somehow.

There are also waitForX(key) methods to synchronize on values in the VU's data dictionary. For example, a background script might do some processing and store a value in the data dictionary. If the main script needs that value before it can continue, it may call waitForString(key) to pause until the background script has stored the value against the particular key in the data dictionary.


These methods are only used to synchronize between main scripts and background scripts in a single VU. Synchronization between multiple VUs is more complex. See Passing Data between Scripts and Virtual Users for more information.