The Grinder 3

The Grinder, a Java Load Testing Framework

What is The Grinder?

The Grinder is a Java^TM load testing framework that makes it easy to run a distributed test using many load injector machines. It is freely available under a BSD-style open-source license.

The latest news, downloads, and mailing list archives can be found on SourceForge.net.

Key features

• Generic Approach Load test anything that has a Java API. This includes common cases such as HTTP web servers, SOAP and REST web services, and application servers (CORBA, RMI, JMS, EJBs), as well as custom protocols.
• Flexible Scripting Tests are written in the powerful Jython scripting language.
• Distributed Framework A graphical console allows multiple load injectors to be monitored and controlled, and provides centralised script editing and distribution.
• Mature HTTP Support Automatic management of client connections and cookies. SSL. Proxy aware. Connection throttling. Sophisticated record and replay of the interaction between a browser and a web site.

See the longer features list for further details.

History

The Grinder was originally developed for the book Professional Java 2 Enterprise Edition with BEA WebLogic Server by Paco Gómez and Peter Zadrozny. Philip Aston took ownership of the code, reworked it to create The Grinder 2, and shortly after began work on The Grinder 3. The Grinder 3 provides many new features, the most significant of which is Jython scripting. Philip continues to enhance and maintain The Grinder.

In 2003, Peter, Philip and Ted Osborne published the book J2EE Performance Testing which makes extensive use of The Grinder 2.

Authors

Over the years, many users have contributed features, bug fixes, and translations to The Grinder.

Credits

I thank Paco Gómez and Peter Zadrozny for the key ideas embodied in the original version of The Grinder.

I am grateful to SourceForge, Inc. for The Grinder's home on the Internet.

I thank Atlassian for the free Clover and FishEye licenses, and to Headway Software for the free Structure 101 license.

This site is built with Apache Forrest.

Philip Aston

The Grinder License

The Grinder is free software. It also repackages other free software. This section explains what you can and cannot do with The Grinder and the software included with it.

The Grinder

Copyright (c) 2000 Paco Gómez
Copyright (c) 2000-2008 Philip Aston
All rights reserved.

Additional contributions have been made by individuals listed in the AUTHORS file supplied with this distribution. Each individual's claim to copyright is asserted in the files to which they contributed.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the names of the copyright holders nor the names of the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

HTTPClient

The Grinder includes Ronald Tschalär's HTTPClient library (http://www.innovation.ch/java/HTTPClient/index.html). The HTTPClient library is distributed under the GNU Lesser Public License. Under the term 6 of the GNU Lesser Public License, The Grinder is a "work that uses the Library".

Jython

The Grinder includes the software Jython, created by Jim Hugunin, Barry Warsaw and the Jython team (http://www.jython.org/). This is distributed under the terms of the Jython and JPython software licenses.

jEdit Syntax

The Grinder includes the jEdit Syntax highlighting package (http://syntax.jedit.org/). This is distributed according to the jEdit Syntax copyright and usage statement.

Apache XMLBeans

The Grinder includes Apache XMLBeans (http://xmlbeans.apache.org/), under the terms of the Apache Software License Version 2.0. See the XMLBeans NOTICE.

PicoContainer

The Grinder includes PicoContainer (http://picocontainer.codehaus.org/). This is distributed under the terms of the PicoContainer license.

License text

The GNU Lesser General Public License

 GNU LESSER GENERAL PUBLIC LICENSE
           Version 2.1, February 1999

 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
 as the successor of the GNU Library Public License, version 2, hence
 the version number 2.1.]

          Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.

  This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it.  You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.

  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.

  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.

  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

  We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.

  For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard.  To achieve this, non-free programs must be
allowed to use the library.  A more frequent case is that a free
library does the same job as widely used non-free libraries.  In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.

  In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software.  For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.

  Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.

      GNU LESSER GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".

  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)

  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.

  1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

  2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) The modified work must itself be a software library.

    b) You must cause the files modified to carry prominent notices
    stating that you changed the files and the date of any change.

    c) You must cause the whole of the work to be licensed at no
    charge to all third parties under the terms of this License.

    d) If a facility in the modified Library refers to a function or a
    table of data to be supplied by an application program that uses
    the facility, other than as an argument passed when the facility
    is invoked, then you must make a good faith effort to ensure that,
    in the event an application does not supply such function or
    table, the facility still operates, and performs whatever part of
    its purpose remains meaningful.

    (For example, a function in a library to compute square roots has
    a purpose that is entirely well-defined independent of the
    application.  Therefore, Subsection 2d requires that any
    application-supplied function or table used by this function must
    be optional: if the application does not supply it, the square
    root function must still compute square roots.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

  4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

  5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

  6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:

    a) Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)

    b) Use a suitable shared library mechanism for linking with the
    Library.  A suitable mechanism is one that (1) uses at run time a
    copy of the library already present on the user's computer system,
    rather than copying library functions into the executable, and (2)
    will operate properly with a modified version of the library, if
    the user installs one, as long as the modified version is
    interface-compatible with the version that the work was made with.

    c) Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

    d) If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

    e) Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.

  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

  7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:

    a) Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

    b) Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.

  8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

  9. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

  10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.

  11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.

  13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

  14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.

          NO WARRANTY

  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

         END OF TERMS AND CONDITIONS

           How to Apply These Terms to Your New Libraries

  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).

  To apply these terms, attach the following notices to the library.  It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

    <one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>

This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the
  library `Frob' (a library for tweaking knobs) written by James Random Hacker.

  <signature of Ty Coon>, 1 April 1990
  Ty Coon, President of Vice

That's all there is to it!

The Jython and JPython Licenses

A. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING JYTHON
=======================================================

PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
--------------------------------------------

1. This LICENSE AGREEMENT is between the Python Software Foundation
("PSF"), and the Individual or Organization ("Licensee") accessing and
otherwise using this software ("Jython") in source or binary form and
its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Jython alone
or in any derivative version, provided, however, that PSF's License
Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2007
Python Software Foundation; All Rights Reserved" are retained in
Jython alone or in any derivative version prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on
or incorporates Jython or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Jython.

4. PSF is making Jython available to Licensee on an "AS IS"
basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF JYTHON WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF JYTHON
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING JYTHON,
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any
relationship of agency, partnership, or joint venture between PSF and
Licensee.  This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.

8. By copying, installing or otherwise using Jython, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.

Jython 2.0, 2.1 License
================================

Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Jython Developers
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

 - Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

 - Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the distribution.

 - Neither the name of the Jython Developers nor the names of
   its contributors may be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.




JPython 1.1.x Software License.
=========================

______________________________________________________________________

IMPORTANT: PLEASE READ THE FOLLOWING AGREEMENT CAREFULLY.

BY CLICKING ON THE "ACCEPT" BUTTON WHERE INDICATED, OR BY INSTALLING,
COPYING OR OTHERWISE USING THE SOFTWARE, YOU ARE DEEMED TO HAVE AGREED TO
THE TERMS AND CONDITIONS OF THIS AGREEMENT.

______________________________________________________________________

JPython version 1.1.x

  1. This LICENSE AGREEMENT is between the Corporation for National Research
     Initiatives, having an office at 1895 Preston White Drive, Reston, VA
     20191 ("CNRI"), and the Individual or Organization ("Licensee")
     accessing and using JPython version 1.1.x in source or binary form and
     its associated documentation as provided herein ("Software").

  2. Subject to the terms and conditions of this License Agreement, CNRI
     hereby grants Licensee a non-exclusive, non-transferable, royalty-free,
     world-wide license to reproduce, analyze, test, perform and/or display
     publicly, prepare derivative works, distribute, and otherwise use the
     Software alone or in any derivative version, provided, however, that
     CNRI's License Agreement and CNRI's notice of copyright, i.e.,
     "Copyright ©1996-1999 Corporation for National Research Initiatives;
     All Rights Reserved" are both retained in the Software, alone or in any
     derivative version prepared by Licensee.

     Alternatively, in lieu of CNRI's License Agreement, Licensee may
     substitute the following text (omitting the quotes), provided, however,
     that such text is displayed prominently in the Software alone or in any
     derivative version prepared by Licensee: "JPython (Version 1.1.x) is
     made available subject to the terms and conditions in CNRI's License
     Agreement. This Agreement may be located on the Internet using the
     following unique, persistent identifier (known as a handle):
     1895.22/1006. The License may also be obtained from a proxy server on
     the Web using the following URL: http://hdl.handle.net/1895.22/1006."

  3. In the event Licensee prepares a derivative work that is based on or
     incorporates the Software or any part thereof, and wants to make the
     derivative work available to the public as provided herein, then
     Licensee hereby agrees to indicate in any such work, in a prominently
     visible way, the nature of the modifications made to CNRI's Software.

  4. Licensee may not use CNRI trademarks or trade name, including JPython
     or CNRI, in a trademark sense to endorse or promote products or
     services of Licensee, or any third party. Licensee may use the mark
     JPython in connection with Licensee's derivative versions that are
     based on or incorporate the Software, but only in the form
     "JPython-based ___________________," or equivalent.

  5. CNRI is making the Software available to Licensee on an "AS IS" basis.
     CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY
     OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY
     REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY
     PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE
     ANY THIRD PARTY RIGHTS.

  6. CNRI SHALL NOT BE LIABLE TO LICENSEE OR OTHER USERS OF THE SOFTWARE FOR
     ANY INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
     USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE
     THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. SOME STATES DO NOT
     ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY SO THE ABOVE DISCLAIMER
     MAY NOT APPLY TO LICENSEE.

  7. This License Agreement may be terminated by CNRI (i) immediately upon
     written notice from CNRI of any material breach by the Licensee, if the
     nature of the breach is such that it cannot be promptly remedied; or
     (ii) sixty (60) days following notice from CNRI to Licensee of a
     material remediable breach, if Licensee has not remedied such breach
     within that sixty-day period.

  8. This License Agreement shall be governed by and interpreted in all
     respects by the law of the State of Virginia, excluding conflict of law
     provisions. Nothing in this Agreement shall be deemed to create any
     relationship of agency, partnership, or joint venture between CNRI and
     Licensee.

  9. By clicking on the "ACCEPT" button where indicated, or by installing,
     copying or otherwise using the Software, Licensee agrees to be bound by
     the terms and conditions of this License Agreement.

                               [ACCEPT BUTTON]

B. HISTORY OF THE SOFTWARE
=======================================================

JPython was created in late 1997 by Jim Hugunin. Jim was also the
primary developer while he was at CNRI. In February 1999 Barry Warsaw
took over as primary developer and released JPython version 1.1.

In October 2000 Barry helped move the software to SourceForge
where it was renamed to Jython. Jython 2.0 and 2.1 were developed
under the Jython specific license below.

From the 2.2 release on, Jython contributors have signed
Python Software Foundation contributor agreements and releases are
covered under the Python Software Foundation license version 2.

The standard library is covered by the Python Software Foundation
license as well. See the Lib/LICENSE file for details.

The zxJDBC package was written by Brian Zimmer and originally licensed
under the GNU Public License.  The package is now covered by the Jython
Software License.

The command line interpreter is covered by the Apache Software
License.  See the org/apache/LICENSE file for details.

jEdit Syntax copyright and usage statement

The jEdit 2.2.1 syntax highlighting package contains code that is
Copyright 1998-1999 Slava Pestov, Artur Biesiadowski, Clancy Malcolm,
Jonathan Revusky, Juha Lindfors and Mike Dillon.

You may use and modify this package for any purpose. Redistribution is
permitted, in both source and binary form, provided that this notice
remains intact in all source distributions of this package.

-- Slava Pestov
25 September 2000
<sp@gjt.org>

XMLBeans NOTICE

=========================================================================
==  NOTICE file corresponding to section 4(d) of the Apache License,   ==
==  Version 2.0, in this case for the Apache XmlBeans distribution.    ==
=========================================================================

This product includes software developed by The Apache Software
Foundation (http://www.apache.org/).

Portions of this software were originally based on the following:
 - software copyright (c) 2000-2003, BEA Systems,
   <http://www.bea.com/>.

Aside from contributions to the Apache XMLBeans project, this software
also includes:

 - one or more source files from the Apache Xerces-J and Apache Axis
   products, Copyright (c) 1999-2003 Apache Software Foundation

 - W3C XML Schema documents Copyright 2001-2003 (c) World Wide Web
   Consortium (Massachusetts Institute of Technology, European
   Research Consortium for Informatics and Mathematics, Keio
   University)

 - Piccolo XML Parser for Java from http://piccolo.sourceforge.net/,
   Copyright 2002 Yuval Oren under the terms of the Apache Software
   License 2.0

 - JSR-173 Streaming API for XML from
   http://sourceforge.net/projects/xmlpullparser/,
   Copyright 2005 BEA under the terms of the Apache Software
   License 2.0

PicoContainer License

Copyright (c) 2003-2005, PicoContainer Organization
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

  Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

  Neither the name of the PicoContainer Organization nor the names of its
  contributors may be used to endorse or promote products derived from this
  software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

Downloading The Grinder

Download

The Grinder can be downloaded from SourceForge.net. New users are advised to start with The Grinder 3.

The Grinder 3 is distributed as two zip files which you should expand using unzip, WinZip or similar. Everything required to run The Grinder is in the zip file labelled grinder-3.0-version.zip. The remaining files that are needed to build The Grinder are distributed in the zip file labelled grinder-3.0-version-src.zip; these are mainly of interest to developers wanting to extend The Grinder.

What else do I need?

To run The Grinder:

and optionally:

Support

Mailing lists

Requests for help should be sent to grinder-use@lists.sourceforge.net.

grinder-announce@lists.sourceforge.net is a low-volume mailing list which is used to announce new releases and other items of interest to users of The Grinder.

Please contribute bug fixes and enhancements to grinder-development@lists.sourceforge.net.

You can subscribe and unsubscribe to the lists, and search their archives, through SourceForge.net. Gmane provides alternative searchable archives, together with NNTP feeds and an optional Blog-like interface.

When Philip Aston finds the time to respond to mail about The Grinder, messages not copied to one of the above mail lists are likely to be ignored. Philip freely copies responses to the lists; if there is a particular reason why you want to keep your communication private you must say so. Finally, if you can provide answers to questions sent to the lists, please don't be shy!

External references

Related Software Projects

Grinder Analyzer		Grinder Analyzer is a tool that parses log data from The Grinder and generates client-side performance graphs. These graphs include response time, transactions per second, and network bandwidth used. Like The Grinder itself, Grinder Analyzer uses Jython, and the excellent JFreechart graphing library.
webFlange		webFlange is a continuous load testing web application written in Java. It leverages The Grinder for running tests, automatically creates reports and allows the creation of charts from the test results.
Grinderstone		GrinderStone Eclipse plug-in is Grinder development environment (debugger for Grinder scripts is included).GrinderStone is extension for PyDev plug-in for developing Grinder scripts.

Articles

Commercials

This section contains links to commercial products and services related to The Grinder. You should not assume any relationship other than those documented below between the listed individuals and companies and The Grinder project. If you have a product or service related to The Grinder and would like to add information to this page, please email details to grinder-use.

J2EE Performance Testing

I'm pleased to announce the availability of J2EE Performance Testing with BEA WebLogic Server by Peter Zadrozny, Philip Aston and Ted Osborne, originally published by Expert Press and now by APress.

This book uses The Grinder 2 throughout, and indeed was responsible for driving the development of many of The Grinder's features. The book shows how to performance test complete J2EE applications and how to explore key performance issues surrounding the most popular J2EE APIs. The performance tests are carried out using BEA WebLogic Server™, but are generally applicable to any J2EE application server.

Most importantly, the book contains in-depth coverage of The Grinder 2 including a full user guide and case studies showing how to apply The Grinder to real world problems. The testing approach is equally applicable when using The Grinder 3.

Following several requests, I've made the source code for the book available from The Grinder SourceForge page. This source is supplied unsupported and with no warranty.

Philip Aston

Anser Enterprise

One of my consulting services is helping performance analysts to set up company-internal blogs on their performance activities to help them communicate better with their developers and management. As part of my consulting service I can offer usage and customization tips on The Grinder and a separate data visualization tool to show Grinder test results on their company's intranet. Much of this is in the area of test automation and mining test results.

Here's a link which provides several example web pages on communicating WebLogic 8.1/Grinder testing results. It requires downloading the Java 1.5 plug-in for charting Grinder test results.

Todd Nichols, Anser Enterprise

TestPros

TestPros provides load testing and performance tuning services using Grinder. We can provide our services in one or a combination of three ways - remotely via our Internet server farm, at our test labs, or at our customer's location.

For more information:

• 1-877-783-7855
• info@TestPros.com
• www.TestPros.com

swtest-discuss

I run a mailing list for software testers called swtest-discuss. There are a few people there (including me) who are interested in talking about how people do testing for open source projects. I haven't yet found a community of open source testers that cuts across multiple tools/applications.

If you're interested in sharing your experiences in testing open source software, please consider joining swtest-discuss, at least long enough to see if there's any interest in having an on-going forum on this topic. If you do subscribe, please either send me a private email or introduce yourself to the list so we know you're there.

Danny R. Faught, Tejas Software Consulting

What's new in The Grinder 3?

This section summarises the changes between The Grinder 2 and The Grinder 3. If you're not familiar with The Grinder 2, skim read this and move on to Getting Started.

Jython

The most significant change that The Grinder 3 introduces is a Jython scripting engine that is used to execute test scripts. Jython is a Java implementation of the popular Python language. Test scripts specify the tests to run. In The Grinder 2, tests were specified in the grinder.properties file. The grinder.properties file is still used to specify general control information (how to contact the console, how many worker processes to use, ..), as well as the name of the test script. Many other key features of The Grinder 2, such as the console and the process architecture, remain unchanged.

The scripting engine provides the following new capabilities:

Test any Java code

The Grinder 3 allows any Java (or Jython) code to be encapsulated as a test. This practically removes the need to write custom plug-ins. Although plug-ins are no longer responsible for performing tests, they can still be useful to manage objects that the tests use. For example, the HTTP plug-in manages a pool of connections for each worker thread, and provides an HTTPRequest object that makes use of these connections.

Dynamic test scripting

The Grinder 2 worker processes execute tests in the properties file sequentially in a fixed order, and there is limited support in some of the The Grinder 2 plug-ins for checking test results. The Grinder 3 allows arbitrary branching and looping and makes test results directly available to the test script, allowing different test paths to be taken depending on the outcome of each test.

The Grinder 2 HTTP plug-in's string bean feature provides simple support for requests that contain dynamic data. The Grinder 3 can use the full power of Jython to create dynamic requests of arbitrary complexity.

Kind of dry, huh? If you never seen any Python or are wondering what was wrong with the old grinder.properties approach then skip ahead to the Script Gallery where you can sample the power of The Grinder 3.

New distribution packaging

The Grinder is distributed in separate binary and source zip files. They can be downloaded from SourceForge.net.

Other changes

• The TCPSniffer has been renamed TCPProxy for correctness. The TCPProxy can be used with other HTTP and HTTPS proxies. Many new features and fixes have been added to the TCPProxy.
• Console signals are now transmitted over a TCP socket connection. Multicast is no longer used, removing a frequent source of setup problems.
• The interface that plug-ins must implement has changed significantly. Plug-ins written for The Grinder 2 will not work with The Grinder 3.
• Many grinder.properties have been removed. The features formerly accessed through setting properties are now set by making calls to the plug-in from test scripts. Some of the remaining property names have been renamed.
• HTTP tests can now be directed through an HTTP proxy.
• String beans and OK strings have been removed from the HTTP plug-in. String beans and OK strings are very limited in comparison to to the flexibility now provided by Jython scripts.
• The HttpURLConnection implementation has been removed from the HTTP plug-in.
• Many other minor updates to HTTP testing functionality.
• HTTPS and SSL contexts can now be controlled on a per thread basis.
• The JUnit and Socket plug-ins have been removed. Their functionality can be achieved directly by using the appropriate Java objects in scripts.
• From the console you can edit test scripts and distribute them to the worker processes. It is no longer be necessary to copy grinder.properties files around or to use a shared disk.

Features of The Grinder 3

Thanks to Edwin DeSouza for his help in compiling this feature list.
Last updated: 5 January 2008

Capabilities of The Grinder

Open Source

Standards

The Grinder Architecture

Console

Statistics, Reports, Charts

Script

The Grinder Plug-ins

HTTP Plug-in

TCP Proxy

Documentation

Support

Getting started

Getting started

The Grinder processes

The Grinder is a framework for running test scripts across a number of machines. The framework is comprised of three types of process (or program). Worker processes, agent processes, and the console. The responsibilities of each of the process types are:

• Worker processes
  • Interpret Jython test scripts and perform tests using a number of worker threads
• Agent processes
  • Manage worker processes
• The console
  • Coordinate the other processes
  • Collate and display statistics
  • Script editing and distribution

As The Grinder is written in Java, each of these processes is a Java Virtual Machine (JVM).

For heavy duty testing, you start an agent process on each of several load injector machines. The worker processes they launch can be controlled and monitored using the console. There is little reason to run more than one agent on each load injector, but you can if you wish.

Tests and test scripts

A test is a unit of work against which statistics are recorded. Tests are uniquely defined by a test number and also have a description. Users specify which tests to run using a Jython test script. If you wish your scripts can report many different actions (e.g. different web page requests) against the same test, The Grinder will aggregate the results.

The script is executed many times in a typical testing scenario. Each worker process has a number of worker threads, and each worker thread calls the script a number of times. A single execution of a test script is called a run.

You can write scripts for use with the Grinder by hand. There are a number of examples of how to do this in the Script Gallery. See the Scripts section for more details on how to create scripts.

If you are creating a script to test a web site or web application, you can use the TCPProxy to record a browser session as a script.

Network communication

Each worker process sets up a network connection to the console to report statistics. Each agent process sets up a connection to the console to receive commands, which it passes on to its worker processes. The console listens for both types of connection on a particular address and port. By default, the console listens on port 6372 on all local network interfaces of the machine running the console.

If an agent process fails to connect to the console, or the grinder.useConsole property is false, the agent will continue independently without the console and automatically will start its worker processes. The worker processes will run to completion and not report to the console. This can be useful when you want to quickly try out a test script without bothering to start the console.

Output

Each worker process writes logging information to a file called out-host-n.log, where host is the machine host name and n is the worker process number. Errors are written to error-host-n.log. If no errors occur, an error file will not be created.

Data about individual test invocations is written into a file called data-host-n.log that can be imported into a spreadsheet tool such as Microsoft Excel^TM for further analysis. The data file is the only place where information about individual tests is recorded; the console displays only aggregate information.

The final statistics summary (in the out-* files of each process) looks something like this:

Final statistics for this process:

              Successful
              Tests         Errors        Mean Test    Test Time
                                          Time (ms)    Standard
                                                       Deviation
                                                       (ms)

Test 0        25            0             255.52       22.52
Test 1        25            0             213.40       25.15
Test 2        25            0             156.80       20.81         "Image"
Test 3        25            0             90.48        14.41
Test 4        25            0             228.68       23.97         "Login page"
Test 5        25            0             86.12        12.53         "Security check"
Test 6        25            0             216.20       8.89
Test 7        25            0             73.20        12.83
Test 8        25            0             141.92       18.36
Test 9        25            0             104.68       19.86         "Logout page"

Totals        250           0             156.70       23.32

The console has a dynamic display of similar information collected from all the worker processes. Plug-ins and advanced test scripts can provide additional statistics; for example, the HTTP plug-in adds a statistic for the content length of the response body.

Each test has one of two possible outcomes:

1. Success. The number of Successful Tests for that test is incremented The time taken to perform the test is added to the Total.
2. Error. The execution of a test raised an exception. The number of Errors for the test is incremented. The time taken is discarded.

The Total, Mean, and Standard Deviation figures are calculated based only on successful tests.

How do I start The Grinder?

Its easy:

1. Create a grinder.properties file. This file specifies general control information (how the worker processes should contact the console, how many worker processes to use, ..), as well as the name of the Jython script that will be used to run the tests.

2. Set your CLASSPATH to include the grinder.jar file which can be found in the lib directory.

3. Start the console on one of the test machines:

   java net.grinder.Console
   

4. For each test machine, do steps 1. and 2. and start an agent process:

   java net.grinder.Grinder
   

   You can also specify an explicit properties file as the first argument. For example:

   java net.grinder.Grinder myproperties
   

The console does not read the grinder.properties file. It has its own options dialog (choose the File/Options menu option) which you should use to set the communication addresses and ports to match those in the grinder.properties files. The console controls can be used to trigger The Grinder test scenario. Each agent process then creates child worker processes to do the work.

As the worker processes execute, they dynamically inform the console of the tests in the test script. If you start the console after the agent process, you should press the Reset processes button. This will cause the existing worker processes to exit and the agent process to start fresh worker processes which will update the console with the new test information.

Included below are some sample shell scripts, for both unix/linux and windows, for starting grinder agents, its console, and the HTTPProxy.

Windows:

• setGrinderEnv.cmd:

  set GRINDERPATH=(full path to grinder install directory)
  set GRINDERPROPERTIES=(full path to grinder.properties)\grinder.properties
  set CLASSPATH=%GRINDERPATH%\lib\grinder.jar;%CLASSPATH%
  set JAVA_HOME=(full path to java install directory)
  PATH=%JAVA_HOME%\bin;%PATH%
  

• startAgent.cmd:

  call (path to setGrinderEnv.cmd)\setGrinderEnv.cmd
  echo %CLASSPATH%
  java -cp %CLASSPATH% net.grinder.Grinder %GRINDERPROPERTIES%
  

• startConsole.cmd:

  call (path to setGrinderEnv.cmd)\setGrinderEnv.cmd
  java -cp %CLASSPATH% net.grinder.Console
  

• startProxy.cmd:

  call (path to setGrinderEnv.cmd)\setGrinderEnv.cmd
  java -cp %CLASSPATH% net.grinder.TCPProxy -console -http > grinder.py
  

Unix:

• setGrinderEnv.sh:

  #!/usr/bin/ksh
  GRINDERPATH=(full path to grinder install directory)
  GRINDERPROPERTIES=(full path to grinder.properties)/grinder.properties
  CLASSPATH=$GRINDERPATH/lib/grinder.jar:$CLASSPATH
  JAVA_HOME=(full path to java install directory)
  PATH=$JAVA_HOME/bin:$PATH
  export CLASSPATH PATH GRINDERPROPERTIES
  

• startAgent.sh:

  #!/usr/bin/ksh
  . (path to setGrinderEnv.sh)/setGrinderEnv.sh
  java -cp $CLASSPATH net.grinder.Grinder $GRINDERPROPERTIES
  

• startConsole.sh:

  #!/usr/bin/ksh
  . (path to setGrinderEnv.sh)/setGrinderEnv.sh
  java -cp $CLASSPATH net.grinder.Console
  

• startProxy.sh:

  #!/usr/bin/ksh
  . (path to setGrinderEnv.sh)/setGrinderEnv.sh
  java -cp $CLASSPATH net.grinder.TCPProxy -console -http > grinder.py
  

How should I set up a project structure for The Grinder?

Well the short answer is however works best for you. Many people will already know how they want to set up their directory structure and will have no issue implementing The Grinder as one of their many tools. For those looking for a little guidance it is worth asking yourself questions like:

• How many projects will I be working on?
• Will I need to revisit projects from time to time?
• Do I need repeatability?
• Is this a shared implementation?
• ...etc.

Below is given an example of a directory structure for setting up The Grinder.

.
`- Grinder
    |
    |-- bin
    |   |-- setGrinderEnv.sh/cmd
    |   |-- startAgent.sh/cmd
    |   |-- startConsole.sh/cmd
    |   `-- startProxy.sh/cmd
    |
    |-- engine
    |   |-- grinder-3.0-beta32
    |   |-- grinder-3.0
    |   `-- ...
    |
    |-- etc
    |   |-- grinder.properties
    |   `-- ...
    |
    |-- jvm
    |   |-- jdk1.3
    |   |-- jdk1.4.02
    |   `-- ...
    |
    |-- lib
    |   |-- jython2.1
    |   |-- jdom-1.0
    |   |-- xerces_2_6_0
    |   |-- xerces-2_6_2
    |   |-- oracle
    |   `-- ...
    |
    |-- logs
    |   `-- ...
    |
    `-- projects
        |-- website_project
        |   |-- httpscript.py
        |   |-- httpscript_tests.py
        |   `-- ...
        |
        |-- db_project
        |   |-- jdbc.py
        |   `-- ...
        |
        `-- ...

First off the bin directory has been created for storing executable files for the implementation. The sample start scripts from "How do I start The Grinder?" have been included in this directory. The engine directory has been created for storing the versions of The Grinder that may be used. Strictly speaking the versions of The Grinder could be stored under the lib directory but for this example The Grinder has been given its own directory. The etc directory has been created to store the configuration files for the implementation such as the grinder.properties file. The jvm directory has been created to store the various jdks and their versions that could be used in testing. The lib directory has been created to store the various third party libraries and their respective versions that projects may require. For example if you wanted to use the full set of libraries which come with jython then this is the directory into which you would install. Remember to update your CLASSPATH with the libraries you require. The logs has been created to store the various logs that the grinder generates during its runs.The projects directory has been created to store the scripts to be run by The Grinder and organise them by project/body of work.

The above example would be useful as a simple implementation for one person who works on one project at a time. As the number of projects grows, more people share the implementation, or projects need to be revisited with repeatability ensured, then it makes sense, in this example, to modularize the implementation around the projects. To do this simply create the bin, etc and logs directories under the respective projects like so:

    |
    `-- projects
        |-- website_project
        |   |-- bin
        |   |   |-- setGrinderEnv.sh/cmd
        |   |   |-- startAgent.sh/cmd
        |   |   |-- startConsole.sh/cmd
        |   |   `-- startProxy.sh/cmd
        |   |-- etc
        |   |   |-- grinder.properties
        |   |   `-- ...
        |   |-- httpscript.py
        |   |-- httpscript_tests.py
        |   |-- logs
        |   |   `-- ...
        |   `-- ...
        |
        |-- db_project

Once this has been done the environment can be set to use the engine, jvm and libraries required by a particular project, rather than setting the environment for all the projects (as would happen in the simple implementation). This allows you, for example, to retain projects which were run using legacy versions of libraries and/or engine and re-run them at a later date with the same setup. Also different projects may require different versions of the same library which would have caused issues when using an implementation-wide CLASSPATH. The grinder.properties file can also be customised on a per project basis.

Modularizing the implementation like this gives greater flexibility and repeatability and opens up the prospect of multiple people using the implementation concurrently.

The Grinder 3 Properties File

The Grinder worker and agent processes are controlled by setting properties in the grinder.properties file.

All properties have default values. If you start The Grinder agent process without a grinder.properties file it will communicate with the console using default addresses, use one worker process, one thread, and make one run through the test script found in the file grinder.py. This is not much use, so read on...

Table of properties

This table lists the properties understood by The Grinder engine.