Improve docs and testsuite

* NEWS: Update.
* README: Update.
* configure.ac: Update.
* tests/initdb.at: Remove mysql-specific statements.
* tests/initdb.c (trycreate, main): Rewrite postgres-specific
parts.
* tests/testsuite.at (AT_DBINIT_PREREQ): Throw xfail if
FAILFILE exists. Exit immediately in that case.

1 files changed, 48 insertions, 12 deletions

diff --git a/README b/README
index 2ddf2b7..5ee4f46 100644
--- a/README
+++ b/README
@@ -137,18 +137,22 @@ This will build the module.  Finally, do the following command as root:
 * Testing
 
 Testing the module requires access to an SQL database which will be
-populated with the test data.  You can either create the database
-and SQL user, or just an SQL user and give him rights for creating it.
-For example:
+populated with the test data.  Before running the test suite, you
+have to create the database, or the user (role), which is able to
+create it.  For example, for MySQL:
 
    GRANT ALL PRIVILEGES on dbrw_test.* to dbrw_test@localhost;
 
+Or, for PostgreSQL:
+
+   CREATE ROLE dbrw_test WITH LOGIN CREATEDB
+   
 Once done, supply the SQL credentials and the database name with
-extra arguments to configure, as shown in the example below:
+extra arguments to `make check', as shown in the example below:
 
-  ./configure --with-varnish-source=/usr/src/varnish-3.0.1\
-              DBRW_TEST_DATABASE=dbrw_test\
-	      DBRW_TEST_USER=dbrw_test
+  make DBRW_TEST_DBTYPE=mysql\
+       DBRW_TEST_DATABASE=dbrw_test\
+       DBRW_TEST_USER=dbrw_test check
 
 You can use the following variables:
 
@@ -184,15 +188,47 @@ Database user.
 
 Password to connect to the server (if necessary).
 
-After running make, do
+Ideally, the tests should succeed.  If they don't, that don't
+necessarily indicates a problem in the module:
+
+The tests will be skipped if the supplied credentials are insufficient
+to access the SQL server. 
+
+If the first test fails, and all subsequent ones are marked as
+"expected failure", that means that the testsuite wasn't able to
+create or populate the test database.  You will find more info in the
+file named FAILURE located in the tests directory.  Fix the problem,
+run `make -C tests clean' (see below) and re-run `make check'.
+
+If all tests are marked as "expected failure", then the testsuite
+uses the cached data from the previous run, which wasn't able to
+create or populate the test database.  In this case, act as described
+above.
 
+Finally, if some or all of the tests were marked as failed, that
+indicates a bug in the module itself, or in the test suite.  In this
+case, the file testsuite.log will contain detailed logs.  Additional
+information can then be found in the directory testsuite.dir.  Please
+send these data to the developer.
+
+Notice that the testsuite tries to create the database only once.
+Subsequent invocations of `make check' will use the existing database.
+Similarly, if it failed to create the database, the failure will be
+memorized and all subsequent runs will just skip all checks.  To clear
+the state, run `make clean' in the directory tests, e.g.:
+
+  make -C tests clean
   make check
 
-to run the tests.  Ideally, they should succeed.  The tests will be skipped
-if the supplied credentials are insufficient to access the SQL server.
-If they fail, the file testsuite.log will contain detailed logs.
-Additional information can then be found in the directory testsuite.dir.
+You can also supply the database credentials in invocation of
+configure:
+  
+  ./configure --with-varnish-source=/usr/src/varnish-3.0.1\
+              DBRW_TEST_DATABASE=dbrw_test\
+	      DBRW_TEST_USER=dbrw_test
 
+This way you won't need to supply them to `make check'.
+	      
 * Bug reporting
 
 Send bug reports and suggestions to <gray@gnu.org>