gnulib/doc/extra-tests.texi

@node Extra tests modules
@section Extra tests modules

@cindex Extra tests modules
@cindex C++ tests modules
@cindex tests modules, C++
@cindex long-running tests modules
@cindex tests modules, long-running
@cindex privileged tests modules
@cindex tests modules, privileged
@cindex unportable tests modules
@cindex tests modules, unportable
Test modules can be marked with some special status attributes.  When a
test module has such an attribute, @code{gnulib-tool --import} will not
include it by default.

The supported status attributes are:

@table @code
@item c++-test
Indicates that the test is testing C++ interoperability.  Such a test is
useful in a C++ or mixed C/C++ package, but is useless in a C package.

@item longrunning-test
Indicates that the test takes a long time to compile or execute (more
than five minutes or so).  Such a test is better avoided in a release
that is made for the general public.

@item privileged-test
Indicates that the test will request special privileges, for example,
ask for the superuser password.  Such a test may hang when run
non-interactively and is therefore better avoided in a release that is
made for the general public.

@item unportable-test
Indicates that the test is known to fail on some systems, and that
there is no workaround about it.  Such a test is better avoided in a
release that is made for the general public.
@end table

@code{gnulib-tool --import --with-tests} will not include tests marked with
these attributes by default.  When @code{gnulib-tool} is invoked with one
of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
@code{--with-privileged-tests}, @code{--with-unportable-tests}, it
will include tests despite the corresponding special status attribute.
When @code{gnulib-tool} receives the option @code{--with-all-tests},
it will include all tests regardless of their status attributes.

@code{gnulib-tool --create-testdir --with-tests} and
@code{gnulib-tool --create-megatestdir --with-tests} by default include all
tests of modules specified on the command line, regardless of their status
attributes.  Tests of modules occurring as dependencies are not included
by default if they have one of these status attributes.  The options
@code{--with-c++-tests}, @code{--with-longrunning-tests},
@code{--with-privileged-tests}, @code{--with-unportable-tests} are
recognized here as well.  Additionally, @code{gnulib-tool} also
understands the options @code{--without-c++-tests},
@code{--without-longrunning-tests}, @code{--without-privileged-tests},
@code{--without-unportable-tests}.

In order to mark a module with a status attribute, you need to add it
to the module description, like this:

@example
Status:
longrunning-test
@end example

If only a part of a test deserves a particular status attribute, you
can split the module into a primary and a secondary test module,
say @code{foo-tests} and @code{foo-extra-tests}.  Then add a dependency
from @code{foo-tests} to @code{foo-extra-tests}, and mark the
@code{foo-extra-tests} with the particular status attribute.