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 --tests-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 --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
  50 \fB--source\fR.
  51 .TP
  52 .I filename
  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.
  61 .TP
  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
  65 \fB--paths-host\fR.
  66 .TP
  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.
  70 .TP
  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.
  75 .TP
  76 .BR --no-built-binaries
  77 Specifies that all built binaries should be ignored completely;
  78 equivalent to
  79 .BR --built-binaries-filter=_
  80 (since no package name ever contains \fB_\fR).
  81 .TP
  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 .
  89 .TP
  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.
  94 .TP
  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).
 100 .SH OTHER OPTIONS
 101 .TP
 102 .BI --output-dir " " \fIoutput-dir\fR
 103 Specifies that stderr and stdout from the tests should be placed in
 104 .IR output-dir .
 105 These files are named
 106 .BI argid- test -stderr
 107 and
 108 .BI argid- test -stdout
 109 for each test
 110 .IR test ,
 111 and
 112 .BR log
 113 for the log transcript.  If no \fIoutput-dir\fR is specified, or the
 114 path is specified to be on the testbed (ie, if \fB--output-dir\fR
 115 follows \fB--paths-testbed\fR), then the \fBlog\fR file is instead
 116 written to the temporary directory \fItmpdir\fR if one was specified,
 117 or otherwise no separate copy is made.  Note that the log transcript
 118 output will also be sent to \fBadt-run\fR's stderr unless
 119 \fB--quiet\fR is specified.
 120 .TP
 121 .BI --user= user
 122 Run builds and tests as \fIuser\fR on the testbed.  This needs root on
 123 the testbed; if root on the testbed is not available then builds and
 124 tests run as whatever user is provided.
 125 .TP
 126 .BI --gain-root= gain-root
 127 Prefixes
 128 .B debian/rules binary
 129 with
 130 .RB gain-root .  The default is not to use anything, except that if
 131 \fB--user\fR is supplied or root on the testbed is not available the
 132 default is \fBfakeroot\fR.
 133 .TP
 134 .BI --tmp-dir= tmpdir
 135 Specifies that \fItmpdir\fR should be used instead of a fresh
 136 temporary directory on the host.  \fItmpdir\fR will be created if
 137 necessary, and emptied of all of its contents before \fBadt-run\fR
 138 starts, and it will not be cleaned out afterwards.  \fItmpdir\fR is
 139 not affected by \fB--paths-testbed\fR.
 140 .B NOTE
 141 again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
 142 .TP
 143 .BI --log-file= logfile
 144 Specifies that the trace log should be written to \fIlogfile\fR
 145 instead of to \fBlog\fR in \fIoutput-dir\fR or \fItmpdir\fR.
 146 \fIlog-file\fR is not affected by \fB--paths-testbed\fR.
 147 .TP
 148 .BI --gnupg-home= dir
 149 Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
 150 The specified directory should not contain keyrings containing other
 151 unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
 152 which keys to use.  The default is
 153 .BR $HOME/.autopkgtest .
 154 \fB--paths-testbed\fR has no effect on this option.
 155 .TP
 156 .B --gnupg-home=fresh
 157 Use a fresh temporary directory and generate fresh keys each run.
 158 This can be very slow and depends on the availability of sufficient
 159 quantities of high-quality entropy.
 160 .TP
 161 .BR -q " | " --quiet
 162 Do not send a copy of \fBadt-run\fR's trace logstream to stderr.  This
 163 option does not affect the copy sent to \fIlogfile\fR,
 164 \fIoutput-dir\fR or \fItmpdir\fR.  Note that without the trace
 165 logstream it can be very hard to diagnose problems.
 166 .TP
 167 \fB---\fR \fIvirt-server virt-server-arg\fR...
 168 Specifies the virtualisation regime server, as a command and arguments
 169 to invoke.  All the remaining arguments and options after
 170 .B ---
 171 are passed to the virtualisation server program.
 172
 173 .SH OUTPUT FORMAT
 174 During a normal test run, one line is printed for each test.  This
 175 consists of a short string identifying the test, some horizontal
 176 whitespace, and either
 177 .B PASS
 178 or
 179 .BR FAIL " reason"
 180 or
 181 .BR SKIP " reason"
 182 where the pass/fail indication is separated by any reason by some
 183 horizontal whitespace.
 184
 185 The string to identify the test consists of a short alphanumeric
 186 string invented by \fBadt-run\fR to distinguish different command-line
 187 arguments, the \fIargid\fR, followed by a hyphen and the test name.
 188
 189 Sometimes a
 190 .B SKIP
 191 will be reported when the name of the test is not known or not
 192 applicable: for example, when there are no tests in the package, or a
 193 there is a test stanza which contains features not understood by this
 194 version of
 195 .BR adt-run .
 196 In this case
 197 .B *
 198 will appear where the name of the test should be.
 199
 200 If \fBadt-run\fR detects that erroneous package(s) are involved, it
 201 will print the two lines
 202 .BR "blame: " \fIblamed-thing\fR ...
 203 and
 204 .BR "badpkg: " \fImessage\fR.
 205 Here each whitespace-separated \fIblamed-thing\fR is one of
 206 .BI arg: argument
 207 (representing a pathname found in a command line argument),
 208 .BI dsc: package
 209 (a source package name),
 210 .BI deb: package
 211 (a binary package name)
 212 or possibly other strings to be determined.  This indicates which
 213 arguments and/or packages might have contributed to the problem; the
 214 ones which were processed most recently and which are therefore most
 215 likely to be the cause of a problem are listed last.
 216
 217 .SH EXIT STATUS
 218 0       all tests passed
 219 .br
 220 1       unexpected failure (the python interpreter invents this exit status)
 221 .br
 222 2       at least one test skipped
 223 .br
 224 4       at least one test failed
 225 .br
 226 6       at least one test failed and at least one test skipped
 227 .br
 228 8       no tests in this package
 229 .br
 230 12      erroneous package
 231 .br
 232 16      testbed failure
 233 .br
 234 20      other unexpected failures including bad usage
 235
 236 .SH SEE ALSO
 237 \fBadt-virt-chroot\fR(1), \fBadt-virt-xenlvm\fR(1)
 238
 239 .SH BUGS
 240 This tool still lacks some important features and is not very
 241 well-tested.
 242
 243 .SH AUTHORS AND COPYRIGHT
 244 This manpage is part of autopkgtest, a tool for testing Debian binary
 245 packages.  autopkgtest is Copyright (C) 2006-1007 Canonical Ltd and
 246 others.
 247
 248 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 249 contributors and full copying conditions.