diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 60250bb7a9f..1d9519dd986 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -28,7 +28,7 @@
sequential
mode for running the tests. The
sequential method runs each test script alone, while the
parallel method starts up multiple server processes to run groups
- of tests in parallel. Parallel testing gives confidence that
+ of tests in parallel. Parallel testing adds confidence that
interprocess communication and locking are working correctly.
@@ -43,9 +43,7 @@ gmake check
in the top-level directory. (Or you can change to
src/test/regress and run the command there.)
- This will first build several auxiliary files, such as
- sample user-defined trigger functions, and then run the test driver
- script. At the end you should see something like:
+ At the end you should see something like:
=======================
@@ -113,9 +111,9 @@ gmake MAX_CONNECTIONS=10 check
Running the Tests Against an Existing Installation
- To run the tests after installation)]]>,
+ To run the tests after installation (see ),
initialize a data area and start the
- server, , ]]> then type:
+ server as explained in , then type:
gmake installcheck
@@ -125,73 +123,89 @@ gmake installcheck-parallel
The tests will expect to contact the server at the local host and the
default port number, unless directed otherwise by PGHOST and
- PGPORT environment variables.
-
-
-
- The source distribution also contains regression tests for the optional
- procedural languages and for some of the contrib modules.
- At present, these tests can be used only against an already-installed
- server. To run the tests for all procedural languages that have been
- built and installed, change to the src/pl directory of the
- build tree and type:
-
-gmake installcheck
-
- You can also do this in any of the subdirectories of src/pl
- to run tests for just one procedural language. To run the tests for all
- contrib modules that have them, change to the
- contrib directory of the build tree and type:
-
-gmake installcheck
-
- The contrib modules must have been built and installed first.
- You can also do this in a subdirectory of contrib to run
- the tests for just one module.
+ PGPORT environment variables. The tests will be run in a
+ database named regression; any existing database by this name
+ will be dropped.
+ The tests will also transiently create some cluster-wide objects, such as
+ user identities named regressuserN.
- Testing Hot Standby
+ Additional Test Suites
- The source distribution also contains regression tests of the static
- behaviour of Hot Standby. These tests require a running primary server
- and a running standby server that is accepting new WAL changes from the
- primary using either file-based log shipping or streaming replication.
- Those servers are not automatically created for you, nor is the setup
- documented here. Please check the various sections of the documentation already
- devoted to the required commands and related issues.
+ The gmake check and gmake installcheck commands
+ run only the core regression tests, which test built-in
+ functionality of the PostgreSQL server. The source
+ distribution also contains additional test suites, most of them having
+ to do with add-on functionality such as optional procedural languages.
- First create a database called "regression" on the primary.
+ To run all test suites applicable to the modules that have been selected
+ to be built, including the core tests, type one of these commands at the
+ top of the build tree:
-psql -h primary -c "CREATE DATABASE regression"
-
- Next, run a preparatory script on the primary in the regression database:
- src/test/regress/sql/hs_primary_setup.sql, and
- allow for the changes to propagate to the standby, for example
-
-psql -h primary -f src/test/regress/sql/hs_primary_setup.sql regression
-
- Now confirm that the default connection for the tester is the standby
- server under test and then run the standbycheck target from the regression
- directory:
-
-cd src/test/regress
-gmake standbycheck
+gmake check-world
+gmake installcheck-world
+ These commands run the tests using temporary servers or an
+ already-installed server, respectively, just as previously explained
+ for gmake check and gmake installcheck. Other
+ considerations are the same as previously explained for each method.
+ Note that gmake check-world builds a separate temporary
+ installation tree for each tested module, so it requires a great deal
+ more time and disk space than gmake installcheck-world.
- Some extreme behaviours can also be generated on the primary using the
- script: src/test/regress/sql/hs_primary_extremes.sql
- to allow the behaviour of the standby to be tested.
+ Alternatively, you can run individual test suites by typing
+ gmake check or gmake installcheck in the appropriate
+ subdirectory of the build tree. Keep in mind that gmake
+ installcheck assumes you've installed the relevant module(s), not
+ only the core server.
- Additional automated testing may be available in later releases.
+ The additional tests that can be invoked this way include:
+
+
+
+
+
+ Regression tests for optional procedural languages (other than
+ PL/pgSQL, which is tested by the core tests).
+ These are located under src/pl.
+
+
+
+
+ Regression tests for contrib modules,
+ located under contrib.
+ Not all contrib modules have tests.
+
+
+
+
+ Regression tests for the ECPG interface library,
+ located in src/interfaces/ecpg/test.
+
+
+
+
+ Tests stressing behavior of concurrent sessions,
+ located in src/test/isolation.
+
+
+
+
+
+ When using installcheck mode, these tests will destroy any
+ existing databases named pl_regression,
+ contrib_regression, isolationtest,
+ regress1, or connectdb, as well as
+ regression.
@@ -199,7 +213,7 @@ gmake standbycheck
Locale and Encoding
- By default, the tests against a temporary installation use the
+ By default, tests using a temporary installation use the
locale defined in the current environment and the corresponding
database encoding as determined by initdb. It
can be useful to test different locales by setting the appropriate
@@ -232,8 +246,9 @@ gmake check LANG=C ENCODING=EUC_JP
- The encoding can be set for tests against a temporary or an
- existing installation.
+ The database encoding can be set for tests against either a temporary or
+ an existing installation, though in the latter case it must be
+ compatible with the installation's locale.
@@ -241,7 +256,7 @@ gmake check LANG=C ENCODING=EUC_JP
Extra Tests
- The regression test suite contains a few test files that are not
+ The core regression test suite contains a few test files that are not
run by default, because they might be platform-dependent or take a
very long time to run. You can run these or other extra test
files by setting the variable EXTRA_TESTS. For
@@ -257,6 +272,52 @@ gmake check EXTRA_TESTS=collate.linux.utf8 LANG=en_US.utf8
platforms, and only when run in a database that uses UTF-8 encoding.
+
+
+ Testing Hot Standby
+
+
+ The source distribution also contains regression tests for the static
+ behavior of Hot Standby. These tests require a running primary server
+ and a running standby server that is accepting new WAL changes from the
+ primary (using either file-based log shipping or streaming replication).
+ Those servers are not automatically created for you, nor is replication
+ setup documented here. Please check the various sections of the
+ documentation devoted to the required commands and related issues.
+
+
+
+ To run the Hot Standby tests, first create a database
+ called regression on the primary:
+
+psql -h primary -c "CREATE DATABASE regression"
+
+ Next, run the preparatory script
+ src/test/regress/sql/hs_primary_setup.sql
+ on the primary in the regression database, for example:
+
+psql -h primary -f src/test/regress/sql/hs_primary_setup.sql regression
+
+ Allow these changes to propagate to the standby.
+
+
+
+ Now arrange for the default database connection to be to the standby
+ server under test (for example, by setting the PGHOST and
+ PGPORT environment variables).
+ Finally, run gmake standbycheck in the regression directory:
+
+cd src/test/regress
+gmake standbycheck
+
+
+
+
+ Some extreme behaviors can also be generated on the primary using the
+ script src/test/regress/sql/hs_primary_extremes.sql
+ to allow the behavior of the standby to be tested.
+
+
@@ -285,8 +346,10 @@ gmake check EXTRA_TESTS=collate.linux.utf8 LANG=en_US.utf8
file against the reference outputs stored in the
src/test/regress/expected directory. Any
differences are saved for your inspection in
- src/test/regress/regression.diffs. (Or you
- can run diff yourself, if you prefer.)
+ src/test/regress/regression.diffs.
+ (When running a test suite other than the core tests, these files
+ of course appear in the relevant subdirectory,
+ not src/test/regress.)
@@ -328,7 +391,7 @@ gmake check EXTRA_TESTS=collate.linux.utf8 LANG=en_US.utf8
To run the tests in a different locale when using the
temporary-installation method, pass the appropriate
locale-related environment variables on
- the make command line, for example:
+ the gmake command line, for example:
gmake check LANG=de_DE.utf8
@@ -348,7 +411,7 @@ gmake check NO_LOCALE=1
- In general, it is nevertheless advisable to try to run the
+ In general, it is advisable to try to run the
regression tests in the locale setup that is wanted for
production use, as this will exercise the locale- and
encoding-related code portions that will actually be used in
@@ -382,7 +445,7 @@ gmake check NO_LOCALE=1
results involving mathematical functions of double
precision columns have been observed. The float8 and
geometry tests are particularly prone to small differences
- across platforms, or even with different compiler optimization setting.
+ across platforms, or even with different compiler optimization settings.
Human eyeball comparison is needed to determine the real
significance of these differences which are usually 10 places to
the right of the decimal point.
@@ -444,14 +507,19 @@ exclusion of those that don't.
If the errors test results in a server crash
at the select infinite_recurse() command, it means that
the platform's limit on process stack size is smaller than the
- ]]>
- max_stack_depth]]>
- parameter indicates. This
+ parameter indicates. This
can be fixed by running the server under a higher stack
size limit (4MB is recommended with the default value of
max_stack_depth). If you are unable to do that, an
alternative is to reduce the value of max_stack_depth.
+
+
+ On platforms supporting getrlimit(), the server should
+ automatically choose a safe value of max_stack_depth;
+ so unless you've manually overridden this setting, a failure of this
+ kind is a reportable bug.
+
@@ -459,7 +527,7 @@ exclusion of those that don't.
The random test script is intended to produce
- random results. In rare cases, this causes the random regression
+ random results. In very rare cases, this causes that regression
test to fail. Typing:
diff results/random.out expected/random.out
@@ -468,6 +536,18 @@ diff results/random.out expected/random.out
not worry unless the random test fails repeatedly.
+
+
+ Configuration Parameters
+
+
+ When running the tests against an existing installation, some non-default
+ parameter settings could cause the tests to fail. For example, changing
+ parameters such as enable_seqscan or
+ enable_indexscan could cause plan changes that would
+ affect the results of tests that use EXPLAIN.
+
+