script is intended to produce
     random results.   In very rare cases, this causes that regression
     test to fail.  Typing:
<programlisting>
diff results/random.out expected/random.out
</programlisting>
     should produce only one or a few lines of differences.  You need
     not worry unless the random test fails repeatedly.
    </para>
   </sect2>

   <sect2 id="regress-evaluation-config-params">
    <title>Configuration Parameters</title>

    <para>
     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 <varname>enable_seqscan</varname> or
     <varname>enable_indexscan</varname> could cause plan changes that would
     affect the results of tests that use <command>EXPLAIN</command>.
    </para>
   </sect2>
  </sect1>

<!-- We might want to move the following section into the developer's guide. -->
  <sect1 id="regress-variant">
   <title>Variant Comparison Files</title>

   <para>
    Since some of the tests inherently produce environment-dependent
    results, we have provided ways to specify alternate <quote>expected</quote>
    result files.  Each regression test can have several comparison files
    showing possible results on different platforms.  There are two
    independent mechanisms for determining which comparison file is used
    for each test.
   </para>

   <para>
    The first mechanism allows comparison files to be selected for
    specific platforms.  There is a mapping file,
    <filename>src/test/regress/resultmap</filename>, that defines
    which comparison file to use for each platform.
    To eliminate bogus test <quote>failures</quote> for a particular platform,
    you first choose or make a variant result file, and then add a line to the
    <filename>resultmap</filename> file.
   </para>

   <para>
    Each line in the mapping file is of the form
<synopsis>
testname:output:platformpattern=comparisonfilename
</synopsis>
    The test name is just the name of the particular regression test
    module. The output value indicates which output file to check. For the
    standard regression tests, this is always <literal>out</literal>. The
    value corresponds to the file extension of the output file.
    The platform pattern is a pattern in the style of the Unix
    tool <command>expr</command> (that is, a regular expression with an implicit
    <literal>^</literal> anchor at the start).  It is matched against the
    platform name as printed by <command>config.guess</command>.
    The comparison file name is the base name of the substitute result
    comparison file.
   </para>

   <para>
    For example: some systems lack a working <literal>strtof</literal> function,
    for which our workaround causes rounding errors in the
    <filename>float4</filename> regression test.
    Therefore, we provide a variant comparison file,
    <filename>float4-misrounded-input.out</filename>, which includes
    the results to be expected on 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>