Grinder Load Testing Framework

Here is a "classroom" approach to making use of this free tool for performance testing, as if I'm leading you through it for the first time. Along the way, I point out internals and undocumented knowledge. reference LoadRunner terms.

Topics this page:

Site Map  
About this site  

Download and Installation

At the time you read this, the version may have likely moved on from "grinder-3.0-beta29" created December 20, 2005. But you get the idea...
Get announcements of new releases by subscribing to the low-volume mailing list grinder-announce@lists.sourceforge.net.

Avoid putting your own files within the default folder name "C:\grinder-3.0-beta29". Inevitably, when versions change, you would need to figure out which files need to be saved or end up spending frustrating hours debugging why new versions don't work.

I suggest that you create a private folder to put your project files, such as "grinder3", rather a default name such as "C:\grinder-3.0-beta29". Define an environment variable such as "GRINDERENV" to specify that location.

If you create a jar file, add its path (with the jar file name) to the CLASSPATH environment variable.

If it's not already on your system, download and install:
• Java 1.4+ SDK. Specify the full path of its jar files in your machine's CLASSPATH environment variable.
• Since files are in zip (compressed) format, Winzip or $20 Power Archiver. You can also use the jar program that comes with Java.

Download from grinder.sourceforge.net:

• grinder-3.0-beta29.zip contains folder grinder-3.0-beta29, so
  unzip it to C:\ root.
  In the "lib" sub-folder are compiled bytecode jar files grinder.jar and jython.jar.
  In the "examples" sub-folder are sample Python scripts processed by classes in jython.jar.
• grinder-3.0-beta29-src.zip contains folder grinder-3.0-beta29, so
  unzip it to C:\ root. In its "src" folder are ".java" source code files (and associated CVS flags) buried within a library hierarchy:
  src/net/grinder/ contains java source for programs "Console", "Grinder" agent, and "TCPProxy".
  src/org/syntax/jedit
  src/org/python/core/ClonePyInstance.java
  src/"HTTPClient" -- the Java plug-in for testing HTTP services, which is why you need this even though you may not need/want to change the Grinder product's source code.
  Folders within "tests-src" parallel the "src" folder:
  "src/net/grinder/"
  "HTTPClient", which contains file "TestCookie.java"
  Files in the "docs" folder (generated by Sun's javadoc utility) reference css and properties files in the "etc" folder, where the all-important " grinder.properties" file.
• grinder-documentation-20060409.zip contains files with no folder, so
  unzip it within grinder-3.0-beta29.
  Its "development" folder
  Its "g2" folder contains a copy of internet pages such as this what's New in Grinder 2 page.
  Its "g3" folder contains a copy of internet pages such as this What's New in Grinder 3 page.
  The "images" folder stores jpg files.
  Its "skin" folder...
• source.zip contains folder "performance-book-1.0" containing files mentioned in the book "J2EE Performance Testing".
  Unzip it within C:\ since it's not specific to any release of the Grinder.
• chapter_code.zip contains folders Ch04, ch03, ch06, ch07
  unzip it within performance-book-1.0
• spreadsheets.zip contains files "CH04.xls" and "CH03.zip"
  unzip it within performance-book-1.0, then
  Unzip "CH03.zip" within performance-book-1.0/ch03.

• If you have beta-29 or newer, install jython from the lib folder. Or you can download Jython 2.2a and follow these install instructions.

mail lists

grinder-development archive

Introduction to Jython Part 1 and Part 2 from IBM DeveloperWorks.

Jakarta Commons HttpClient

Console Invocation

The Grinder's "Console" is like LoadRunner's "Controller". It is the central program (on a "main" machine) which starts and stops load generator ("injector") worker processes which interpret and carry out Jython test scripts. During a test run, it collates the "samples" it receives, and displays statistics summarizing the activity.

The Grinder Console can be invoked several ways. After you manually open a Windows command window (by clicking Start, Selecting "Run...", typing "cmd", and clicking "OK"), and executing:

java -version
This confirms that java is available for use at the location specified by the CLASSPATH enviornment variable.

cd \grinder3\mine

This is establishes the "current" directory holding user-specific project files.
Add this folder path to the PATH environment variable.
Also add this to path as an environment variable such as GRINDERENV.

java   net.grinder.Console

This invokes Grinder using the "grinder.properties" file in the current directory. The Task Manager sees a new "java.exe" process appear. Exit.

The "C" in "Console" must be upper case. If you type the lower case "console", expect this return message:

Exception in thread "main" java.lang.NoClassDefFoundError: net/grinder/console

If you don't see see the Console, maybe your "grinder.properties" file

grinder.useConsole=false
grinder.consolePort=6372

Adding # in front of this line (commenting it out) is usually preferred to changing "false" to "true".

Closing the command window will make the Console disappear!

go.bat

My custom Windows command file was adapted from sample "startConsole.cmd" Windows command script:

SET GRINDERCLASS=C:\grinder-3.0-beta29
call %GRINDERCLASS%\setGrinderEnv.cmd
java -cp %CLASSPATH% net.grinder.Console
pause Press Ctrl-C

This example uses the GRINDERENV environment variable and invokes the JRE specified in the CLASSPATH environment variable.

More about the "setGrinderEnv.cmd" file later.

To make this execute every time you boot up, create a link to this within your "Startup" folder.

Remote Worker Processes Agent Invocation

An "agent"

If you need multiple agents:

1. Find the IP addresses. On each machine:
   ipconfig /all

   Look for IP Address: . . . . . . . . . . . . : 70.7.129.255

2. Change your grinder.properties file to specify the IP address of your Console machine:
   grinder.consoleHost=127.0.0.125
3. Make sure the Console machine can connect to the agent. Run a command prompt and type:
   ping 10.1.1.197:6372

   Note: Port 6372 is the default port for the agent and worker processes to contact the Console.

   telnet 10.1.1.197 6372 quit
4. Run another command Window and invoke the Grinder agent on the agent machine:
   java   net.grinder.Grinder

   "waiting for console signal" should appear.

   Under the Console's "Processes" tab, a new process (identified by the machine name) should have State "Connected"

   Create a .cmd batch file to do this (such as my a.bat).

Properties Configuration

First, define

grinder.processes=1
grinder.threads=2
grinder.runs=10

grinder.sourceforge.net/g3/getting-started.html

To create a "log" folder to hold logs:

grinder.logDirectory=logs
grinder.numberOfOldLogs=2
grinder.logProcessStreams=false
		

To ...

grinder.jvm.classpath=build/classes;build/test
grinder.jvm.arguments=-Dpython.home=/applications/jython-2.1
		

grinder.script=helloworld.py

To configure Grinder for automatic redirection ...

Communities discussing this

• SourceForge.net.

• gmane.comp.java.grinder.user searchable archives.

• swtest-discuss

"performance-book-1.0"

The "EPizza" folder contains "test_scripts.zip"

The "Pet Store" folder contains files "grinder.properties" and "http-plugin-sniffer-post-340"

Recording Scripts

Scripts can be created by recording actions of a real user using the TCP Proxy described in this tutorial.
1. Start the TCPProxy:
   java net.grinder.TCPProxy -http -localPort 8001 > myscript.py

   These are the defaults (with no keystore) if it were started without any parameters. Note that parameters -httpplugin and -newhttpplugin have been deprecated.

   Add the "-console" parameter if you are using cygwin that do not allow Java processes to be interrupted cleanly.

2. Configure an internet browser (such as IE or Mozilla) to be proxied through port 8001:

   Download Mozilla Firefox or another alternate internet browser and set the proxy there so that you don't have to keep changing browser settings when you want to use your regular browser to check emails, etc.

   Alternately, if you stay with Firefox, you can use Jeremy Gillick's SwitchProxy Firefox extension to quickly switch proxy settings.

Each recording session creates two files: httpscript.py and httpscript_test.py

The latest beta records scripts with tests grouped into pages, making it easier to comment out whole pages at once.

3. Entries in the grinder.properties file:
   grinder.test0.parameter.url=http://www.google.com

Common Script Edits

Default script files that are installed were created with Unix/Mac format of just "\n" rather than PC-DOS "\r\n" format. So on PC's open script files with Wordpad rather than Notepad.

Every Grinder script defines "TestRunner" class which instantiates each worker thread. That is repeatedly called for each test (iteration) of that thread.

class TestRunner:
# This method is called for every test run iteration:
def __call__(self):
logWrapper("Hello World")

Because these are Python scripts, each request must begin with two (and only two) tabs.

The HTTPclient plug-in is used through the facade obtained


from net.grinder.script import Test
from net.grinder.script.Grinder import grinder
from net.grinder.plugin.http import HTTPPluginControl
from HTTPClient import NVPair
from java.net import InetAddress

The "Test" class imported above references "test0", "test1", etc. in the grinder.properties files referenced in these statements:

tests = {
"News01" : Test(1, "News 1 posting"),
"Sport01" : Test(2, "Sport 1 posting"),
"Sport02" : Test(3, "Sport 2 posting"),
"Trading01" : Test(4, "Trading 1 query"),
"LifeStyle01" : Test(5, "LifeStyle 1 posting"),
}

Because test sequences are defined manually, inserting tests within a list would require the list to be manually renumbered

To specify logging:
log = grinder.logger.output;

To reset:

HTTPPluginControl.getConnectionDefaults().setProxyServer("localhost",8001)

To ...

test = Test(1, "getByName")
instrumentedGetByName = test.wrap(InetAddress.getByName)

class TestRunner:
def __call__(self):
instrumentedGetByName("myhost")

To us a regular expression:

pattern = re.compile("(" + stringName + "=[\w&#;]+)&"
# ...
result2 = pattern.search(target, 0)
value = result2.group(1) # everything captured between the parens

Grinder scripting tutorial on looping through an XML request file for values to use in HTTP requests.

Running Scripts

Each "virtual user" test context runs within its own thread.

A single worker process can manage several worker threads.

At the Console:

• Select files to download to each agents' <path>
• Press the "Send changed files to worker processes" button. This transfers scripts to each agent machines' folder named < machine name >-file-store\incoming
• When the agent runs, logs are sent to the terminal if the script has (before the interface) defined:

  out = grinder.logger.TERMINAL

  If the script has:

  out = grinder.logger.LOG

  then Grinder creates (if it doesn't already exist) a folder named according to the grinder.properties file entry

  grinder.logDirectory=logs

  Within this folder the agent stores several files for each test, named using the agent's machine name:

  out_<machine name>-<test number>.log
  data_<machine name>-<test number>.log

  But before that, files left over from a previous run are renamed with a sequence number:

  
  out_<machine name>-<test number>.log00001
  error_<machine name>-<test number>.log00001

  The number of previous runs kept this way is controlled in grinder.properties file entry

  grinder.numberOfOldLogs=2