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