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.
28 .SH PROCESSING INSTRUCTIONS
30 .BR --tests-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 --binary " " \fIdeb\fR
47 Specifies that \fIdeb\fR should be used. By default it will be used
48 to satisfy dependencies, both during building and testing, but not
49 necessarily installed. The ordering is significant, as for
53 Bare filename arguments are processed as if
54 .BR --tests-tree ", " --source " or " --binary
55 was specified; the nature of the argument is guessed from the form of
56 the filename. (So in the case of \fB--tests-tree\fR, either the
57 option must be specified, or the filename must end in a slash.)
58 .SH PROCESSING OPTIONS
59 These affect modify processing instructions. Unless stated
60 otherwise, they affect all subsequent options.
62 .BR --paths-testbed | --paths-host
63 Specifies that subsequent pathnames in command-line arguments refer to
64 files on the testbed, or on the host, respectively. The default is
67 .BR --sources-tests | --sources-no-tests
68 Specifies that the tests in subsequent \fB--source\fR arguments should
69 (or should not) be run.
71 .BR --built-binaries-filter= \fIpattern\fB,\fIpattern\fB,\fR...
72 Specifies that only binaries whose package names match one of the
73 specified patterns should be used; others will be ignored. This
74 option applies to subsequent \fB--source\fR arguments.
76 .BR --no-built-binaries
77 Specifies that all built binaries should be ignored completely;
79 .BR --built-binaries-filter=_
80 (since no package name ever contains \fB_\fR).
82 .B --binaries=ignore | --binaries=auto | --binaries=install
83 Specifies that binary package (in subsequently specified
84 \fB--binary\fR arguments, or resulting from subsequently specified
85 \fB--source\fR arguments and not filtered out) should be ignored, used
86 only to satisfy dependencies, or installed unconditionally,
87 respectively. Equivalent to specifying both
88 .BR --binaries-forbuilds " and " --binaries-fortests .
90 .BI --binaries-forbuilds= ...
91 Like \fB--binaries=\fR but only changes the handling during package
92 building: packages will be ignored, used for dependencies, or
93 unconditionally installed, when a source package is built.
95 .BI --binaries-fortests= ...
96 Like \fB--binaries=\fR but only changes the handling during testing:
97 packages will be ignored, used for dependencies (including as the
98 package under test), or unconditionally installed, when tests are run
99 (as a result of either \fB--source\fR or \fB--build-tree\fR).
102 .BI --output-dir " " \fIoutput-dir\fR
103 Specifies that stderr and stdout from the tests should be placed in
105 The files were previously named
112 .BR log-buildt " (for the build logs from " --build-source ),
114 .RI "(for the build logs from the " i th
115 .BR --install-from-source ),
117 .RI "(for the installation logs from the " j "th installation or removal)".
118 Names have probably changed since this manual was written.
121 Run builds and tests as \fIuser\fR on the testbed. This needs root on
122 the testbed; if root on the testbed is not available then builds and
123 tests run as whatever user is provided.
125 .BI --gain-root= gain-root
127 .B debian/rules binary
129 .RB gain-root . The default is not to use anything, except that if
130 \fB--user\fR is supplied or root on the testbed is not available the
131 default is \fBfakeroot\fR.
133 .BI --tmp-dir= tmpdir
134 Specifies that \fItmpdir\fR should be used instead of a fresh
135 temporary directory on the host. \fItmpdir\fR will be created if
136 necessary, and emptied of all of its contents before \fBadt-run\fR
137 starts, and it will not be cleaned out afterwards. \fItmpdir\fR is
138 not affected by \fB--paths-testbed\fR.
140 again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
142 .BI --gnupg-home= dir
143 Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
144 The specified directory should not contain keyrings containing other
145 unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
146 which keys to use. The default is
147 .BR $HOME/.autopkgtest .
148 \fB--paths-testbed\fR has no effect on this option.
150 .B --gnupg-home=fresh
151 Use a fresh temporary directory and generate fresh keys each run.
152 This can be very slow and depends on the availability of sufficient
153 quantities of high-quality entropy.
156 Do not send a copy of \fBadt-run\fR's trace logstream to stderr;
157 instead, store it in the \fItmpdir\fR if one was specified, or discard
158 it otherwise. Note that without the trace logstream it can be very
159 hard to diagnose problems.
161 \fB---\fR \fIvirt-server virt-server-arg\fR...
162 Specifies the virtualisation regime server, as a command and arguments
163 to invoke. All the remaining arguments and options after
165 are passed to the virtualisation server program.
168 During a normal test run, one line is printed for each test. This
169 consists of a short string identifying the test, some horizontal
170 whitespace, and either
176 where the pass/fail indication is separated by any reason by some
177 horizontal whitespace.
179 The string to identify the test consists of a short alphanumeric
180 string invented by \fBadt-run\fR to distinguish different command-line
181 arguments, followed by a hyphen and the test name.
185 will be reported when the name of the test is not known or not
186 applicable: for example, when there are no tests in the package, or a
187 there is a test stanza which contains features not understood by this
192 will appear where the name of the test should be.
196 may be produced, where the right hand side is
198 (representing a pathname found in a command line argument),
200 (a source package name),
202 (a binary package name)
203 or possibly other strings to be determined. In case of an erroneous
204 package (see \fBEXIT STATUS\fR) this indicates which arguments and/or
205 packages might have contributed to the problem; the ones which were
206 processed most recently and which are therefore most likely to be the
207 cause of a problem are listed last.
212 2 at least one test skipped
214 4 at least one test failed
216 6 at least one test failed and at least one test skipped
218 8 no tests in this package
224 20 other unexpected failures including bad usage
227 \fBadt-virt-chroot\fR(1)
230 This tool still lacks many important features.
232 .SH AUTHORS AND COPYRIGHT
233 This manpage is part of autopkgtest, a tool for testing Debian binary
234 packages. autopkgtest is Copyright (C) 2006 Canonical Ltd and others.
236 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
237 contributors and full copying conditions.