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