path: root/README
authorSergey Poznyakoff <>2014-11-12 21:27:25 (GMT)
committer Sergey Poznyakoff <>2014-11-12 21:27:25 (GMT)
commitc7956b1f1f22937970f29b1f0d4a8a7a7957274d (patch) (side-by-side diff)
tree8eb010877cf0eac5e25d0d2baa3f013ae8baf96c /README
parent1cb6d5974b17364d651636ec088066fef210ad2b (diff)
Improve docs and testsuite
* NEWS: Update. * README: Update. * Update. * tests/ Remove mysql-specific statements. * tests/initdb.c (trycreate, main): Rewrite postgres-specific parts. * tests/ (AT_DBINIT_PREREQ): Throw xfail if FAILFILE exists. Exit immediately in that case.
Diffstat (limited to 'README') (more/less context) (ignore whitespace changes)
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:
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_USER=dbrw_test
+ make DBRW_TEST_DBTYPE=mysql\
+ 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
+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 --with-varnish-source=/usr/src/varnish-3.0.1\
+ 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 <>

Return to:

Send suggestions and report system problems to the System administrator.