Doc: improve README files associated with TAP tests.

Rearrange src/test/perl/README so that the first section is more
clearly "how to run these tests", and the rest "how to write new
tests".  Add some basic info there about debugging test failures.
Then, add cross-refs to that READNE from other READMEs that
describe how to run TAP tests.

Per suggestion from Kevin Burke, though this is not his original
patch.

Discussion: https://postgr.es/m/CAKcy5eiSbwiQnmCfnOnDCVC7B8fYyev3E=6pvvECP9pLE-Fcuw@mail.gmail.com

diff --git a/src/bin/pg_amcheck/README b/src/bin/pg_amcheck/README
index 950f8a73667b80f7246ee218beefbe66a92f5625..dd6f0c58bbd452bef7ea85c5add510fed99eecf7 100644 (file)
--- a/src/bin/pg_amcheck/README
+++ b/src/bin/pg_amcheck/README
@@ -17,3 +17,5 @@ You can use "make installcheck" if you previously did "make install".
 In that case, the code in the installation tree is tested.  With
 "make check", a temporary installation tree is built from the current
 sources and then tested.
+
+See src/test/perl/README for more info about running these tests.

diff --git a/src/test/authentication/README b/src/test/authentication/README
index a8f27bfdaf5d7e98ccb434f8294954066bf62a44..602280a07137ea3cbe5c82287002f6fc41b253ff 100644 (file)
--- a/src/test/authentication/README
+++ b/src/test/authentication/README
@@ -24,3 +24,5 @@ sources and then tested.
 
 Either way, this test initializes, starts, and stops a test Postgres
 cluster.
+
+See src/test/perl/README for more info about running these tests.

diff --git a/src/test/kerberos/README b/src/test/kerberos/README
index fa9c03e78291570883250d711685189354a535e2..df7aad55ef5e1dd6e556b82d43f0b7f05c3a3a60 100644 (file)
--- a/src/test/kerberos/README
+++ b/src/test/kerberos/README
@@ -32,6 +32,8 @@ sources and then tested.
 Either way, this test initializes, starts, and stops a test Postgres
 cluster, as well as a test KDC server.
 
+See src/test/perl/README for more info about running these tests.
+
 Requirements
 ============
 

diff --git a/src/test/ldap/README b/src/test/ldap/README
index 826b15373f22c95636a11b9cbbd0be59e9109a83..d869f66ebfc2f260453de76187bb9b059d99f719 100644 (file)
--- a/src/test/ldap/README
+++ b/src/test/ldap/README
@@ -31,6 +31,8 @@ sources and then tested.
 Either way, this test initializes, starts, and stops a test Postgres
 cluster, as well as a test LDAP server.
 
+See src/test/perl/README for more info about running these tests.
+
 Requirements
 ============
 

diff --git a/src/test/perl/README b/src/test/perl/README
index 0e9a00ea058b074ed30e6c03e2ba6390f5dbdc70..d62db9b5d88cac7df8311e2220b06822bd125955 100644 (file)
--- a/src/test/perl/README
+++ b/src/test/perl/README
@@ -12,22 +12,29 @@ $(prove_installcheck) targets in Makefile.global. By default every test in the
 t/ subdirectory is run. Individual test(s) can be run instead by passing
 something like PROVE_TESTS="t/001_testname.pl t/002_othertestname.pl" to make.
 
-You should prefer to write tests using pg_regress in src/test/regress, or
-isolation tester specs in src/test/isolation, if possible. If not, check to
-see if your new tests make sense under an existing tree in src/test, like
-src/test/ssl, or should be added to one of the suites for an existing utility.
-
-Note that all tests and test tools should have perltidy run on them before
-patches are submitted, using perltidy --profile=src/tools/pgindent/perltidyrc
-
 By default, to keep the noise low during runs, we do not set any flags via
 PROVE_FLAGS, but this can be done on the 'make' command line if desired, eg:
 
 make check-world PROVE_FLAGS='--verbose'
 
+When a test fails, the terminal output from 'prove' is usually not sufficient
+to diagnose the problem.  Look into the log files that are left under
+tmp_check/log/ to get more info.  Files named 'regress_log_XXX' are log
+output from the perl test scripts themselves, and should be examined first.
+Other files are postmaster logs, and may be helpful as additional data.
+
+
 Writing tests
 -------------
 
+You should prefer to write tests using pg_regress in src/test/regress, or
+isolation tester specs in src/test/isolation, if possible. If not, check to
+see if your new tests make sense under an existing tree in src/test, like
+src/test/ssl, or should be added to one of the suites for an existing utility.
+
+Note that all tests and test tools should have perltidy run on them before
+patches are submitted, using perltidy --profile=src/tools/pgindent/perltidyrc
+
 Tests are written using Perl's Test::More with some PostgreSQL-specific
 infrastructure from src/test/perl providing node management, support for
 invoking 'psql' to run queries and get results, etc. You should read the

diff --git a/src/test/recovery/README b/src/test/recovery/README
index 632e720ebefac0e67795b1082e1fc8806fa487f2..435fa64c76d0c7bb5cab85dc208416c4c7bcb00d 100644 (file)
--- a/src/test/recovery/README
+++ b/src/test/recovery/README
@@ -23,3 +23,5 @@ sources and then tested.
 
 Either way, this test initializes, starts, and stops several test Postgres
 clusters.
+
+See src/test/perl/README for more info about running these tests.

diff --git a/src/test/ssl/README b/src/test/ssl/README
index f3f196e214e4b4b37eacba0bd738bf71dc76a80f..9e2cedc0dda57a26a94d0e1c845798fd203a8a11 100644 (file)
--- a/src/test/ssl/README
+++ b/src/test/ssl/README
@@ -29,6 +29,8 @@ sources and then tested.
 Either way, this test initializes, starts, and stops a test Postgres
 cluster that is accessible to other local users!
 
+See src/test/perl/README for more info about running these tests.
+
 Certificates
 ============
 

diff --git a/src/test/subscription/README b/src/test/subscription/README
index fb5382e1205fc1d248f62b867689613a4e0c545a..69e40c5f55df2258ed0fb54e9e8e2702a6ac280d 100644 (file)
--- a/src/test/subscription/README
+++ b/src/test/subscription/README
@@ -9,15 +9,19 @@ Running the tests
 =================
 
 NOTE: You must have given the --enable-tap-tests argument to configure.
+Also, to use "make installcheck", you must have built and installed
+contrib/hstore in addition to the core code.
 
 Run
     make check
 or
     make installcheck
-You can use "make installcheck" if you previously did "make install"
-(including installing the hstore extension).  In that case, the code
-in the installation tree is tested.  With "make check", a temporary
-installation tree is built from the current sources and then tested.
+You can use "make installcheck" if you previously did "make install".
+In that case, the code in the installation tree is tested.  With
+"make check", a temporary installation tree is built from the current
+sources and then tested.
 
 Either way, this test initializes, starts, and stops several test Postgres
 clusters.
+
+See src/test/perl/README for more info about running these tests.