More testing notes

1 files changed, 35 insertions, 0 deletions

diff --git a/TESTING b/TESTING
index 331254b..00d6b51 100644
--- a/TESTING
+++ b/TESTING
@@ -29,6 +29,9 @@ to HTTP mode if you are changing the CGI code by running:
 
     make basictest TEST_PROTO=http
 
+The protocol being used during a test run is exposed in the GTT_PROTO
+environment variable passed to implementations.
+
 The fundamental parts of the `testing/` directory are
 =====================================================
 
@@ -57,3 +60,35 @@ The fundamental parts of the `testing/` directory are
 						 
 * `03_*.yarn` These tests are more integration tests which look to simulate
   more complex user use-cases.
+
+Tip and tricks when writing tests for Gitano
+============================================
+
+* Until this point is taken out of this document, testing explicitly against
+  stderr is only guaranteed to work in ssh-only tests.  Guard those scenarios
+  with an 'ASSUMING' which checks.  For example, 'ASSUMING rsync is possible'
+  checks this.
+
+* Where there are checks for 'stdout' or 'stderr' you can also write the same
+  kinds of statements for 'the output' which will consider a concatenation of
+  the two.
+
+* Remember that the stdout/stderr of a step is not retained by default by all
+  yarn implementations, even in --snapshot mode.  If you need the output of
+  a shell command for debugging purposes, be sure to write it to a file.
+
+* There is a utility "IMPLEMENTS THEN failure ensues" which always fails but
+  also dumps a whole bunch of information to its output which can be a quick
+  way to debug a scenario without needing to --snapshot which slows things
+  down.
+
+* Remember that access to Gitano behaves differently over SSH and over HTTP.
+  If your test assumes the behaviour of one or the other you must either guard
+  as in the first point or write your IMPLEMENTS to cope.
+
+* As of the time of writing, Gitano's Yarns are written in shell.  You should
+  only assume POSIX shell functionality.  We default to `/bin/sh` which on all
+  sensible systems is a simple shell such as `dash`.  If your `/bin/sh` is,
+  however, `bash` then you should take extra care not to write bashisms into
+  your test implementations.
+