Add some documentation on test behaviour in selftest.

(This used to be commit e8e9f2cc7b0503e30b211094f452829395a73eec)

source4/selftest/README

@@ -3,15 +3,32 @@
 This directory contains test scripts that are useful for running a
 bunch of tests all at once. 
 
-===============
-Available tests
-===============
-The available tests are obtained from a script, usually 
-selftest/samba{3,4}_tests.sh. This script should for each test output 
+Available testsuites
+====================
+The available testsuites are obtained from a script, usually 
+selftest/samba{3,4}_tests.sh. This script should for each testsuite output 
 the name of the test, the command to run and the environment that should be 
-provided.
+provided. Use the included "plantest" function to generate the required output.
+
+Testsuite behaviour
+================================
+
+Exit code
+------------
+The testsuites should exit with a non-zero exit code if at least one 
+test failed. 
+
+Output format
+-------------
+
+test: <NAME>
+success: <NAME> 
+failure: <NAME> 
+error: <NAME>
+skip: <NAME>
+
+failure: <NAME> [ EXTENDED DESCRIPTION ]
 
-============
 Environments
 ============
 Tests often need to run against a server with particular things set up, 
@@ -41,22 +58,22 @@ The following environments are currently available:
 	 * SERVER: Name of the member server
 
 
-=============
 Running tests
 =============
 
-To run all the tests use:
+To run all the tests use::
 
    make test
 
-To run a quick subset (aiming for about 1 minute of testing) run:
+To run a quick subset (aiming for about 1 minute of testing) run::
 
    make quicktest
 
-To run a specific test, use this syntax
+To run a specific test, use this syntax::
 
    make test TESTS=testname
 
-for example
+for example::
 
    make test TESTS=samba4.BASE-DELETE
+