<!-- doc/src/sgml/regress.sgml -->

 <chapter id="regress">
  <title>Regression Tests</title>

  <indexterm zone="regress">
   <primary>regression tests</primary>
  </indexterm>

  <indexterm zone="regress">
   <primary>test</primary>
  </indexterm>

  <para>
   The regression tests are a comprehensive set of tests for the SQL
   implementation in <productname>PostgreSQL</productname>.  They test
   standard SQL operations as well as the extended capabilities of
   <productname>PostgreSQL</productname>.
  </para>

  <sect1 id="regress-run">
   <title>Running the Tests</title>

  <para>
   The regression tests can be run against an already installed and
   running server, or using a temporary installation within the build
   tree.  Furthermore, there is a <quote>parallel</quote> and a
   <quote>sequential</quote> 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 adds confidence that
   interprocess communication and locking are working correctly.
   Some tests may run sequentially even in the <quote>parallel</quote>
   mode in case this is required by the test.
  </para>

  <sect2 id="regress-run-temp-inst">
   <title>Running the Tests Against a Temporary Installation</title>

  <para>
   To run the parallel regression tests after building but before installation,
   type:
<screen>
make check
</screen>
   in the top-level directory.  (Or you can change to
   <filename>src/test/regress</filename> and run the command there.)
   Tests which are run in parallel are prefixed with <quote>+</quote>, and
   tests which run sequentially are prefixed with <quote>-</quote>.
   At the end you should see something like:
<screen>
<computeroutput>
# All 213 tests passed.
</computeroutput>
</screen>
   or otherwise a note about which tests failed.  See <xref
   linkend="regress-evaluation"/> below before assuming that a
   <quote>failure</quote> represents a serious problem.
  </para>

   <para>
    Because this test method runs a temporary server, it will not work
    if you did the build as the root user, since the server will not start as
    root.  Recommended procedure is not to do the build as root, or else to
    perform testing after completing the installation.
   </para>

   <para>
    If you have configured <productname>PostgreSQL</productname> to install
    into a location where an older <productname>PostgreSQL</productname>
    installation already exists, and you perform <literal>make check</literal>
    before installing the new version, you might find that the tests fail
    because the new programs try to use the already-installed shared
    libraries.  (Typical symptoms are complaints about undefined symbols.)
    If you wish to run the tests before overwriting the old installation,
    you'll need to build with <literal>configure --disable-rpath</literal>.
    It is not recommended that you use this option for the final installation,
    however.
   </para>

   <para>
    The parallel regression test starts quite a few processes under your
    user ID.  Presently, the maximum concurrency is twenty parallel test
    scripts, which means forty processes: there's a server process and a
    <application>psql</application> process for each test script.
    So if your system enforces a per-user limit on the number of processes,
    make sure this limit is at least fifty or so, else you might get
    random-seeming failures in the parallel test.  If you are not in
    a position to raise the limit, you can cut down the degree of parallelism
    by setting the <literal>MAX_CONNECTIONS</literal> parameter.  For example:
<screen>
make MAX_CONNECTIONS=10 check
</screen>
    runs no more than ten tests concurrently.
   </para>
  </sect2>

  <sect2 id="regress-run-existing-inst">
   <title>Running the Tests Against an Existing Installation</title>

  <para>
   To run the tests after installation