autopkgtest/autopkgtest.md

   1 Autopkgtest - Defining tests for Debian packages
   2 ================================================
   3
   4 This document describes how the autopkgtest tester core (the program
   5 `adt-run`) interprets and executes tests found in Debian source
   6 packages.
   7
   8 Overview
   9 --------
  10
  11 The source package provides a test metadata file `debian/tests/control`.
  12 This is a file containing zero or more RFC822-style stanzas, along these
  13 lines:
  14
  15     Tests: fred bill bongo
  16     Restrictions: needs-root breaks-testbed
  17
  18 This example defines three tests, called `fred`, `bill` and `bongo`. The
  19 tests will be performed by executing `debian/tests/fred`,
  20 `debian/tests/bill`, etc. Each test program should, on success, exit
  21 with status 0 and print nothing to stderr; if a test exits nonzero, or
  22 prints to stderr, it is considered to have failed.
  23
  24 The cwd of each test is guaranteed to be the root of the source package,
  25 which will have been unpacked but not built. *However* note that the
  26 tests must test the *installed* version of the program. Tests may not
  27 modify the source tree (and may not have write access to it).
  28
  29 If the file to be executed has no execute bits set, `chmod a+x` is
  30 applied to it (this means that tests can be added in patches without the
  31 need for additional chmod; contrast this with debian/rules).
  32
  33 During execution of the test, the environment variable `$ADTTMP` will
  34 point to a directory for the execution of this particular test, which
  35 starts empty and will be deleted afterwards (so there is no need for the
  36 test to clean up files left there).
  37
  38 If tests want to create artifacts which are useful to attach to test
  39 results, such as additional log files or screenshots, they can put them
  40 into the directory specified by the `$ADT_ARTIFACTS` environment
  41 variable. When using the `--output-dir` option, they will be copied into
  42 `outputdir/artifacts/`.
  43
  44 Tests must declare all applicable Restrictions - see below.
  45
  46 Control fields
  47 --------------
  48
  49 The fields which may appear in debian/tests/control stanzas are:
  50
  51 - **Tests:** *name-of-test [name-of-another-test ...]*
  52
  53   This field names the tests which are defined by this stanza, and map to
  54   executables/scripts in the test directory. All of the other fields in the
  55   same stanza apply to all of the named tests. Either this field or
  56   `Test-Command:` must be present.
  57
  58   Test names are separated by whitespace and should contain only characters
  59   which are legal in package names. It is permitted, but not encouraged, to use
  60   upper-case characters as well.
  61
  62 - **Test-Command:** *shell command*
  63
  64   If your test only contains a shell command or two, or you want to re-use an
  65   existing upstream test executable and just need to wrap it with some command
  66   like `dbus-launch` or `env`, you can use this field to specify the shell
  67   command directly. It will be run under `bash -e`. This is mutually exclusive
  68   with the `Tests:` field.
  69
  70 - **Restrictions:** *restriction-name [another-restriction-name ...]*
  71
  72   Declares some restrictions or problems with the tests defined in this
  73   stanza. Depending on the test environment capabilities, user requests, and so
  74   on, restrictions can cause tests to be skipped or can cause the test to be
  75   run in a different manner. Tests which declare unknown restrictions will be
  76   skipped. See below for the defined restrictions.
  77
  78 - **Features:** *feature-name [another-feature-name ...]*
  79
  80   Declares some additional capabilities or good properties of the tests defined
  81   in this stanza. Any unknown features declared will be completely ignored. See
  82   below for the defined features.
  83
  84 - **Depends:** *dpkg dependency field syntax*
  85
  86   Declares that the specified packages must be installed for the test to go
  87   ahead. This supports all features of dpkg dependencies (see
  88   <https://www.debian.org/doc/debian-policy/ch-relationships.html>), plus the
  89   following extensions:
  90
  91   `@` stands for the package(s) generated by the source package containing the
  92   tests; each dependency (strictly, or-clause, which may contain `|`s but not
  93   commas) containing `@` is replicated once for each such binary package, with
  94   the binary package name substituted for each `@` (but normally `@` should
  95   occur only once and without a version restriction).
  96
  97   `@builddeps@` will be replaced by the package's `Build-Depends:`,
  98   `Build-Depends-Indep:`, and `build-essential`. This is useful if you have
  99   many build dependencies which are only necessary for running the test suite
 100   and you don't want to replicate them in the test `Depends:`. However, please
 101   use this sparingly, as this can easily lead to missing binary package
 102   dependencies being overlooked if they get pulled in via build dependencies.
 103
 104   If no Depends field is present, `Depends: @` is assumed. Note that the source
 105   tree's Build-Dependencies are *not* necessarily installed, and if you specify
 106   any Depends, no binary packages from the source are installed unless
 107   explicitly requested.
 108
 109 - **Tests-Directory:** *path*
 110
 111   Replaces the path segment `debian/tests` in the filenames of the test
 112   programs with `path`. I. e., the tests are run by executing
 113   `built/source/tree/path/testname`. `path` must be a relative path and is
 114   interpreted starting from the root of the built source tree.
 115
 116   This allows tests to live outside the debian/ metadata area, so that they can
 117   more palatably be shared with non-Debian distributions.
 118
 119 - **Classes:** *class-1, class-2, ...*
 120
 121   Most package tests should work in a minimal environment and are usually not
 122   hardware specific. However, some packages like the kernel, X.org, or graphics
 123   drivers should be tested on particular hardware, and also run on a set of
 124   different platforms rather than just a single virtual testbeds.
 125
 126   This field can specify a list of abstract class names such as "desktop" or
 127   "graphics-driver". Consumers of autopkgtest can then map these class names to
 128   particular machines/platforms/policies.  Unknown class names should be
 129   ignored.
 130
 131   This is purely an informational field for autopkgtest itself and will be
 132   ignored.
 133
 134 Any unknown fields will cause the whole stanza to be skipped.
 135
 136 Defined restrictions
 137 --------------------
 138
 139 - **rw-build-tree**
 140
 141   The test(s) needs write access to the built source tree (so it may need to be
 142   copied first). Even with this restriction, the test is not allowed to make
 143   any change to the built source tree which (i) isn't cleaned up by
 144   debian/rules clean, (ii) affects the future results of any test, or (iii)
 145   affects binary packages produced by the build tree in the future.
 146
 147 - **breaks-testbed**
 148
 149   The test, when run, is liable to break the testbed system. This includes
 150   causing data loss, causing services that the machine is running to
 151   malfunction, or permanently disabling services; it does not include causing
 152   services on the machine to temporarily fail.
 153
 154   When this restriction is present the test will usually be skipped unless the
 155   testbed's virtualisation arrangements are sufficiently powerful, or
 156   alternatively if the user explicitly requests.
 157
 158 - **needs-root**
 159
 160   The test script must be run as root.
 161
 162 - **build-needed**
 163
 164   The tests need to be run from a built source tree. The test runner will build
 165   the source tree (honouring the source package's build dependencies), before
 166   running the tests. However, the tests are *not* entitled to assume that the
 167   source package's build dependencies will be installed when the test is run.
 168
 169   Please use this considerately, as for large builds it unnecessarily builds
 170   the entire project when you only need a tiny subset (like the tests/
 171   subdirectory). It is often possible to run `make -C tests` instead, or copy
 172   the test code to `$ADTTMP` and build it there with some custom commands. This
 173   cuts down the load on the Continuous Integration servers and also makes tests
 174   more robust as it prevents accidentally running them against the built source
 175   tree instead of the installed packages.
 176
 177 - **allow-stderr**
 178
 179   Output to stderr is not considered a failure. This is useful for tests which
 180   write e. g. lots of logging to stderr.
 181
 182 - **isolation-container**
 183
 184   The test wants to start services or open network TCP ports. This commonly
 185   fails in a simple chroot/schroot, so tests need to be run in their own
 186   container (e. g. adt-virt-lxc) or their own machine/VM (e. g. adt-virt-qemu
 187   or adt-virt-null). When running the test in a virtualization server which
 188   does not provide this (like adt-virt-schroot) it will be skipped.
 189
 190 - **isolation-machine**
 191
 192   The test wants to interact with the kernel, reboot the machine, or other
 193   things which fail in a simple schroot and even a container.  Those tests need
 194   to be run in their own machine/VM (e. g.  adt-virt-qemu or
 195   adt-virt-null). When running the test in a virtualization server which does
 196   not provide this it will be skipped.
 197
 198 - **needs-recommends**
 199
 200   Enable installation of recommended packages in apt for the test
 201   dependencies. This does not affect build dependencies.
 202
 203 Defined features
 204 ----------------
 205
 206 There are no currently defined Features.
 207
 208 Source package header
 209 ---------------------
 210
 211 To allow test execution environments to discover packages which provide
 212 tests, their source packages should have a `Testsuite:` header
 213 containing `autopkgtest` (which is currently the only defined value).
 214 Multiple values get comma separated, as usual in control files.
 215
 216 This tag is added automatically by dpkg-source version 1.17.11 or later.
 217 For earlier Debian/Ubuntu releases you need to set it manually in
 218 debian/control by adding
 219
 220     XS-Testsuite: autopkgtest
 221
 222 in the `Source:` paragraph.
 223
 224 Implicit test control file for known package types
 225 --------------------------------------------------
 226
 227 There are groups of similarly-structured packages for which the contents
 228 of `debian/tests/control` would be mostly identical. For those packages,
 229 if `debian/tests/control` is absent, an implicit control file is
 230 assumed. Those packages do not have to provide anything else, although
 231 they should still include an appropriate source package header
 232 (`XS-Testsuite`) so that they can be discovered in the archive.
 233
 234 ### Ruby packages
 235
 236 The source package must contain at least one of the following files:
 237
 238 -   `debian/ruby-test-files.yaml`
 239 -   `debian/ruby-tests.rb`
 240 -   `debian/ruby-tests.rake`
 241
 242 Implied control file: :
 243
 244     Test-Command: gem2deb-test-runner --autopkgtest 2>&1
 245     Depends: @, @builddeps@, gem2deb-test-runner
 246
 247 *Note:* `gem2deb` will be filtered out of the `Depends:` field, as it is
 248 not needed to run the tests for installed packages.
 249
 250 Packages should declare `Testsuite: autopkgtest-pkg-ruby` in
 251 `debian/control`.
 252
 253 ### Perl packages
 254
 255 The source package must contain a `t/` directory and at least one of the
 256 following files:
 257
 258 -   `Makefile.PL`
 259 -   `Build.PL`
 260
 261 Implied control file: :
 262
 263     Test-Command: /usr/share/pkg-perl-autopkgtest/runner build-deps
 264     Depends: @, @builddeps@, pkg-perl-autopkgtest
 265
 266     Test-Command: /usr/share/pkg-perl-autopkgtest/runner runtime-deps
 267     Depends: @, pkg-perl-autopkgtest
 268
 269 Packages should declare `Testsuite: autopkgtest-pkg-perl` in
 270 `debian/control`.
 271
 272 Reboot during a test
 273 --------------------
 274
 275 Some testbeds support rebooting; for those, the testbed will have an
 276 `autopkgtest-reboot` command which tests can call to cause a reboot.
 277 **Do not** use `reboot` and similar commands directly! They will cause
 278 testbeds like `null` or `schroot` to reboot the entire host, and even
 279 for `qemu` it will just cause the test to fail as there is no state
 280 keeping to resume a test at the right position after reboot.
 281
 282 The particular steps for a rebooting tests are:
 283
 284 -   The test calls `autopkgtest-reboot my_mark` with a "mark"
 285     identifier. `autopkgtest-reboot` will cause the test to terminate
 286     (with `SIGKILL`).
 287 -   `adt-run` backs up the current state of the test source tree and any
 288     `$ADT_ARTIFACTS` that were created so far, reboots the testbed, and
 289     restores the test source tree and artifacts.
 290 -   The test gets run again, this time with a new environment variable
 291     `$ADT_REBOOT_MARK` containing the argument to `autopkgtest-reboot`,
 292     e. g. `my_mark`.
 293 -   The test needs to check `$ADT_REBOOT_MARK` and jump to the
 294     appropriate point. A nonexisting variable means "start from the
 295     beginning".
 296
 297 This example test will reboot the testbed two times in between:
 298
 299     #!/bin/sh -e
 300     case "$ADT_REBOOT_MARK" in
 301       "") echo "test beginning"; autopkgtest-reboot mark1 ;;
 302       mark1) echo "test in mark1"; autopkgtest-reboot mark2 ;;
 303       mark2) echo "test in mark2" ;;
 304     esac
 305     echo "test end"