Quick start
===========
 1) Make sure the s2 binary in PATH.
 2) Copy the `testing' directory to a directory where you have RW
    permissions.
 3) If you are an SRM 2.x tester only interested in running a series
    of tests against an endpoint, skip to 7.
 4) cd testing/scripts/eval && make ln
 5) `make ln' creates symbolic links to s2.sh script for all *.s2 files
    in your current working directory (See `The s2.sh script' section
    for more information).  You'll now be able to choose and run a
    couple of test scripts and examine the s2.sh script output files.
    (See `The s2.sh script' section.)  To run all tests contained
    in the current directory, type
    make test
 6) If you are not interested in SRM 2.x, skip to 10.
 7) Add your endpoint to your local copy of
    testing/scripts/protos/srm/s2.env
    or set the SRM_ENDPOINT environment variable
 8) cd testing/scripts/protos/srm/2.<x>/basic && make ln
    where <x> is [12].
 9) do 5)
10) Read at least the `Overview' section from s2.txt document and
    `How to create new SRM 2.2 scenarios'.


Testing directory
=================
After you've copied the testing directory into a directory with
read-write permissions, please take a few minutes to familiarise
yourself with its design.  Overview of the most important files and
directories:

bin/s2.sh       please see `The s2.sh script' section
mk/             directory containing generic makefiles
scripts/        directory containing s2 test scripts, please refer to 
                README files within those directories for 
                directory-specific information.

You should never need to change anything bin/ and mk/ directories.

Every script directory contains a Makefile.  This Makefile has three
aims.  Firstly, to provide a way of automatically creating <script>.sh
files for <script>.s2 files which link to the s2.sh script (make ln).
In this way, all test are run with the same parameters in a unified
way.  Secondly, it provides a bulk testing functionality by running
all test (make test).  Thirdly, it removes all files generated by a
test run and symbolic links to the s2.sh script (make clean).

Please try
$ make help

for additional information.


The s2.sh script
================
The script is a wrapper around the s2 binary.  It sources s2
environment files in a directory-recursive fashion and optionally
runs s2 through valgrind or gdb.

s2 environment files
~~~~~~~~~~~~~~~~~~~~
Every <script>.s2 has an optional <script>.env file, which
defines <script>-specific environment variables.  Directory-wide 
environment variables are defined in s2.env files.  The s2.env
files can be defined in any of the `testing/script' subdirectories
and they affect all sub-directories in a hierarchical fashion.

For example, an s2.env file located in `testing/scripts/eval' affects
`find testing/scripts/eval -type d` directories, but not any of the 
`find testing/scripts/protos -type d` directories.
Environment variables defined in
`scripts/protos/srm/2.2/usecase/PutGet01.env' will take precedence
over environment variables defined in
`scripts/protos/srm/2.2/usecase/s2.env'.  However,
`scripts/protos/srm/2.2/usecase/s2.env' will take precedence over
`scripts/protos/srm/2.2/s2.env',
`scripts/protos/srm/2.2/s2.env' will take precedence over
`scripts/protos/srm/s2.env' and so on.

Environment variables defined in the user's environment take precedence
over all of the above.

s2.sh script output files
~~~~~~~~~~~~~~~~~~~~~~~~~
*.d     debug output of the diagnose library.  Verbosity can be
        limited, please see the documentation for libdiagnose or
        `testing/scripts/s2.env' file.
*.e0    before-execution log messages
*.e1    after-execution log messages
*.e2    after-evaluation log messages
*.l     log file of the s2 binary
*.log   log file of an s2 script
*.out   messages sent to standard output
*.p     "pretty-printed" s2 script


How to create new SRM 2.2 scenarios
===================================
To create new SRM 2.2 scenarios, at least some basic knowledge of
the S2 programming concepts is necessary.  To that end, you should
consult the s2.txt reference manual, run and go through a few examples
in testing/scripts/eval subdirectories.

Secondly, you'll need to know the syntax of the S2 SRM 2.2 calls.
Unfortunately, there is no grammar in the s2.txt reference manual
for these, however, all the available parameters for all calls
are given in the testing/scripts/protos/srm/2.2/template directory.
These calls have two types of parameters: send and receive.  The `send'
parameters contain read-only values (all variables are evaluated before
the call) and the receive parameters contain regular expressions.
In this way a success or a failure of a call can be established
simply by entering expected values to receive parameters of an
SRM call.  Also, the returned values can be saved into variables for
later inspection/evaluation by the use of named regular expressions
(?P<var_name>regexp).  Please see the reference manual for more details
on regular expressions.  The important thing to note is that matching
of returned values against regular expressions is currently performed
in the short-circuit manner from left to right, therefore if a receive
parameter's regular expression doesn't match the returned value for
this parameter, the matching engine stops and no values are written
into variables contained in named regular expressions right of the
first mismatched receive parameter.  For example:

srmPing $ENV{ENDPOINT} authorizationID=$ENV{USER} versionInfo=v2\.2 otherInfo=(?P<otherInfo>.*)

is the simplest SRM 2.2 call with two send ($ENV{ENDPOINT},
authorizationID) and two receive (versionInfo, otherInfo) parameters.
If an SRM 2.2 server returns a value which doesn't match v2\.2
(note the backslash as a single dot stands for any character), the
${otherInfo} variable is never defined as the match for that parameter
is never attempted, since the match for versionInfo already failed.

The best place if you want to learn how to create new SRM
2.2 scenarios are testing/scripts/protos/srm/2.2/basic and
testing/scripts/protos/srm/2.2/template directories.  The first
directory shows S2 SRM 2.2 calls in action which you can copy/modify,
the second contains a list of all S2 SRM 2.2 call parameters.

Using existing scenarios for stress testing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a number of ways in which existing SRM 2.2 scenarios can be
adapted for stress testing.  The simplest one is to do something like

>0 99 NOP
   <EXISTING_SCENARIO>

Which runs the same scenario 100 times in parallel.  Or something like:

>0 99 SLEEP 1 500000000
   <EXISTING_SCENARIO>

Which would run <EXISTING_SCENARIO> 100 times in parallel with 1.5s delay
between the scenarios.

Note that you can make use of the internal repeat operator $I{<NUM>}
to refer to the parallel instance 0--99 inside <EXISTING_SCENARIO>.

Request for help
================
Please help improve this project by:
 * reporting s2 bugs, errors in documentation, etc.
 * creating and contributing back SRM 2.2 test scenarios
 * providing feedback
 * new developers and/or patches that work and apply cleanly against
   CVS head or at least the latest advertised CVS tag are very welcome