Add a TESTING document

1 files changed, 59 insertions, 0 deletions

diff --git a/TESTING b/TESTING
new file mode 100644
index 0000000..331254b
--- /dev/null
+++ b/TESTING
@@ -0,0 +1,59 @@
+How the test suites work in Gitano
+==================================
+
+Gitano's test suite is a functional black-box suite built in the `yarn` testing
+language.  Yarn is part of the cmdtest suite by Lars Wirzenius and can be found
+in the `cmdtest` Debian package.  The testing stuff all lives in the testing
+directory at the top level of the Gitano git repository.
+
+The test suite can run in both an SSH mode and an HTTP mode.  In the former the
+accesses to the Gitano instances created during the tests are made by simulated
+SSH access.  In the latter they are made by simulating HTTP access to the CGIs
+which form the Gitano interface.
+
+To run the test suite, simply:
+
+    make test
+
+If you want to run a specific scenario from the test suite:
+
+    make test SCENARIO="whatever scenario name"
+
+If you are making changes and just want to 'smoke test' Gitano to ensure that
+you have not made any fundamental compiler errors etc, then run:
+
+    make basictest
+
+The basictest run will only run in SSH mode by default, you can switch that
+to HTTP mode if you are changing the CGI code by running:
+
+    make basictest TEST_PROTO=http
+
+The fundamental parts of the `testing/` directory are
+=====================================================
+
+* `gitano-test-tool.in`: This is a tool which helps the test suite to do
+  complex operations including simulating different UNIX users, setting up a
+  Gitano instance, etc.
+
+* `http-unwrap`: This tool helps gitano-test-tool to unwrap HTTP responses
+  generated by the test suite when running in HTTP mode.
+
+* `keys/`: This directory contains a set of keys which are used in various
+  parts of the test suite
+
+* `rules-patches/`: This directory contains patches to the ruleset which can be
+  applied during tests.  If you change the skeleton ruleset for Gitano, you may
+  need to refresh these patches.
+			 
+* `library.yarn`: This contains the implementations for the test suite yarn
+  statements.
+
+* `01_*.yarn`: These are considered the basic tests
+
+* `02_*.yarn`: These tests are focussed around validating the commands
+   specifically.  The test might not use only the command in question, but that
+   is their goal.
+						 
+* `03_*.yarn` These tests are more integration tests which look to simulate
+  more complex user use-cases.