| 1 |
[[!meta title="DEP-8: automatic as-installed package testing"]]
|
| 2 |
|
| 3 |
Title: autopkgtest - automatic as-installed package testing
|
| 4 |
DEP: 8
|
| 5 |
State: DRAFT
|
| 6 |
Date: 2011-02-27
|
| 7 |
Drivers: Ian Jackson <ijackson@chiark.greenend.org.uk>,
|
| 8 |
Iustin Pop <iustin@debian.org>,
|
| 9 |
Stefano Zacchiroli <zack@debian.org>
|
| 10 |
URL: http://dep.debian.net/deps/dep8
|
| 11 |
Source: http://anonscm.debian.org/viewvc/dep/web/deps/dep8.mdwn
|
| 12 |
License:
|
| 13 |
Copying and distribution of this file, with or without modification,
|
| 14 |
are permitted in any medium without royalty provided the copyright
|
| 15 |
notice and this notice are preserved.
|
| 16 |
Abstract:
|
| 17 |
Establish a standard interface to define and run "as-installed" tests of
|
| 18 |
packages, i.e. the testing of packages in a context as close as possible
|
| 19 |
to a Debian system where the packages subject to testing are properly
|
| 20 |
installed.
|
| 21 |
|
| 22 |
[[!toc ]]
|
| 23 |
|
| 24 |
|
| 25 |
# Introduction
|
| 26 |
|
| 27 |
In the working.
|
| 28 |
|
| 29 |
In the meantime you can check the original specification below, which is
|
| 30 |
currently implemented by the
|
| 31 |
[autopkgtest](http://packages.debian.org/sid/autopkgtest) package.
|
| 32 |
|
| 33 |
----
|
| 34 |
|
| 35 |
|
| 36 |
# Appendix A - original specification
|
| 37 |
|
| 38 |
|
| 39 |
## Introduction
|
| 40 |
|
| 41 |
This document describes how the autopkgtest tester core (the program `adt-run`)
|
| 42 |
interprets and executes tests found in source packages.
|
| 43 |
|
| 44 |
The source package provides a test metadata file debian/tests/control. This is
|
| 45 |
a file containing zero or more RFC822-style stanzas, along these lines:
|
| 46 |
|
| 47 |
Tests: fred bill bongo
|
| 48 |
Restrictions: needs-root breaks-computer
|
| 49 |
|
| 50 |
This example defines three tests, called `fred`, `bill` and `bongo`. The tests
|
| 51 |
will be performed by executing debian/tests/fred, debian/tests/bill, etc. Each
|
| 52 |
test program should, on success, exit with status 0 and print nothing to
|
| 53 |
stderr; if a test exits nonzero, or prints to stderr, it is considered to have
|
| 54 |
failed.
|
| 55 |
|
| 56 |
The cwd of each test is guaranteed to be the root of the source package which
|
| 57 |
will have been built. HOWEVER note that the tests must test the INSTALLED
|
| 58 |
version of the program. Tests may not modify the source tree (and may not have
|
| 59 |
write access to it).
|
| 60 |
|
| 61 |
If the file to be executed has no execute bits set, `chmod a+x` is applied to
|
| 62 |
it (this means that tests can be added in patches without the need for
|
| 63 |
additional chmod; contrast this with debian/rules).
|
| 64 |
|
| 65 |
During execution of the test, the environment variable TMPDIR will point to a
|
| 66 |
directory for the execution of this particular test, which starts empty and
|
| 67 |
will be deleted afterwards (so there is no need for the test to clean up files
|
| 68 |
left there).
|
| 69 |
|
| 70 |
Tests must declare all applicable Restrictions - see below.
|
| 71 |
|
| 72 |
|
| 73 |
The fields which may appear in the RFC822-style stanza are:
|
| 74 |
|
| 75 |
* `Tests: <name-of-test> [<name-of-another-test> ...]`
|
| 76 |
|
| 77 |
This field is mandatory. It names the tests which are defined by this
|
| 78 |
stanza. All of the other fields in the same stanza apply to all of the named
|
| 79 |
tests.
|
| 80 |
|
| 81 |
Test names are separated by whitespace and should contain only characters
|
| 82 |
which are legal in package names, plus `/'.
|
| 83 |
|
| 84 |
* `Restrictions: <restriction-name> [<another-restriction-name> ...]`
|
| 85 |
|
| 86 |
Declares some restrictions or problems with the tests defined in this stanza.
|
| 87 |
Depending on the test environment capabilities, user requests, and so on,
|
| 88 |
restrictions can cause tests to be skipped or can cause the test to be run in
|
| 89 |
a different manner. Tests which declare unknown restrictions will be
|
| 90 |
skipped. See below for the defined restrictions.
|
| 91 |
|
| 92 |
* `Features: <feature-name> [<another-feature-name> ...]`
|
| 93 |
|
| 94 |
Declares some additional capabilities or good properties of the tests defined
|
| 95 |
in this stanza. Any unknown features declared will be completely ignored.
|
| 96 |
See below for the defined features.
|
| 97 |
|
| 98 |
* `Depends: <dpkg dependcy field syntax>`
|
| 99 |
|
| 100 |
Declares that the specified packages must be installed for the test to go
|
| 101 |
ahead. `@` stands for the package(s) generated by the source package
|
| 102 |
containing the tests; each dependency (strictly, or-clause, which may contain
|
| 103 |
`|`-s but not commas) containing `@` is replicated once for each such binary
|
| 104 |
package, with the binary package name substituted for each `@` (but normally
|
| 105 |
`@` should occur only once and without a version restriction).
|
| 106 |
|
| 107 |
If no Depends field is present, `Depends: @` is assumed. Note that the
|
| 108 |
source tree's Build-Dependencies are *not* necessarily installed, and if you
|
| 109 |
specify any Depends, no binary packages from the source are installed unless
|
| 110 |
explicitly requested.
|
| 111 |
|
| 112 |
* `Tests-Directory: <path>`
|
| 113 |
|
| 114 |
Replaces the path segment `debian/tests` in the filenames of the test
|
| 115 |
programs with <path>. Ie, the tests are run by executing
|
| 116 |
`/path/to/built/source/tree/<path>/<name-of-test>`. `<path>` must be a
|
| 117 |
relative path and is interpreted starting from the root of the built source
|
| 118 |
tree.
|
| 119 |
|
| 120 |
This allows tests to live outside the debian/ metadata area, so that they can
|
| 121 |
more palatably be shared with non-Debian distributions.
|
| 122 |
|
| 123 |
Any unknown fields will cause the whole stanza to be skipped.
|
| 124 |
|
| 125 |
|
| 126 |
## Restrictions
|
| 127 |
|
| 128 |
The defined Restrictions are:
|
| 129 |
|
| 130 |
* `rw-build-tree`
|
| 131 |
|
| 132 |
The test(s) needs write access to the built source tree (so it may need to be
|
| 133 |
copied first). Even with this restriction, the test is not allowed to make
|
| 134 |
any change to the built source tree which (i) isn't cleaned up by
|
| 135 |
debian/rules clean, (ii) affects the future results of any test, or (iii)
|
| 136 |
affects binary packages produced by the build tree in the future.
|
| 137 |
|
| 138 |
* `breaks-testbed`
|
| 139 |
|
| 140 |
The test, when run, is liable to break the testbed system. This includes
|
| 141 |
causing data loss, causing services that the machine is running to
|
| 142 |
malfunction, or permanently disabling services; it does not include causing
|
| 143 |
services on the machine to temporarily fail.
|
| 144 |
|
| 145 |
When this restriction is present the test will usually be skipped unless the
|
| 146 |
testbed's virtualisation arrangements are sufficiently powerful, or
|
| 147 |
alternatively if the user explicitly requests.
|
| 148 |
|
| 149 |
* `needs-root`
|
| 150 |
|
| 151 |
The test script must be run as root.
|
| 152 |
|
| 153 |
|
| 154 |
## Features
|
| 155 |
|
| 156 |
The currently defined Features are:
|
| 157 |
|
| 158 |
* `no-build-needed`
|
| 159 |
|
| 160 |
The tests can run in an unbuilt tree.
|
| 161 |
|
Parent Directory
| 
Revision Log