these systems.  To silence the bogus
    <quote>failure</quote> message on <systemitem>Cygwin</systemitem>
    platforms, <filename>resultmap</filename> includes:
<programlisting>
float4:out:.*-.*-cygwin.*=float4-misrounded-input.out
</programlisting>
    which will trigger on any machine where the output of
    <command>config.guess</command> matches <literal>.*-.*-cygwin.*</literal>.
    Other lines in <filename>resultmap</filename> select the variant comparison
    file for other platforms where it's appropriate.
   </para>

   <para>
    The second selection mechanism for variant comparison files is
    much more automatic: it simply uses the <quote>best match</quote> among
    several supplied comparison files.  The regression test driver
    script considers both the standard comparison file for a test,
    <literal><replaceable>testname</replaceable>.out</literal>, and variant files named
    <literal><replaceable>testname</replaceable>_<replaceable>digit</replaceable>.out</literal>
    (where the <replaceable>digit</replaceable> is any single digit
    <literal>0</literal>-<literal>9</literal>).  If any such file is an exact match,
    the test is considered to pass; otherwise, the one that generates
    the shortest diff is used to create the failure report.  (If
    <filename>resultmap</filename> includes an entry for the particular
    test, then the base <replaceable>testname</replaceable> is the substitute
    name given in <filename>resultmap</filename>.)
   </para>

   <para>
    For example, for the <literal>char</literal> test, the comparison file
    <filename>char.out</filename> contains results that are expected
    in the <literal>C</literal> and <literal>POSIX</literal> locales, while
    the file <filename>char_1.out</filename> contains results sorted as
    they appear in many other locales.
   </para>

   <para>
    The best-match mechanism was devised to cope with locale-dependent
    results, but it can be used in any situation where the test results
    cannot be predicted easily from the platform name alone.  A limitation of
    this mechanism is that the test driver cannot tell which variant is
    actually <quote>correct</quote> for the current environment; it will just pick
    the variant that seems to work best.  Therefore it is safest to use this
    mechanism only for variant results that you are willing to consider
    equally valid in all contexts.
   </para>

  </sect1>

  <sect1 id="regress-tap">
   <title>TAP Tests</title>

   <para>
    Various tests, particularly the client program tests
    under <filename>src/bin</filename>, use the Perl TAP tools and are run
    using the Perl testing program <command>prove</command>.  You can pass
    command-line options to <command>prove</command> by setting
    the <command>make</command> variable <varname>PROVE_FLAGS</varname>, for example:
<programlisting>
make -C src/bin check PROVE_FLAGS='--timer'
</programlisting>
    See the manual page of <command>prove</command> for more information.
   </para>

   <para>
    The <command>make</command> variable <varname>PROVE_TESTS</varname>
    can be used to define a whitespace-separated list of paths relative
    to the <filename>Makefile</filename> invoking <command>prove</command>
    to run the specified subset of tests instead of the default
    <filename>t/*.pl</filename>.  For example:
<programlisting>
make check PROVE_TESTS='t/001_test1.pl t/003_test3.pl'
</programlisting>
   </para>

   <para>
    The TAP tests require the Perl module <literal>IPC::Run</literal>.
    This module is available from
    <ulink url="https://metacpan.org/dist/IPC-Run">CPAN</ulink>
    or an operating system package.
    They also require <productname>PostgreSQL</productname> to be
    configured with the option <option>--enable-tap-tests</option>.
   </para>

   <para>
    Generically speaking, the TAP tests will test the executables in a
    previously-installed installation tree if you say <literal>make
    installcheck</literal>,