Dirty SQL test system

* Added a system that allows "dirty" tests to be written. These tests
actually need to change the database, so a temporary test database must
be created to run them.

legacyworlds/doc/database.txt

@@ -60,22 +60,33 @@ The tests/ sub-directory contains the SQL source code for the pgTAP testing
 framework as well as the tests themselves. See below for more information.
  
  
- Unit tests
- ----------
+Unit tests
+----------
  
-There are three sub-directories in the tests/ directory. The admin/ directory
+There are four sub-directories in the tests/ directory. The admin/ directory
 contains tests that require administrative permissions on the database
 (therefore most functionality checks can be found there), while the user/
 sub-directory contains unit tests that must be executed as the standard
-user (for example privileges checks). Finally, the utils/ sub-directory 
-contains scripts used by tests from the admin/ directory to create test
-data.
+user (for example privileges checks).
+
+The dirty/ sub-directory contains tests which require actual changes to
+be committed to the database; while unit tests are not supposed to be executed
+on a loaded database anyway, these specific tests could cause problems with
+other tests, and therefore run on copies of the database.
+
+Finally, the utils/ sub-directory contains scripts used by tests from both the
+admin/ and dirty/ sub-directories to create test data.
  
-In both directories, files are organised in a manner that is parallel to the
-contents of the database creation scripts. For each actual SQL file, a
-sub-directory with the same name (minus the ".sql" extension) can be created,
-each sub-directory containing the test suites for the definitions and
-functions from the corresponding file.
+In both the admin/ and user/ directories, files are organised in a manner that
+is parallel to the contents of the database creation scripts. For each actual
+SQL file, a sub-directory with the same name (minus the ".sql" extension) can
+be created, each sub-directory containing the test suites for the definitions
+and functions from the corresponding file.
+
+The dirty/ sub-directory contains a script which can be used to run the
+"dirty" test suites, as well as one directory per test suite. Each test suite
+directory may contain a "prepare.sql" script, to be executed before the actual
+tests, as well as a "run-test.sql" which runs the actual tests.
  
 In order to run the database unit tests, the following steps must be taken:
  
@@ -93,14 +104,20 @@ In order to run the database unit tests, the following steps must be taken:
 4) The tests/pgtap.sql script must be loaded into the database as the
    administrative user.
 
-At this point, it becomes possible to launch the test suites by issuing a
+At this point, it becomes possible to launch the basic test suites by issuing a
 command similar to:
 
 		pg_prove -d $DATABASE -U $USER \
 				`find $DIR/ -type f -name '*.sql' | sort`
 
 where $DATABASE is the name of the database, $USER the name of the user that
-will execute the tests and $DIR being either admin or user.
+will execute the tests and $DIR being either admin or user. The "dirty" test
+suite can be launched by running:
+
+		TEST_DATABASE=$DATABASE ./run-dirty-tests.sh
+
+Note that the dirty tests will fail unless all existing connections to the
+main database are closed.
 
 
 Build system
@@ -109,5 +126,5 @@ Build system
 The build system will attempt to create the database using the scripts. It will
 stop at the first unsuccessful command. On success, it will proceed to loading
 pgTAP, then run all available unit tests: first it will execute tests from the
-admin/ sub-directory, then tests from the user/ sub-directory. A failure will
-cause the build to be aborted. 
+admin/ sub-directory, then tests from the user/ sub-directory, and finally the
+dirty tests. A failure will cause the build to be aborted.