tools/adt-setup-vm: Disable downloading of package translations to save some bandwidth
[autopkgtest/autopkgtest.git] / 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 Overview
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-testbed
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 unpacked but not built.  HOWEVER note
24 that the tests must test the INSTALLED version of the program.  Tests
25 may not modify the 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 ADTTMP 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 If tests want to create artifacts which are useful to attach to test
37 results, such as additional log files or screenshots, they can put them
38 into the directory specified by the ADT_ARTIFACTS environment variable.
39 When using the --output-dir option, they will be copied into
40 <outputdir>/artifacts/.
41
42 Tests must declare all applicable Restrictions - see below.
43
44
45 Control fields
46 --------------
47 The fields which may appear in debian/tests/control stanzas are:
48
49   Tests: <name-of-test> [<name-of-another-test> ...]
50
51     This field is mandatory.  It names the tests which are defined by
52     this stanza.  All of the other fields in the same stanza apply to
53     all of the named tests.
54
55     Test names are separated by whitespace and should contain only
56     characters which are legal in package names. It is permitted, but
57     not encouraged, to use upper-case characters as well.
58
59   Restrictions: <restriction-name> [<another-restriction-name> ...]
60
61     Declares some restrictions or problems with the tests defined in
62     this stanza.  Depending on the test environment capabilities, user
63     requests, and so on, restrictions can cause tests to be skipped or
64     can cause the test to be run in a different manner.  Tests which
65     declare unknown restrictions will be skipped.  See below for the
66     defined restrictions.
67
68   Features: <feature-name> [<another-feature-name> ...]
69
70     Declares some additional capabilities or good properties of the
71     tests defined in this stanza.  Any unknown features declared will
72     be completely ignored.  See below for the defined features.
73
74   Depends: <dpkg dependency field syntax>
75
76     Declares that the specified packages must be installed for the
77     test to go ahead. This supports all features of dpkg dependencies
78     (see https://www.debian.org/doc/debian-policy/ch-relationships.html),
79     plus the following extensions:
80
81     `@' stands for the package(s) generated by the source package
82     containing the tests; each dependency (strictly, or-clause, which
83     may contain `|'s but not commas) containing `@' is replicated once
84     for each such binary package, with the binary package name
85     substituted for each `@' (but normally `@' should occur only once
86     and without a version restriction).
87
88     `@builddeps@' will be replaced by the package's Build-Depends:,
89     Build-Depends-Indep:, and "make". This is useful if you have many build
90     dependencies which are only necessary for running the test suite and
91     you don't want to replicate them in the test Depends:. However, please
92     use this sparingly, as this can easily lead to missing binary package
93     dependencies being overlooked if they get pulled in via build
94     dependencies.
95
96     If no Depends field is present, `Depends: @' is assumed.  Note
97     that the source tree's Build-Dependencies are _not_ necessarily
98     installed, and if you specify any Depends, no binary packages from
99     the source are installed unless explicitly requested.
100
101   Tests-Directory: <path>
102
103     Replaces the path segment `debian/tests' in the filenames of the
104     test programs with <path>.  Ie, the tests are run by executing
105     /path/to/built/source/tree/<path>/<name-of-test>.  <path> must be
106     a relative path and is interpreted starting from the root of the
107     built source tree.
108
109     This allows tests to live outside the debian/ metadata area, so
110     that they can more palatably be shared with non-Debian
111     distributions.
112
113 Any unknown fields will cause the whole stanza to be skipped.
114
115 Defined restrictions
116 --------------------
117   rw-build-tree
118
119     The test(s) needs write access to the built source tree (so it may
120     need to be copied first).  Even with this restriction, the test is
121     not allowed to make any change to the built source tree which (i)
122     isn't cleaned up by debian/rules clean, (ii) affects the future
123     results of any test, or (iii) affects binary packages produced by
124     the build tree in the future.
125
126   breaks-testbed
127
128     The test, when run, is liable to break the testbed system.  This
129     includes causing data loss, causing services that the machine is
130     running to malfunction, or permanently disabling services; it does
131     not include causing services on the machine to temporarily fail.
132
133     When this restriction is present the test will usually be skipped
134     unless the testbed's virtualisation arrangements are sufficiently
135     powerful, or alternatively if the user explicitly requests.
136
137   needs-root
138
139     The test script must be run as root.
140
141   build-needed
142
143     The tests need to be run from a built source tree.  The test
144     runner will build the source tree (honouring the source package's
145     build dependencies), before running the tests.  However, the tests
146     are NOT entitled to assume that the source package's build
147     dependencies will be installed when the test is run.
148
149     Please use this considerately, as for large builds it unnecessarily
150     builds the entire project when you only need a tiny subset (like the
151     tests/ subdirectory).  It is often possible to run "make -C tests"
152     instead, or copy the test code to $ADTTMP and build it there with some
153     custom commands.  This cuts down the load on the Continuous
154     Integration servers and also makes tests more robust as it prevents
155     accidentally running them against the built source tree instead of the
156     installed packages.
157
158   allow-stderr
159
160     Output to stderr is not considered a failure. This is useful for
161     tests which write e. g. lots of logging to stderr.
162
163   isolation-container
164
165     The test wants to start services or open network TCP ports. This
166     commonly fails in a simple chroot/schroot, so tests need to be run
167     in their own container (e. g. adt-virt-lxc) or their own machine/VM
168     (e. g. adt-virt-qemu or adt-virt-null). When running the test in a
169     virtualization server which does not provide this (like
170     adt-virt-schroot) it will be skipped.
171
172   isolation-machine
173
174     The test wants to interact with the kernel, reboot the machine, or
175     other things which fail in a simple schroot and even a container.
176     Those tests need to be run in their own machine/VM (e. g.
177     adt-virt-qemu or adt-virt-null). When running the test in a
178     virtualization server which does not provide this it will be
179     skipped.
180
181   needs-recommends
182
183     Enable installation of recommended packages in apt for the test
184     dependencies. This does not affect build dependencies.
185
186 Defined features
187 ----------------
188 There are no currently defined Features.
189
190
191 Source package header
192 ---------------------
193 To allow test execution environments to discover packages which provide
194 tests, their source packages should have a `Testsuite:` header
195 containing `autopkgtest` (which is currently the only defined value).
196 Multiple values get comma separated, as usual in control files.
197
198 This tag can be set manually in debian/control by adding
199
200     XS-Testsuite: autopkgtest
201
202 in the `Source:' paragraph. Future versions of dpkg-source might add this
203 automatically when a debian/tests/control file is present.