runner/adt-run.1

   1 .TH adt\-run 1 2007 autopkgtest "Linux Programmer's Manual"
   2 .SH NAME
   3 adt\-run \- test an installed binary package using the package's tests
   4 .SH SYNOPSYS
   5 .B adt\-run
   6 .IR options ...
   7 .B \-\-\-
   8 .I virt\-server
   9 .RI [ virt\-server\-arg ...]
  10 .br
  11 .SH DESCRIPTION
  12 .B adt\-run
  13 is the program for invoking the autopkgtest package testing machinery.
  14
  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
  17 the source package.
  18
  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.
  23
  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.
  27
  28 .SH PROCESSING INSTRUCTIONS
  29 .TP
  30 .BR --built-tree " " \fIdirectory\fR
  31 Specifies that tests from the built source tree
  32 .IR directory
  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.
  38 .TP
  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
  44 binaries it produces.
  45 .TP
  46 .BR --unbuilt-tree " " \fIdirectory\fR
  47 Specifies that tests from the unbuilt source tree
  48 .IR directory
  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.
  52 .TP
  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
  57 \fB--source\fR.
  58 .TP
  59 .I filename
  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.
  69 .TP
  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
  73 \fB--paths-host\fR.
  74 .TP
  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.
  78 .TP
  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.
  83 .TP
  84 .BR --no-built-binaries
  85 Specifies that all built binaries should be ignored completely;
  86 equivalent to
  87 .BR --built-binaries-filter=_
  88 (since no package name ever contains \fB_\fR).
  89 .TP
  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 .
  97 .TP
  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.
 102 .TP
 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).
 108 .SH OTHER OPTIONS
 109 .TP
 110 .BI --output-dir " " \fIoutput-dir\fR
 111 Specifies that stderr and stdout from the tests should be placed in
 112 .IR output-dir .
 113 These files are named
 114 .BI argid- test -stderr
 115 and
 116 .BI argid- test -stdout
 117 for each test
 118 .IR test ,
 119 and
 120 .BR log
 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 \fItmp\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.
 128 .TP
 129 .BI --user= user
 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.
 133 .TP
 134 .BI --gain-root= gain-root
 135 Prefixes
 136 .B debian/rules binary
 137 with
 138 .RB gain-root .
 139 The default is not to use anything, except that if
 140 \fB--user\fR is supplied or root on the testbed is not available the
 141 default is \fBfakeroot\fR.
 142 .TP
 143 .BI --tmp-dir= tmp
 144 Specifies that \fItmp\fR should be used instead of a fresh
 145 temporary directory on the host.  \fItmp\fR will be created if
 146 necessary, and emptied of all of its contents before \fBadt-run\fR
 147 starts, and it will not be cleaned out afterwards.  \fItmp\fR is
 148 not affected by \fB--paths-testbed\fR.
 149 .B NOTE
 150 again that all of the contents of \fItmp\fR will be \fBdeleted\fR.
 151 .TP
 152 .BI --log-file= logfile
 153 Specifies that the trace log should be written to \fIlogfile\fR
 154 instead of to \fBlog\fR in \fIoutput-dir\fR or \fItmp\fR.
 155 \fIlog-file\fR is not affected by \fB--paths-testbed\fR.
 156 .TP
 157 .BI --summary= summary
 158 Specifies that a summary of the outcome should be written to
 159 \fIsummary\fR.  The events in the summary are written to the log
 160 in any case.
 161 \fIsummary\fR is not affected by \fB--paths-testbed\fR.
 162 .TP
 163 .BR --timeout- \fIwhich\fR = \fIseconds\fR
 164 Use a different timeout for operations on or with the testbed.  There
 165 are four timeouts affected by four values of \fIwhich\fR:
 166 .BR short :
 167 supposedly
 168 short operations like setting up the testbed's apt and checking the
 169 state (default: 100s);
 170 .BR install :
 171 installation of packages including dependencies
 172 (default: 3ks);
 173 .BR test :
 174 test runs (default: 10ks); and
 175 .BR build :
 176 builds (default:
 177 100ks).  The value must be specified as an integer number of seconds.
 178 .TP
 179 .BR --timeout-factor =\fIdouble\fR
 180 Multiply all of the default timeouts by the specified factor (see
 181 \fB--timeout-\fR\fIwhich\fR above).  Only the defaults are affected;
 182 explicit timeout settings are used exactly as specified.
 183 .TP
 184 .BR --debug | -d
 185 Include additional debugging information in the trace log.  Each
 186 additional \fB-d\fR increases the debugging level; the current maximum
 187 is \fB-ddd\fR.  If you like to see what's going on, \fR-d\fB or
 188 \fR-dd\fB is recommended.
 189 .TP
 190 .BI --gnupg-home= dir
 191 Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
 192 The specified directory should not contain keyrings containing other
 193 unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
 194 which keys to use.  The default is
 195 .BR $HOME/.autopkgtest .
 196 \fB--paths-testbed\fR has no effect on this option.
 197 .TP
 198 .B --gnupg-home=fresh
 199 Use a fresh temporary directory and generate fresh keys each run.
 200 This can be very slow and depends on the availability of sufficient
 201 quantities of high-quality entropy.
 202 .TP
 203 .BR -q " | " --quiet
 204 Do not send a copy of \fBadt-run\fR's trace logstream to stderr.  This
 205 option does not affect the copy sent to \fIlogfile\fR,
 206 \fIoutput-dir\fR or \fItmp\fR.  Note that without the trace
 207 logstream it can be very hard to diagnose problems.
 208 .TP
 209 \fB---\fR \fIvirt-server virt-server-arg\fR...
 210 Specifies the virtualisation regime server, as a command and arguments
 211 to invoke.  All the remaining arguments and options after
 212 .B ---
 213 are passed to the virtualisation server program.
 214 .TP
 215 .BI --set-lang= langval
 216 When running commands on the testbed, sets the \fBLANG\fR environment
 217 variable to \fIlangval\fR.  The default in \fBadt-run\fR is to set it
 218 to \fBC\fR.
 219 .TP
 220 .BI --leave-lang
 221 Suppresses the setting by \fBadt-run\fR of \fBLANG\fR on the testbed.
 222 This results in tests and builds using the testbed's own normal
 223 \fBLANG\fR value setting.
 224
 225 .SH OUTPUT FORMAT
 226 During a normal test run, one line is printed for each test.  This
 227 consists of a short string identifying the test, some horizontal
 228 whitespace, and either
 229 .B PASS
 230 or
 231 .BR FAIL " reason"
 232 or
 233 .BR SKIP " reason"
 234 where the pass/fail indication is separated by any reason by some
 235 horizontal whitespace.
 236
 237 The string to identify the test consists of a short alphanumeric
 238 string invented by \fBadt-run\fR to distinguish different command-line
 239 arguments, the \fIargid\fR, followed by a hyphen and the test name.
 240
 241 Sometimes a
 242 .B SKIP
 243 will be reported when the name of the test is not known or not
 244 applicable: for example, when there are no tests in the package, or a
 245 there is a test stanza which contains features not understood by this
 246 version of
 247 .BR adt-run .
 248 In this case
 249 .B *
 250 will appear where the name of the test should be.
 251
 252 If \fBadt-run\fR detects that erroneous package(s) are involved, it
 253 will print the two lines
 254 .BR "blame: " \fIblamed-thing\fR ...
 255 and
 256 .BR "badpkg: " \fImessage\fR.
 257 Here each whitespace-separated \fIblamed-thing\fR is one of
 258 .BI arg: argument
 259 (representing a pathname found in a command line argument),
 260 .BI dsc: package
 261 (a source package name),
 262 .BI deb: package
 263 (a binary package name)
 264 or possibly other strings to be determined.  This indicates which
 265 arguments and/or packages might have contributed to the problem; the
 266 ones which were processed most recently and which are therefore most
 267 likely to be the cause of a problem are listed last.
 268
 269 .SH EXIT STATUS
 270 0       all tests passed
 271 .br
 272 1       unexpected failure (the python interpreter invents this exit status)
 273 .br
 274 2       at least one test skipped
 275 .br
 276 4       at least one test failed
 277 .br
 278 6       at least one test failed and at least one test skipped
 279 .br
 280 8       no tests in this package
 281 .br
 282 12      erroneous package
 283 .br
 284 16      testbed failure
 285 .br
 286 20      other unexpected failures including bad usage
 287
 288 .SH SEE ALSO
 289 \fBadt-virt-chroot\fR(1), \fBadt-virt-xenlvm\fR(1)
 290
 291 .SH BUGS
 292 This tool still lacks some important features and is not very
 293 well-tested.
 294
 295 .SH AUTHORS AND COPYRIGHT
 296 This manpage is part of autopkgtest, a tool for testing Debian binary
 297 packages.  autopkgtest is Copyright (C) 2006-2007 Canonical Ltd and
 298 others.
 299
 300 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 301 contributors and full copying conditions.