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 OPTIONS
  29 .TP
  30 .BR --tests-tree [ -tb ] " " \fIdirectory\fR
  31 Specifies that the built source tree can be found in
  32 .IR directory .
  33 (Default: adt-run's current directory, on the host.)
  34 .TP
  35 .BR --source [ -tb ] " " \fIdsc\fR
  36 Builds \fIdsc\fR, and then uses the tests in that tree, as well as
  37 testing the packages from this build and using them to satisfy
  38 dependencies.  Equivalent to \fB--source-tests\fI and
  39 \fB--source-binaries\fI (except that it only does the build once).
  40 .TP
  41 .BR --source-tests [ -tb ] " " \fIdsc\fR
  42 Builds \fIdsc\fR (installing dependencies as appropriate), and then
  43 uses the tests in that tree.  The packages tested will be those
  44 installed on the testbed, not the ones from this build.
  45 .TP
  46 .BR --source-testsinstall [ -tb ] " " \fIdsc\fR
  47 Builds \fIdsc\fR (installing dependencies as appropriate), and then
  48 installs the packages which result (subject to
  49 \fB--package-filter-source-install\fR).  The packages tested will be
  50 those installed on the testbed, not the ones from this build.  This is
  51 like \fB--source-tests\fR except that the packages from the build are
  52 installed even if they are not required as a dependency for any test.
  53 .TP
  54 .BR --source-binaries [ -tb ] " " \fIdsc\fR
  55 Builds \fIdsc\fR (installing dependencies as appropriate), and then
  56 use the resulting binary packages to satisfy dependencies (instead of
  57 packages from the default archive).
  58
  59
  60 Only dependencies mentioned by
  61 tests, or binary packages built by or provided directly to
  62 \fBadt-run\fR, are affected: dependencies mentioned by binary packages
  63 installed implicitly
  64
  65   The dependencies affected are
  66
  67
  68 which are themselves installed deliberately by the test
  69 .  Binary packages
  70 installed implicitly by
  71
  72
  73 direct \Test-Depends lines,
  74
  75 installs the packages which result (subject to
  76 \fB--package-filter-source-install\fR).  The packages tested will be
  77 those installed on the testbed, not the ones from this build.
  78
  79
  80
  81
  82 Equivalent to \fB--source-tests\fR but
  83
  84 ; also uses the tests in the
  85 resulting build tree.
  86
  87
  88 and then
  89 uses the tests in that tree.  The packages tested will be those
  90 installed on the testbed, not the ones from this build.
  91 .TP
  92
  93
  94
  95 , as well as
  96 testing the packages from this build and using them to satisfy
  97 dependencies.  Equivalent to \fB--source-tests\fI and
  98 \fB--source-binaries\fI (except that it only does the build once).
  99
 100
 101
 102 Specifies that the source to use for the tests can be found in
 103 .IR filename
 104 (which should be a \fB.dsc\fR).  The source will be unpacked
 105 and built, and the tests from this build tree will be run.
 106 .TP
 107 .BR --use-source [ -tb ] " " \fIfilename\fR
 108 Specifies that the source to use for the tests can be found in
 109 .IR filename
 110 (which should be a \fB.dsc\fR), and that the packages from this
 111 build should be the ones tested, and used to satisfy any dependencies;
 112 this option is like \fB--build-source\fR and \fB--from-source\fR combined.
 113 .TP
 114 .BR --user " " \fIusername\fR
 115 Specifies that commands on the testbed should generally be run as
 116 \fIusername\fR; this option does not make much sense unless the
 117 virtualisation environment provides root on the testbed.  Commands are
 118 run via \fBsu -c\fR; affected commands are tests (other than those
 119 which declare that they need root), source package builds and source
 120 package binary generation (via fakeroot).  If the testbed advertises
 121 the \fBroot-on-testbed\fR and \fBsuggest-normal-user=\fR capabilities,
 122 the suggested normal is used as the default; otherwise the default is
 123 to run commands as the testbed's default user (this can be explicitly
 124 requested by specifying the empty string for \fIusername\fR).
 125 .TP
 126 .BR --fakeroot " " \fIfakeroot-command\fR
 127 Specifies that \fBdebian/rules binary\fR should be run via
 128 \fIfakeroot-command\fR.  The default is \fBfakeroot\fR if the testbed
 129 doesn't offer us root or if we are running \fBdebian/rules build\fR as
 130 a normal user according to a specified or default value of
 131 \fB--user\fR, and no wrapper otherwise.
 132
 133 The default is to run without any special
 134 measures if the test
 135
 136 Specifies that commands on the testbed should generally be run as
 137 \fIusername\fR; this option does not make much sense unless the
 138 virtualisation environment provides root on the testbed.  Commands
 139 are run via \fBsu -c\fR; affected commands are tests (other than those
 140 which declare that they need root), source package builds and source
 141 package binary generation (except if \fB--fakeroot\fR is specified -
 142 see below).
 143
 144 Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
 145 unconditionally installed on the testbed before any tests are run (but
 146 after any necessary building).  This can be used to test a specific
 147 binary package.
 148 .TP
 149 .BR --install-binary [ -tb ] " " \fIfilename\fR
 150 Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
 151 unconditionally installed on the testbed before any tests are run (but
 152 after any necessary building).  This can be used to test a specific
 153 binary package.
 154 .TP
 155 .BR --from-source [ -tb ] " " \fIsource\fR
 156 Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
 157 built on the testbed and then the resulting \fB.deb\fR's
 158 used to satisfy dependencies where necessary.
 159 .TP
 160 .BR --install-from-source [ -tb ] " " \fIsource\fR
 161 Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
 162 built on the testbed and then (some subset of) the \fB.deb\fR's which
 163 result should be installed.
 164 ;.TP
 165 ;.BR --without-depends | --with-depends-only | --with-depends | --with-recommends
 166 ;Specifies dependency handling: These options control whether
 167 ;dependencies necessary for building and installing the packages as
 168 ;requested will be installed (and possibly deinstalled, if there are
 169 ;conflicts).
 170 ;.IP
 171 ;Each option controls installation of the dependencies for
 172 ;all subsequent
 173 ;.BR --build-source ", " --install-package " and " --install-from-source
 174 ;options, until the next dependency handling option; the last
 175 ;dependency handling option controls whether dependencies specified in
 176 ;the actual test control file are installed.
 177 ;.IP
 178 ;The four handling modes are to honour, respectively: no dependencies, only
 179 ;\fBDepends\fR, everything except \fBRecommends\fR and \fBSuggests\fR,
 180 ;and everything except \fBSuggests\fR.
 181 ;The default is \fB--without-depends\fR (it is as if this was
 182 ;specified at the start of the command line).
 183 ;.TP
 184 ;.BR --package-filter-dependency " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
 185 ;Limits the packages installed (or removed) due to dependencies to
 186 ;those matching the specified filter.  The filter is a comma-separated
 187 ;list of glob patterns (which must match the whole package name); each
 188 ;optionally preceded by \fB!\fR (which indicates that matching packages
 189 ;should not be installed).  The first pattern found determines; if no
 190 ;pattern matches, then the package is taken to match the filter iff the
 191 ;last pattern had a \fB!\fR.
 192 .TP
 193 .BR --package-filter-from-source " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
 194 Limits the packages installed directly due to
 195 .B --install-from-source
 196 directives; the patterns are interpreted as for
 197 .BR --package-filter-dependency .
 198 .TP
 199 .BR --control [ -tb ] " " \fIcontrol\fR
 200 Specifies that
 201 .I control
 202 should be used as the test control file instead of
 203 .B debian/tests/control
 204 in the build tree.  Note that it is not an error for this file not to
 205 exist; that just means that there are no tests.
 206 .TP
 207 .BR --output-dir [ -tb ] " " \fIoutput-dir\fR
 208 Specifies that stderr and stdout from the tests should be placed in
 209 .IR output-dir .
 210 The files are named
 211 .BI stderr- test
 212 and
 213 .BI stdout- test
 214 for each test
 215 .IR test ,
 216 and
 217 .BR log-buildt " (for the build logs from " --build-source ),
 218 .BI log-buildi- i
 219 .RI "(for the build logs from the " i th
 220 .BR --install-from-source ),
 221 .BI log-install- j
 222 .RI "(for the installation logs from the " j "th installation or removal)".
 223 .TP
 224 .BR -d " | " --debug
 225 Enables debugging output.  Probably not hugely interesting.
 226 .TP
 227 \fB---\fR \fIvirt-server virt-server-arg\fR...
 228 Specifies the virtualisation regime server, as a command and arguments
 229 to invoke.  All the remaining arguments and options after
 230 .B ---
 231 are passed to the virtualisation server program.
 232
 233 .SS NOTES
 234 Some options which come in variants with and without
 235 .BR -tb .
 236 These specify paths on the testbed and the host, respectively.  The
 237 data will be copied by
 238 .B adt-run
 239 to where it is needed.
 240
 241 .SH OUTPUT FORMAT
 242 During a normal test run, one line is printed for each test.  This
 243 consists of the name of the test, some horizontal whitespace, and
 244 either
 245 .B PASS
 246 or
 247 .BR FAIL " reason"
 248 or
 249 .BR SKIP " reason"
 250 where the pass/fail indication is separated by any reason by some
 251 horizontal whitespace.
 252
 253 Sometimes a
 254 .B SKIP
 255 will be reported when the name of the test is not known or not
 256 applicable: for example, when there are no tests in the package, or a
 257 there is a test stanza which contains features not understood by this
 258 version of
 259 .BR adt-run .
 260 In this case
 261 .B *
 262 will appear where the name of the test should be.
 263
 264 .SH EXIT STATUS
 265 0       all tests passed
 266 .br
 267 2       at least one test skipped
 268 .br
 269 4       at least one test failed
 270 .br
 271 6       at least one test failed and at least one test skipped
 272 .br
 273 8       no tests in this package
 274 .br
 275 12      erroneous package
 276 .br
 277 16      testbed failure
 278 .br
 279 20      other unexpected failures including bad usage
 280
 281 .SH SEE ALSO
 282 \fBadt-virt-chroot\fR(1)
 283
 284 .SH BUGS
 285 This tool still lacks many important features.
 286
 287 .SH AUTHORS AND COPYRIGHT
 288 This manpage is part of autopkgtest, a tool for testing Debian binary
 289 packages.  autopkgtest is Copyright (C) 2006 Canonical Ltd and others.
 290
 291 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 292 contributors and full copying conditions.