                   Actor testing instructions

These are instructions for contributors of automated actor tests. Each
test should be implemented as a Kepler workflow to be run by the
nightly build script. This script runs
each workflow listed in lib/actor-list.csv.  Note that actors that
cannot be tested effectively using the approach outlined below should be
listed in lib/actor-list.csv along with an explanation of the 
difficulty according to the instructions in that file.

1.  Try to focus each actor test on testing a single actor.  There may be  
more than one test for a particular actor, in which case just separate the filenames of the workflows using a comma.  The name of the test  
should indicate which actor is being tested as well as the specific  
nature of the test.  Use a name such as "ArrayLength_SDF.moml"  
to imply that only one test under SDF is required, and a name like  
"ArrayAppend_SDF_two_channels.moml" to indicate one of several  
possible tests for an actor.  If a workflow is designed to test
more than one actor, try to name the workflow in an informative way 
that clearly distinguishes from other tests, and go ahead and list it on
the lines for each actor to which it applies in actor-list.csv. The system
ensure each test workflow is only run once even if it is listed several times.

2. Actor tests may be included anywhere in the kepler repository.   
The relative path to each actor test (e.g., workflows/test/test- 
ecogrid-eml-gce-data.xml) should be included in the file lib/actor-list.csv.
This is the file used by the nightly build script to  
determine what actor tests to run.   Maintain the file in alphabetical order  
of the actor names.

3.  Before including a test in the nightly build, test it locally  
using the ptexecute ant target in build.xml, i.e., by issuing a  
command such as:

           ant ptexecute -Dworkflow=workflows/eco/Elk_Wolf.xml

4.  Any local data files required for the test should be included in  
the kepler repository.  Within the actor test, specify the path to  
any such files relative to the kepler project directory.

5.  Where possible, use the Test, NonStrictTest,  TypeTest, and 
MessageDigestTest  actors to validate actor output (see documentation 
for these actors).

6.  Use the minimum number of actors and connections required to test  
a particular function of an actor.

7.  Document each actor test internally (e.g., using a TextAttribute  
a.k.a. "Annotation").  Indicate what function of the actor is being  
tested, how its inputs are prepared, how its outputs are validated,  
etc.  Strive to make it easy to determine what has gone wrong when a  
test fails.

8.  Document what external applications are required to successfully  
run the test, and how to acquire installers for these applications.   
Make sure that required applications are installed on the nightly  
build system before committing the test to the repository.

9.  Include your name and e-mail address in the documentation for  
each test.
