8 files changed, 35 insertions, 12 deletions

diff --git a/src/bin/pg_amcheck/README b/src/bin/pg_amcheck/README
index 950f8a73667..dd6f0c58bbd 100644
--- 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 a8f27bfdaf5..602280a0713 100644
--- 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 fa9c03e7829..df7aad55ef5 100644
--- 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 826b15373f2..d869f66ebfc 100644
--- 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 0e9a00ea058..d62db9b5d88 100644
--- 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 632e720ebef..435fa64c76d 100644
--- 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 f3f196e214e..9e2cedc0dda 100644
--- 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 fb5382e1205..69e40c5f55d 100644
--- 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.