runner/adt-run.1

   1 .TH adt\-run 1 2006 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.
  34 .TP
  35 .BR --source " " \fIdsc\fR
  36 Builds \fIdsc\fR.  The resulting binaries will (by default) be used to
  37 satisfy dependencies.  The tests from that built tree will also be run
  38 (by default).  The ordering is significant: each \fB--source\fR option
  39 should precede options whose dependencies are to be satisfied by the
  40 binaries it produces.
  41 .TP
  42 .BR --binary " " \fIdeb\fR
  43 Specifies that \fIdeb\fR should be used.  By default it will be used
  44 to satisfy dependencies, both during building and testing, but not
  45 necessarily installed.  The ordering is significant, as for
  46 \fB--source\fR.
  47 .TP
  48 .I filename
  49 Bare filename arguments are processed as if
  50 .BR --tests-tree ", " --source " or " --binary
  51 was specified; the nature of the argument is guessed from the form of
  52 the filename.  (So in the case of \fB--tests-tree\fR, either the
  53 option must be specified, or the filename must end in a slash.)
  54 .SH PROCESSING OPTIONS
  55 These affect modify processing instructions.  Unless stated
  56 otherwise, they affect all subsequent options.
  57 .TP
  58 .BR --paths-testbed | --paths-host
  59 Specifies that subsequent pathnames in command-line arguments refer to
  60 files on the testbed, or on the host, respectively.  The default is
  61 \fB--paths-host\fR.
  62 .TP
  63 .BR --sources-tests | --sources-no-tests
  64 Specifies that the tests in subsequent \fB--source\fR arguments should
  65 (or should not) be run.
  66 .TP
  67 .BR --built-binaries-filter= \fIpattern\fB,\fIpattern\fB,\fR...
  68 Specifies that only binaries whose package names match one of the
  69 specified patterns should be used; others will be ignored.  This
  70 option applies to subsequent \fB--source\fR arguments.
  71 .TP
  72 .BR --no-built-binaries
  73 Specifies that all built binaries should be ignored completely;
  74 equivalent to
  75 .BR --built-binaries-filter=_
  76 (since no package name ever contains \fB_\fR).
  77 .TP
  78 .B --binaries=ignore | --binaries=auto | --binaries=install
  79 Specifies that binary package (in subsequently specified
  80 \fB--binary\fR arguments, or resulting from subsequently specified
  81 \fB--source\fR arguments and not filtered out) should be ignored, used
  82 only to satisfy dependencies, or installed unconditionally,
  83 respectively.  Equivalent to specifying both
  84 .BR --binaries-forbuilds " and " --binaries-fortests .
  85 .TP
  86 .BI --binaries-forbuilds= ...
  87 Like \fB--binaries=\fR but only changes the handling during package
  88 building: packages will be ignored, used for dependencies, or
  89 unconditionally installed, when a source package is built.
  90 .TP
  91 .BI --binaries-fortests= ...
  92 Like \fB--binaries=\fR but only changes the handling during testing:
  93 packages will be ignored, used for dependencies (including as the
  94 package under test), or unconditionally installed, when tests are run
  95 (as a result of either \fB--source\fR or \fB--build-tree\fR).
  96 .SH OTHER OPTIONS
  97 .TP
  98 .BI --output-dir " " \fIoutput-dir\fR
  99 Specifies that stderr and stdout from the tests should be placed in
 100 .IR output-dir .
 101 The files were previously named
 102 .BI stderr- test
 103 and
 104 .BI stdout- test
 105 for each test
 106 .IR test ,
 107 and
 108 .BR log-buildt " (for the build logs from " --build-source ),
 109 .BI log-buildi- i
 110 .RI "(for the build logs from the " i th
 111 .BR --install-from-source ),
 112 .BI log-install- j
 113 .RI "(for the installation logs from the " j "th installation or removal)".
 114 Names have probably changed since this manual was written.
 115 .TP
 116 .BI --user= user
 117 Run builds and tests as \fIuser\fR on the testbed.  This needs root on
 118 the testbed; if root on the testbed is not available then builds and
 119 tests run as whatever user is provided.
 120 .TP
 121 .BI --gain-root= gain-root
 122 Prefixes
 123 .B debian/rules binary
 124 with
 125 .RB gain-root .  The default is not to use anything, except that if
 126 \fB--user\fR is supplied or root on the testbed is not available the
 127 default is \fBfakeroot\fR.
 128 .TP
 129 .BI --tmp-dir= tmpdir
 130 Specifies that \fItmpdir\fR should be used instead of a fresh
 131 temporary directory on the host.  \fItmpdir\fR will be created if
 132 necessary, and emptied of all of its contents before \fBadt-run\fR
 133 starts, and it will not be cleaned out afterwards.  \fItmpdir\fR is
 134 not affected by \fB--paths-testbed\fR.
 135 .B NOTE
 136 again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
 137 .TP
 138 .BI --gnupg-home= dir
 139 Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
 140 The specified directory should not contain keyrings containing other
 141 unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
 142 which keys to use.  The default is
 143 .BR $HOME/.autopkgtest .
 144 \fB--paths-testbed\fR has no effect on this option.
 145 .TP
 146 .B --gnupg-home=fresh
 147 Use a fresh temporary directory and generate fresh keys each run.
 148 This can be very slow and depends on the availability of sufficient
 149 quantities of high-quality entropy.
 150 .TP
 151 .BR -d " | " --debug
 152 Enables debugging output.  Probably not hugely interesting.
 153 .TP
 154 \fB---\fR \fIvirt-server virt-server-arg\fR...
 155 Specifies the virtualisation regime server, as a command and arguments
 156 to invoke.  All the remaining arguments and options after
 157 .B ---
 158 are passed to the virtualisation server program.
 159
 160 .SH OUTPUT FORMAT
 161 During a normal test run, one line is printed for each test.  This
 162 consists of a short string identifying the test, some horizontal
 163 whitespace, and either
 164 .B PASS
 165 or
 166 .BR FAIL " reason"
 167 or
 168 .BR SKIP " reason"
 169 where the pass/fail indication is separated by any reason by some
 170 horizontal whitespace.
 171
 172 The string to identify the test consists of a short alphanumeric
 173 string invented by \fBadt-run\fR to distinguish different command-line
 174 arguments, followed by a hyphen and the test name.
 175
 176 Sometimes a
 177 .B SKIP
 178 will be reported when the name of the test is not known or not
 179 applicable: for example, when there are no tests in the package, or a
 180 there is a test stanza which contains features not understood by this
 181 version of
 182 .BR adt-run .
 183 In this case
 184 .B *
 185 will appear where the name of the test should be.
 186
 187 Also, the output:
 188 .BR blame:  ...
 189 may be produced, where the right hand side is
 190 .BI arg: argument
 191 (representing a pathname found in a command line argument),
 192 .BI dsc: package
 193 (a source package name),
 194 .BI deb: package
 195 (a binary package name)
 196 or possibly other strings to be determined.  In case of an erroneous
 197 package (see \fBEXIT STATUS\fR) this indicates which arguments and/or
 198 packages might have contributed to the problem; the ones which were
 199 processed most recently and which are therefore most likely to be the
 200 cause of a problem are listed last.
 201
 202 .SH EXIT STATUS
 203 0       all tests passed
 204 .br
 205 2       at least one test skipped
 206 .br
 207 4       at least one test failed
 208 .br
 209 6       at least one test failed and at least one test skipped
 210 .br
 211 8       no tests in this package
 212 .br
 213 12      erroneous package
 214 .br
 215 16      testbed failure
 216 .br
 217 20      other unexpected failures including bad usage
 218
 219 .SH SEE ALSO
 220 \fBadt-virt-chroot\fR(1)
 221
 222 .SH BUGS
 223 This tool still lacks many important features.
 224
 225 .SH AUTHORS AND COPYRIGHT
 226 This manpage is part of autopkgtest, a tool for testing Debian binary
 227 packages.  autopkgtest is Copyright (C) 2006 Canonical Ltd and others.
 228
 229 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 230 contributors and full copying conditions.