<refentry id="reference-regress">

<refmeta>
<refentrytitle>gogui-regress</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source-name">GoGui</refmiscinfo>
<refmiscinfo class="version">GoGui &version;</refmiscinfo>
<refmiscinfo class="manual">GoGui Reference</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gogui-regress</refname>
<refpurpose>
Runs GTP regression tests.
</refpurpose>
</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>
<command>gogui-regress</command>
<arg><option>-config</option> <replaceable>file</replaceable></arg>
<arg><option>-gtpfile</option> <replaceable>file</replaceable></arg>
<arg><option>-long</option></arg>
<arg><option>-output</option> <replaceable>directory</replaceable></arg>
<arg><option>-verbose</option></arg>
<arg choice="plain"><replaceable>program</replaceable></arg>
<arg choice="plain" rep="repeat">
<replaceable>test.tst</replaceable>
</arg>
</cmdsynopsis>

<cmdsynopsis>
<command>gogui-regress</command>
<arg choice="plain"><option>-help</option></arg>
</cmdsynopsis>

<cmdsynopsis>
<command>gogui-regress</command>
<arg choice="plain"><option>-version</option></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsection>
<title>Description</title>
<para>
Runs a list of regression tests for a Go program supporting the Go Text
Protocol, and formats the output as HTML.
The regression tests are GTP files, which use the special comment
<userinput>#?</userinput>, as used for the
<ulink url="http://www.gnu.org/software/gnugo/gnugo.html">GNU Go</ulink>
regression tests (see section
<ulink url="http://www.gnu.org/software/gnugo/gnugo_20.html#SEC205">
Regression testing</ulink> of the GNU Go documentation).
The regular expression syntax for the expected responses is
mostly compatible to the one used by the GNU Go regression test suite,
see the documentation for
<ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">java.util.regex.Pattern</ulink>
for a complete description.
</para>
<para>
Test names that start with a '@' are interpreted as files containing a test
suite. The file with the corresponding name (excluding the '@') is read
and every non-empty line that does not start with the comment character '#'
is added to the list of test names. The files are allowed to contain names
of other test suites.
</para>
<para>
The main output file is <filename>index.html</filename>.
For each test file
<filename><replaceable>test</replaceable>.tst</filename>,
additional files with name
<filename><replaceable>test</replaceable>.html</filename> and
<filename><replaceable>test</replaceable>.out.html</filename>
are generated.
Additionally, a text file <filename>summary.dat</filename> is generated,
with a table row containing the most important summary statistics.
gogui-regress will start a new instance of the Go program for each test and
use the directory of the test file as the working directory for the Go
program.
</para>
<para>
The return value of gogui-regress is 0, if all tests
completed successfully with no unexpected fails, 1 if there was at
least one unexpected fail, and 2 if the Go program crashed or some other
error occurred.
</para>
</refsection>

<refsection>
<title>Options</title>
<variablelist>

<varlistentry>
<term>
<option>-config</option> <replaceable>file</replaceable>
</term>
<listitem>
<para>
Read command line options and arguments from the given file.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-gtpfile</option> <replaceable>file</replaceable>
</term>
<listitem>
<para>
File with GTP commands to execute before each test. This file can be used
to configure engine parameters. If a command from the file fails, the program
will exit with an error message.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-help</option>
</term>
<listitem>
<para>
Display help and exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-long</option></term>
<listitem>
<para>
Print longer output to standard output, one line per test.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-output</option> <replaceable>directory</replaceable>
</term>
<listitem>
<para>
Write output files to the given directory.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>-verbose</option></term>
<listitem>
<para>
Print the GTP stream to the Go program to standard error.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-version</option>
</term>
<listitem>
<para>
Print version and exit.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
<!-- Empty paragraph to enforce some space in JEditorPane (Java 1.5.0) -->
</para>

</refsection>

</refentry>
