Grinder Webtest

You are reading the documentation for Grinder Webtest, a custom module for the Grinder load test framework designed to execute Visual Studio .webtest files.


This module was developed in order to work around some perceived limitations of Grinder’s built-in proxy-based HTTP recording. We found that in some cases, Fiddler was able to more correctly and accurately record the HTTP requests made by a web-enabled application. Since Fiddler is not designed for load testing, it became necessary to find an alternative method for running the scenarios it recorded.

Fiddler can export sessions in Visual Studio .webtest format, but Grinder has no native support for this. Hence, this module was developed, to allow transparent execution of these files as part of a load test. Since the .webtest format is plain-text XML, it’s possible to extend it to allow parameterization, response capturing and verification, with a minimum of additional code.


  • Run an arbitrary number of tests, with logical grouping in test sets
  • Global and local variable parameters
  • Built-in and customizable macro functions
  • Capturing and verifying response output using regular expressions
  • Sequential, thread-based, random, or weighted test sequencing
  • Automatic numbering of individual tests for logging and reporting purposes
  • Correlating test runner that matches parameters in HTTP responses
  • Four configurable levels of logging verbosity


This software is open source, under the terms of the simplified BSD license.


You can obtain Grinder Webtest by downloading a official release from the downloads page, then extracting it to a location on your disk. In later versions of Jython, you can install like this:

$ jython install

Alternatively, you can just build and run your tests directly in the source directory (it’ll probably work better that way).

If you want a copy of the latest development version, clone it from Github:

$ git clone git://

The only dependency aside from Grinder is Jython. Due to some limitations in earlier versions of Grinder, this module was designed to work with Jython 2.2.1. Grinder Webtest was developed using Grinder 3.2, and versions of Grinder as recent as 3.4 are known to be compatible with Jython 2.2.1. Grinder Webtest has not been tested with newer versions of Jython; if you try a newer version, please let us know whether or not it works.


In the root directory of the Grinder Webtest branch, you will find an example script, along with a that uses it. Refer to the Grinder documentation for more on how to use, and how to run test scripts.

You can use as the template for your test script; all you need to do is include one or more TestSets containing .webtest files:

test_sets = [

Then create a TestRunner class:

TestRunner = get_test_runner(test_sets)

For the simplest tests, this is all you need to know. For more detail, refer to the webtest.runner documentation.


To simplify the task of starting the Grinder console and/or agent, a script is provided. This script reads configuration settings from

First, copy to, and define the appropriate pathnames for your environment. On Linux, it might look something like this:

paths = {
    'java':         '/usr/bin/java',
    'jython':       '/usr/local/share/jython',
    'grinder':      '/usr/share/grinder',
    'properties':   './',

Save the changes to You can run the tests in a single agent process like so:

$ jython agent

Or, if you would like to use the console, ensure your has grinder.useConsole=true, then run the console:

$ jython console

Then start agents in separate terminals. Refer to the Grinder docs for more information about the console, agents, and properties.

Please report bugs and feature requests to the issues page.


If you’d like to work on developing grinder-webtest, fork the project from Github and clone your fork. You may also want to set up a virtual environment for installing any Python dependencies (pythonbrew is nice), activate it, then do:

$ pip install -r requirements.txt

Some unit tests are included in the tests directory, which you can run using pytest like this:

$ py.test

This will also generate an HTML-formatted coverage report in htmlcov. The tests should work using regular Python, so you don’t need to muck about with Jython for this.

If you develop any cool new features or fix any bugs, please submit a `pull request`_!

Table Of Contents

Next topic