1 .TH adt\-run 1 2007 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.
28 .SH PROCESSING INSTRUCTIONS
30 .BR --built-tree " " \fIdirectory\fR
31 Specifies that tests from the built source tree
33 should be run. Note that the packages that would normally be
34 installed as a result of \fB*\fR in the tests' \fBDepends\fR field
35 (which includes the case where the \fBDepends\fR field is not
36 specified) are \fInot\fR installed. The caller must explicitly
37 instruct \fBadt-run\fR to install any relevant packages.
39 .BR --source " " \fIdsc\fR
40 Builds \fIdsc\fR. The resulting binaries will (by default) be used to
41 satisfy dependencies. The tests from that built tree will also be run
42 (by default). The ordering is significant: each \fB--source\fR option
43 should precede options whose dependencies are to be satisfied by the
46 .BR --unbuilt-tree " " \fIdirectory\fR
47 Specifies that tests from the unbuilt source tree
49 should be run. This is very similar to specifing \fB--source\fR
50 except that a directory tree (which should be pristine) is supplied,
51 instead of a source package.
53 .BR --binary " " \fIdeb\fR
54 Specifies that \fIdeb\fR should be used. By default it will be used
55 to satisfy dependencies, both during building and testing, but not
56 necessarily installed. The ordering is significant, as for
60 Bare filename arguments are processed as if
61 .BR --built-tree ", " --source ", " --unbuilt-tree " or " --binary
62 was specified; the nature of the argument is guessed from the form of
63 the filename. In the case of \fB--built-tree\fR, either the
64 option must be specified, or the filename must end in a slash; two
65 slashes at the end are taken to mean \fB--unbuilt-tree\fR.
66 .SH PROCESSING OPTIONS
67 These affect modify processing instructions. Unless stated
68 otherwise, they affect all subsequent options.
70 .BR --paths-testbed | --paths-host
71 Specifies that subsequent pathnames in command-line arguments refer to
72 files on the testbed, or on the host, respectively. The default is
75 .BR --sources-tests | --sources-no-tests
76 Specifies that the tests in subsequent \fB--source\fR and
77 \fB--unbuilt-tree\fR arguments should (or should not) be run.
79 .BR --built-binaries-filter= \fIpattern\fB,\fIpattern\fB,\fR...
80 Specifies that only binaries whose package names match one of the
81 specified patterns should be used; others will be ignored. This
82 option applies to subsequent \fB--source\fR and \fB--unbuilt-tree\fR arguments.
84 .BR --no-built-binaries
85 Specifies that all built binaries should be ignored completely;
87 .BR --built-binaries-filter=_
88 (since no package name ever contains \fB_\fR).
90 .B --binaries=ignore | --binaries=auto | --binaries=install
91 Specifies that binary package (in subsequently specified
92 \fB--binary\fR arguments, or resulting from subsequently specified
93 \fB--source\fR or \fB--unbuilt-tree\fR arguments and not filtered out) should be ignored, used
94 only to satisfy dependencies, or installed unconditionally,
95 respectively. Equivalent to specifying both
96 .BR --binaries-forbuilds " and " --binaries-fortests .
98 .BI --binaries-forbuilds= ...
99 Like \fB--binaries=\fR but only changes the handling during package
100 building: packages will be ignored, used for dependencies, or
101 unconditionally installed, when a source package is built.
103 .BI --binaries-fortests= ...
104 Like \fB--binaries=\fR but only changes the handling during testing:
105 packages will be ignored, used for dependencies (including as the
106 package under test), or unconditionally installed, when tests are run
107 (as a result of \fB--source\fR, \fB--built-tree\fR or \fB--unbuilt-tree\fR).
110 .BI --output-dir " " \fIoutput-dir\fR
111 Specifies that stderr and stdout from the tests should be placed in
113 These files are named
114 .BI argid- test -stderr
116 .BI argid- test -stdout
121 for the log transcript. If no \fIoutput-dir\fR is specified, or the
122 path is specified to be on the testbed (ie, if \fB--output-dir\fR
123 follows \fB--paths-testbed\fR), then the \fBlog\fR file is instead
124 written to the temporary directory \fItmpdir\fR if one was specified,
125 or otherwise no separate copy is made. Note that the log transcript
126 output will also be sent to \fBadt-run\fR's stderr unless
127 \fB--quiet\fR is specified.
130 Run builds and tests as \fIuser\fR on the testbed. This needs root on
131 the testbed; if root on the testbed is not available then builds and
132 tests run as whatever user is provided.
134 .BI --gain-root= gain-root
136 .B debian/rules binary
138 .RB gain-root . The default is not to use anything, except that if
139 \fB--user\fR is supplied or root on the testbed is not available the
140 default is \fBfakeroot\fR.
142 .BI --tmp-dir= tmpdir
143 Specifies that \fItmpdir\fR should be used instead of a fresh
144 temporary directory on the host. \fItmpdir\fR will be created if
145 necessary, and emptied of all of its contents before \fBadt-run\fR
146 starts, and it will not be cleaned out afterwards. \fItmpdir\fR is
147 not affected by \fB--paths-testbed\fR.
149 again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
151 .BI --log-file= logfile
152 Specifies that the trace log should be written to \fIlogfile\fR
153 instead of to \fBlog\fR in \fIoutput-dir\fR or \fItmpdir\fR.
154 \fIlog-file\fR is not affected by \fB--paths-testbed\fR.
157 Include additional debugging information in the trace log. Each
158 additional \fB-d\fR increases the debugging level; the current maximum
159 is \fB-ddd\fR. If you like to see what's going on, \fR-d\fB or
160 \fR-dd\fB is recommended.
162 .BI --gnupg-home= dir
163 Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
164 The specified directory should not contain keyrings containing other
165 unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
166 which keys to use. The default is
167 .BR $HOME/.autopkgtest .
168 \fB--paths-testbed\fR has no effect on this option.
170 .B --gnupg-home=fresh
171 Use a fresh temporary directory and generate fresh keys each run.
172 This can be very slow and depends on the availability of sufficient
173 quantities of high-quality entropy.
176 Do not send a copy of \fBadt-run\fR's trace logstream to stderr. This
177 option does not affect the copy sent to \fIlogfile\fR,
178 \fIoutput-dir\fR or \fItmpdir\fR. Note that without the trace
179 logstream it can be very hard to diagnose problems.
181 \fB---\fR \fIvirt-server virt-server-arg\fR...
182 Specifies the virtualisation regime server, as a command and arguments
183 to invoke. All the remaining arguments and options after
185 are passed to the virtualisation server program.
188 During a normal test run, one line is printed for each test. This
189 consists of a short string identifying the test, some horizontal
190 whitespace, and either
196 where the pass/fail indication is separated by any reason by some
197 horizontal whitespace.
199 The string to identify the test consists of a short alphanumeric
200 string invented by \fBadt-run\fR to distinguish different command-line
201 arguments, the \fIargid\fR, followed by a hyphen and the test name.
205 will be reported when the name of the test is not known or not
206 applicable: for example, when there are no tests in the package, or a
207 there is a test stanza which contains features not understood by this
212 will appear where the name of the test should be.
214 If \fBadt-run\fR detects that erroneous package(s) are involved, it
215 will print the two lines
216 .BR "blame: " \fIblamed-thing\fR ...
218 .BR "badpkg: " \fImessage\fR.
219 Here each whitespace-separated \fIblamed-thing\fR is one of
221 (representing a pathname found in a command line argument),
223 (a source package name),
225 (a binary package name)
226 or possibly other strings to be determined. This indicates which
227 arguments and/or packages might have contributed to the problem; the
228 ones which were processed most recently and which are therefore most
229 likely to be the cause of a problem are listed last.
234 1 unexpected failure (the python interpreter invents this exit status)
236 2 at least one test skipped
238 4 at least one test failed
240 6 at least one test failed and at least one test skipped
242 8 no tests in this package
248 20 other unexpected failures including bad usage
251 \fBadt-virt-chroot\fR(1), \fBadt-virt-xenlvm\fR(1)
254 This tool still lacks some important features and is not very
257 .SH AUTHORS AND COPYRIGHT
258 This manpage is part of autopkgtest, a tool for testing Debian binary
259 packages. autopkgtest is Copyright (C) 2006-1007 Canonical Ltd and
262 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
263 contributors and full copying conditions.