1 .TH adt\-run 1 2006 autopkgtest "Linux Programmer's Manual"
3 adt\-run \- test an installed binary package using the package's tests
9 .RI [ virt\-server\-arg ...]
13 is the program for invoking the autopkgtest package testing machinery.
15 autopkgtest is a facility for testing binary packages, as installed on
16 a system (such as a testbed system). The tests are those supplied in
19 adt\-run runs each test supplied by a particular package and reports
20 the results. It drives the specified virtualisation regime as
21 appropriate, and parses the test description metadata, and arranges
22 for data to be copied to and from the testbed as required.
24 adt\-run should be invoked (unless options to the contrary are
25 supplied) in the top level directory of the built source tree, on the
26 host. The package should be installed on the testbed.
30 .BR --tests-tree [ -tb ] " " \fIdirectory\fR
31 Specifies that the built source tree can be found in
33 (Default: adt-run's current directory, on the host.)
35 .BR --source [ -tb ] " " \fIdsc\fR
36 Builds \fIdsc\fR, and then uses the tests in that tree, as well as
37 testing the packages from this build and using them to satisfy
38 dependencies. Equivalent to \fB--source-tests\fI and
39 \fB--source-binaries\fI (except that it only does the build once).
41 .BR --source-tests [ -tb ] " " \fIdsc\fR
42 Builds \fIdsc\fR (installing dependencies as appropriate), and then
43 uses the tests in that tree. The packages tested will be those
44 installed on the testbed, not the ones from this build.
46 .BR --source-testsinstall [ -tb ] " " \fIdsc\fR
47 Builds \fIdsc\fR (installing dependencies as appropriate), and then
48 installs the packages which result (subject to
49 \fB--package-filter-source-install\fR). The packages tested will be
50 those installed on the testbed, not the ones from this build. This is
51 like \fB--source-tests\fR except that the packages from the build are
52 installed even if they are not required as a dependency for any test.
54 .BR --source-binaries [ -tb ] " " \fIdsc\fR
55 Builds \fIdsc\fR (installing dependencies as appropriate), and then
56 use the resulting binary packages to satisfy dependencies (instead of
57 packages from the default archive).
60 Only dependencies mentioned by
61 tests, or binary packages built by or provided directly to
62 \fBadt-run\fR, are affected: dependencies mentioned by binary packages
65 The dependencies affected are
68 which are themselves installed deliberately by the test
70 installed implicitly by
73 direct \Test-Depends lines,
75 installs the packages which result (subject to
76 \fB--package-filter-source-install\fR). The packages tested will be
77 those installed on the testbed, not the ones from this build.
82 Equivalent to \fB--source-tests\fR but
84 ; also uses the tests in the
89 uses the tests in that tree. The packages tested will be those
90 installed on the testbed, not the ones from this build.
96 testing the packages from this build and using them to satisfy
97 dependencies. Equivalent to \fB--source-tests\fI and
98 \fB--source-binaries\fI (except that it only does the build once).
102 Specifies that the source to use for the tests can be found in
104 (which should be a \fB.dsc\fR). The source will be unpacked
105 and built, and the tests from this build tree will be run.
107 .BR --use-source [ -tb ] " " \fIfilename\fR
108 Specifies that the source to use for the tests can be found in
110 (which should be a \fB.dsc\fR), and that the packages from this
111 build should be the ones tested, and used to satisfy any dependencies;
112 this option is like \fB--build-source\fR and \fB--from-source\fR combined.
114 .BR --user " " \fIusername\fR
115 Specifies that commands on the testbed should generally be run as
116 \fIusername\fR; this option does not make much sense unless the
117 virtualisation environment provides root on the testbed. Commands are
118 run via \fBsu -c\fR; affected commands are tests (other than those
119 which declare that they need root), source package builds and source
120 package binary generation (via fakeroot). If the testbed advertises
121 the \fBroot-on-testbed\fR and \fBsuggest-normal-user=\fR capabilities,
122 the suggested normal is used as the default; otherwise the default is
123 to run commands as the testbed's default user (this can be explicitly
124 requested by specifying the empty string for \fIusername\fR).
126 .BR --fakeroot " " \fIfakeroot-command\fR
127 Specifies that \fBdebian/rules binary\fR should be run via
128 \fIfakeroot-command\fR. The default is \fBfakeroot\fR if the testbed
129 doesn't offer us root or if we are running \fBdebian/rules build\fR as
130 a normal user according to a specified or default value of
131 \fB--user\fR, and no wrapper otherwise.
133 The default is to run without any special
136 Specifies that commands on the testbed should generally be run as
137 \fIusername\fR; this option does not make much sense unless the
138 virtualisation environment provides root on the testbed. Commands
139 are run via \fBsu -c\fR; affected commands are tests (other than those
140 which declare that they need root), source package builds and source
141 package binary generation (except if \fB--fakeroot\fR is specified -
144 Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
145 unconditionally installed on the testbed before any tests are run (but
146 after any necessary building). This can be used to test a specific
149 .BR --install-binary [ -tb ] " " \fIfilename\fR
150 Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
151 unconditionally installed on the testbed before any tests are run (but
152 after any necessary building). This can be used to test a specific
155 .BR --from-source [ -tb ] " " \fIsource\fR
156 Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
157 built on the testbed and then the resulting \fB.deb\fR's
158 used to satisfy dependencies where necessary.
160 .BR --install-from-source [ -tb ] " " \fIsource\fR
161 Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
162 built on the testbed and then (some subset of) the \fB.deb\fR's which
163 result should be installed.
165 ;.BR --without-depends | --with-depends-only | --with-depends | --with-recommends
166 ;Specifies dependency handling: These options control whether
167 ;dependencies necessary for building and installing the packages as
168 ;requested will be installed (and possibly deinstalled, if there are
171 ;Each option controls installation of the dependencies for
173 ;.BR --build-source ", " --install-package " and " --install-from-source
174 ;options, until the next dependency handling option; the last
175 ;dependency handling option controls whether dependencies specified in
176 ;the actual test control file are installed.
178 ;The four handling modes are to honour, respectively: no dependencies, only
179 ;\fBDepends\fR, everything except \fBRecommends\fR and \fBSuggests\fR,
180 ;and everything except \fBSuggests\fR.
181 ;The default is \fB--without-depends\fR (it is as if this was
182 ;specified at the start of the command line).
184 ;.BR --package-filter-dependency " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
185 ;Limits the packages installed (or removed) due to dependencies to
186 ;those matching the specified filter. The filter is a comma-separated
187 ;list of glob patterns (which must match the whole package name); each
188 ;optionally preceded by \fB!\fR (which indicates that matching packages
189 ;should not be installed). The first pattern found determines; if no
190 ;pattern matches, then the package is taken to match the filter iff the
191 ;last pattern had a \fB!\fR.
193 .BR --package-filter-from-source " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
194 Limits the packages installed directly due to
195 .B --install-from-source
196 directives; the patterns are interpreted as for
197 .BR --package-filter-dependency .
199 .BR --control [ -tb ] " " \fIcontrol\fR
202 should be used as the test control file instead of
203 .B debian/tests/control
204 in the build tree. Note that it is not an error for this file not to
205 exist; that just means that there are no tests.
207 .BR --output-dir [ -tb ] " " \fIoutput-dir\fR
208 Specifies that stderr and stdout from the tests should be placed in
217 .BR log-buildt " (for the build logs from " --build-source ),
219 .RI "(for the build logs from the " i th
220 .BR --install-from-source ),
222 .RI "(for the installation logs from the " j "th installation or removal)".
225 Enables debugging output. Probably not hugely interesting.
227 \fB---\fR \fIvirt-server virt-server-arg\fR...
228 Specifies the virtualisation regime server, as a command and arguments
229 to invoke. All the remaining arguments and options after
231 are passed to the virtualisation server program.
234 Some options which come in variants with and without
236 These specify paths on the testbed and the host, respectively. The
237 data will be copied by
239 to where it is needed.
242 During a normal test run, one line is printed for each test. This
243 consists of the name of the test, some horizontal whitespace, and
250 where the pass/fail indication is separated by any reason by some
251 horizontal whitespace.
255 will be reported when the name of the test is not known or not
256 applicable: for example, when there are no tests in the package, or a
257 there is a test stanza which contains features not understood by this
262 will appear where the name of the test should be.
267 2 at least one test skipped
269 4 at least one test failed
271 6 at least one test failed and at least one test skipped
273 8 no tests in this package
279 20 other unexpected failures including bad usage
282 \fBadt-virt-chroot\fR(1)
285 This tool still lacks many important features.
287 .SH AUTHORS AND COPYRIGHT
288 This manpage is part of autopkgtest, a tool for testing Debian binary
289 packages. autopkgtest is Copyright (C) 2006 Canonical Ltd and others.
291 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
292 contributors and full copying conditions.