doc: document the TAP test environment variables

The TAP tests can, to some degree, be controlled by a set of environment
variables. These were however only documented in a README and not in the
main documentation.  This adds documentation of these variables, as well
as changes one CPAN reference to a ulink for consistency.  While there,
also tag CPAN as an acronym as it's listed in the acronyms section.

Reviewed-by: Michael Paquier 
Discussion: https://postgr.es/m/[email protected]

diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml
index 342178bcc24914ddbf9a5b961c0b101b1a3803cb..bbd4960e7be46715b43d89f0813b3335e2316001 100644 (file)
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -487,7 +487,8 @@ $ENV{CONFIG}="Debug";
       As of this writing, IPC::Run is not included in the
       ActiveState Perl installation, nor in the ActiveState Perl Package
       Manager (PPM) library. To install, download the
-      IPC-Run-<version>.tar.gz source archive from CPAN,
+      IPC-Run-<version>.tar.gz source archive from
+      CPAN,
       at , and
       uncompress. Edit the buildenv.pl file, and add a PERL5LIB
       variable to point to the lib subdirectory from the
@@ -518,6 +519,11 @@ $ENV{PROVE_TESTS}='t/020*.pl t/010*.pl'
 
   
 
+  
+    Additionally, the behavior of TAP tests can be controlled by a set of
+    environment variables, see .
+  
+
   
    Some of the TAP tests depend on a set of external commands that would
    optionally trigger tests related to them. Each one of those variables

diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 8f032c4e7ab56ec9765dd583d2aa92a17426ff20..23ea93a387349574b08c0127eb41d3e2a7fde96c 100644 (file)
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -765,7 +765,9 @@ make check PROVE_TESTS='t/001_test1.pl t/003_test3.pl'
 
    
     The TAP tests require the Perl module IPC::Run.
-    This module is available from CPAN or an operating system package.
+    This module is available from
+    CPAN
+    or an operating system package.
     They also require PostgreSQL to be
     configured with the option --enable-tap-tests.
    
@@ -789,6 +791,30 @@ make check PROVE_TESTS='t/001_test1.pl t/003_test3.pl'
     meaning that make installcheck will produce a mix of
     results from temporary servers and the already-running test server.
    
+
+  
+   Environment variables
+
+   
+    Data directories are named according to the test filename, and will be
+    retained if a test fails.  If the environment variable
+    PG_TEST_NOCLEAN is set, data directories will be
+    retained regardless of test status.  For example, retaining the data
+    directory regardless of test results when running the
+    pg_dump tests:
+
+PG_TEST_NOCLEAN=1 make -C src/bin/pg_dump check
+
+   
+
+   
+    Many operations in the test suites use a 180-second timeout, which on slow
+    hosts may lead to load-induced timeouts.  Setting the environment variable
+    PG_TEST_TIMEOUT_DEFAULT to a higher number will change
+    the default to avoid this.
+   
+  
+