Home Docs Load Testing Scripting Possibilities

LoadTest Scripting

As with most other functionality in SoapUI, the possibility to enhance and tailor the execution of a LoadTest to your specific needs is available. The following LoadTest-specific scripting hooks are available directly in the UI;

  1. Setup and TearDown scripts that execute before and after a LoadTest has run
  2. Access to LoadTest related objects in a TestCase script
  3. LoadTest-related event handlers in ReadyAPI
  4. LoadTest-related extensions

A Report Script is also available for customizing the content of generated printable reports, but since this is general functionality for all printable reports this functionality is covered under the Reporting Section instead.

Be sure to have a good knowledge of the general scripting functionality in soapUI before you dive in!

For enhanced scripting features like script debugging and custom events try out LoadUI Pro. With this tool you can distribute your load testing on local and cloud instances, monitor your server resources as your API is put under varying loads, automate your tests with just a few clicks and create performance tests quickly with pre-configured load templates.

Download LoadUI Pro and Start Performance Testing

Let's continue...

1. Setup and TearDown scripts

Setup and TearDown script editors are available as tabs on the bottom of the LoadTest window:

Setup and TearDown scripts

They are run before and after the execution of the containing LoadTest, so they are technically not part of the LoadTest itself, although the TearDown script can still fail the LoadTest via the loadTestRunner.fail( .. ) method.

Some common usage scenarios for these scripts are:

  • Initializing some external resource(s) (in the Setup Script) that somehow participate in the test, for example
    • clear or remove log files
    • prepare target databases or systems
    • initialize shared data or objects to be used in the LoadTest, possibly saving them to the context
  • Failing the LoadTest or for example notifying via email if some condition has not been fulfilled after execution.
    • Total execution time
    • State of some external resource
  • Creating shared objects to be used in the TestCase executed by the LoadTest
  • etc..

The scripts both have access to the following objects:

  • log - a standard Log4j logger which writes to the script log (javadoc) - please note that the script log is by default disabled during execution of a LoadTest, you can enable it in the Global Preferences UI Settings tab.
  • context - an instance of LoadTestRunContext giving access to context properties and related methods (javadoc)
  • loadTestRunner - an instance of LoadTestRunner giving access to the object that controls the execution of the LoadTest (javadoc). Through it you can access the underlying LoadTest model, for example
    • loadTestRunner.loadTest - gives access to the actual loadTest object (javadoc)
    • loadTestRunner.loadTest.statistics - the statistics shown in the statistics table (javadoc)
    • loadTestRunner.loadTest.testCase - the containing testCase (javadoc)
    • etc..

When a TestCase is run under a LoadTest, certain properties are made available in the TestCases context object which can be useful during scripting;

  • context.ThreadIndex - contains the 0-based index of the current thread, so if you use ${ThreadIndex} in a property-expansion, that value will be unique to each thread running under the LoadTest. This might be used when naming output files so they are uniquely named for each thread; for example when configuring an Excel DataSink you could set the output file to Output-${ThreadIndex}.xls, resulting in separate excel files for each thread.
  • context.RunCount - contains the number of times this Thread has executed the TestCase
  • context.TotalRunCount - contains the total number of times the TestCase has been run during the execution of the TestCase
  • context.LoadTestRunner - gives access to the LoadTestRunner (see above) running the LoadTest
  • context.LoadTestContext - gives access to the LoadTestContext (see above) running the LoadTest
  • context.Interactive - Boolean telling if the LoadTest is being run from the UI or not

The main LoadTestRunner and LoadTestContext are the same objects as available in the setup and tearDown scripts described above, allowing you to use them to share objects between all TestCase execution during a LoadTest. For example in a setup script you could initialize some shared resource with

context.resource = .. create resource ..

and in your TestCase you could access this (in a script TestStep or corresponding setup/tearDown script) with

context.LoadTestContext.resource

Note that when running the TestCase "on its own" (ie not via the LoadTest) these will all be null or 0. So the previous script should be

def resource = context.LoadTestContext == null ? null : context.LoadTestContext.resource
if( resource == null )
resource = .. create default resource ..

3. LoadTest EventHandlers and Extensions

The existing soapUI extension mechanism allows you to create LoadTestRunListeners in either java or groovy (ReadyAPI) to tap into events triggered during LoadTest Execution. In ReadyAPI, these are also available for extension directly inside the UI in the Events tab of the Project Window. Scripts here can be used to perform any kind of action, for example you might want to write all TestStep execution times to a database for later analysis, or perform some kind of customization on all sent requests via the LoadTestRunListener.beforeTestStep event.