From c7956b1f1f22937970f29b1f0d4a8a7a7957274d Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Wed, 12 Nov 2014 23:27:25 +0200 Subject: 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. --- README | 60 ++++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 12 deletions(-) (limited to 'README') 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 -- cgit v1.2.1