doc/extra-tests.texi

   1 @node Extra tests modules
   2 @section Extra tests modules
   3
   4 @cindex Extra tests modules
   5 @cindex C++ tests modules
   6 @cindex tests modules, C++
   7 @cindex long-running tests modules
   8 @cindex tests modules, long-running
   9 @cindex privileged tests modules
  10 @cindex tests modules, privileged
  11 @cindex unportable tests modules
  12 @cindex tests modules, unportable
  13 Test modules can be marked with some special status attributes.  When a
  14 test module has such an attribute, @code{gnulib-tool --import} will not
  15 include it by default.
  16
  17 The supported status attributes are:
  18
  19 @table @code
  20 @item c++-test
  21 Indicates that the test is testing C++ interoperability.  Such a test is
  22 useful in a C++ or mixed C/C++ package, but is useless in a C package.
  23
  24 @item longrunning-test
  25 Indicates that the test takes a long time to compile or execute (more
  26 than five minutes or so).  Such a test is better avoided in a release
  27 that is made for the general public.
  28
  29 @item privileged-test
  30 Indicates that the test will request special privileges, for example,
  31 ask for the superuser password.  Such a test may hang when run
  32 non-interactively and is therefore better avoided in a release that is
  33 made for the general public.
  34
  35 @item unportable-test
  36 Indicates that the test is known to fail on some systems, and that
  37 there is no workaround about it.  Such a test is better avoided in a
  38 release that is made for the general public.
  39 @end table
  40
  41 @code{gnulib-tool --import --with-tests} will not include tests marked with
  42 these attributes by default.  When @code{gnulib-tool} is invoked with one
  43 of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
  44 @code{--with-privileged-tests}, @code{--with-unportable-tests}, it
  45 will include tests despite the corresponding special status attribute.
  46 When @code{gnulib-tool} receives the option @code{--with-all-tests},
  47 it will include all tests regardless of their status attributes.
  48
  49 @code{gnulib-tool --create-testdir --with-tests} and
  50 @code{gnulib-tool --create-megatestdir --with-tests} by default include all
  51 tests of modules specified on the command line, regardless of their status
  52 attributes.  Tests of modules occurring as dependencies are not included
  53 by default if they have one of these status attributes.  The options
  54 @code{--with-c++-tests}, @code{--with-longrunning-tests},
  55 @code{--with-privileged-tests}, @code{--with-unportable-tests} are
  56 recognized here as well.  Additionally, @code{gnulib-tool} also
  57 understands the options @code{--without-c++-tests},
  58 @code{--without-longrunning-tests}, @code{--without-privileged-tests},
  59 @code{--without-unportable-tests}.
  60
  61 In order to mark a module with a status attribute, you need to add it
  62 to the module description, like this:
  63
  64 @example
  65 Status:
  66 longrunning-test
  67 @end example
  68
  69 If only a part of a test deserves a particular status attribute, you
  70 can split the module into a primary and a secondary test module,
  71 say @code{foo-tests} and @code{foo-extra-tests}.  Then add a dependency
  72 from @code{foo-tests} to @code{foo-extra-tests}, and mark the
  73 @code{foo-extra-tests} with the particular status attribute.