doc/README.package-tests

   1         AUTOPKGTEST - DEFINING TESTS FOR PACKAGES
   2         =========================================
   3
   4 This document describes how the autopkgtest tester core (the program
   5 `adt-run') interprets and executes tests found in source packages.
   6
   7
   8
   9 The source package provides a test metadata file
  10 debian/tests/control. This is a file containing zero or more
  11 RFC822-style stanzas, along these lines:
  12
  13         Tests: fred bill bongo
  14         Restrictions: needs-root breaks-computer
  15
  16 This example defines three tests, called `fred', `bill' and `bongo'.
  17 The tests will be performed by executing debian/tests/fred,
  18 debian/tests/bill, etc.  Each test program should, on success, exit
  19 with status 0 and print nothing to stderr; if a test exits nonzero, or
  20 prints to stderr, it is considered to have failed.
  21
  22 The cwd of each test is guaranteed to be the root of the source
  23 package which will have been built.  HOWEVER note that the tests must
  24 test the INSTALLED version of the program.  Tests may not modify the
  25 source tree (and may not have write access to it).
  26
  27 If the file to be executed has no execute bits set, chmod a+x is
  28 applied to it (this means that tests can be added in patches without
  29 the need for additional chmod; contrast this with debian/rules).
  30
  31 During execution of the test, the environment variable TMPDIR will
  32 point to a directory for the execution of this particular test, which
  33 starts empty and will be deleted afterwards (so there is no need for
  34 the test to clean up files left there).
  35
  36 Tests must declare all applicable Restrictions - see below.
  37
  38
  39 The fields which may appear in the RFC822-style stanza are:
  40
  41   Tests: <name-of-test> [<name-of-another-test> ...]
  42
  43     This field is mandatory.  It names the tests which are defined by
  44     this stanza.  All of the other fields in the same stanza apply to
  45     all of the named tests.
  46
  47     Test names are separated by whitespace and should contain only
  48     characters which are legal in package names, plus `/'.
  49
  50   Restrictions: <restriction-name> [<another-restriction-name> ...]
  51
  52     Declares some restrictions or problems with the tests defined in
  53     this stanza.  Depending on the test environment capabilities, user
  54     requests, and so on, restrictions can cause tests to be skipped or
  55     can cause the test to be run in a different manner.  Tests which
  56     declare unknown restrictions will be skipped.  See below for the
  57     defined restrictions.
  58
  59   Features: <feature-name> [<another-feature-name> ...]
  60
  61     Declares some additional capabilities or good properties of the
  62     tests defined in this stanza.  Any unknown features declared will
  63     be completely ignored.  See below for the defined features.
  64
  65   Depends: <dpkg dependcy field syntax>
  66
  67     Declares that the specified packages must be installed for the
  68     test to go ahead.  `@' stands for the package(s) generated by the
  69     source package containing the tests; each dependency (strictly,
  70     or-clause, which may contain `|'s but not commas) containing `@'
  71     is replicated once for each such binary package, with the binary
  72     package name substituted for each `@' (but normally `@' should
  73     occur only once and without a version restriction).
  74
  75     If no Depends field is present, `Depends: @' is assumed.  Note
  76     that the source tree's Build-Dependencies are _not_ necessarily
  77     installed, and if you specify any Depends, no binary packages from
  78     the source are installed unless explicitly requested.
  79
  80   Tests-Directory: <path>
  81
  82     Replaces the path segment `debian/tests' in the filenames of the
  83     test programs with <path>.  Ie, the tests are run by executing
  84     /path/to/built/source/tree/<path>/<name-of-test>.  <path> must be
  85     a relative path and is interpreted starting from the root of the
  86     built source tree.
  87
  88     This allows tests to live outside the debian/ metadata area, so
  89     that they can more palatably be shared with non-Debian
  90     distributions.
  91
  92 Any unknown fields will cause the whole stanza to be skipped.
  93
  94
  95 The defined Restrictions are:
  96
  97   rw-build-tree
  98
  99     The test(s) needs write access to the built source tree (so it may
 100     need to be copied first).  Even with this restriction, the test is
 101     not allowed to make any change to the built source tree which (i)
 102     isn't cleaned up by debian/rules clean, (ii) affects the future
 103     results of any test, or (iii) affects binary packages produced by
 104     the build tree in the future.
 105
 106   breaks-testbed
 107
 108     The test, when run, is liable to break the testbed system.  This
 109     includes causing data loss, causing services that the machine is
 110     running to malfunction, or permanently disabling services; it does
 111     not include causing services on the machine to temporarily fail.
 112
 113     When this restriction is present the test will usually be skipped
 114     unless the testbed's virtualisation arrangements are sufficiently
 115     powerful, or alternatively if the user explicitly requests.
 116
 117   needs-root
 118
 119     The test script must be run as root.
 120
 121
 122 The currently defined Features are:
 123
 124   no-build-needed
 125
 126     The tests can run in an unbuilt tree.