FAQ for package maintainers
How can I reproduce the test run locally?
NOTE: if you intend to run tests frequently, you should
consider installing apt-cacher-ng
before anything else.
debci
will notice the running proxy and will setup the testbed
to use it, so you won't have to wait for the download of each package
more than once.
Using no virtualization backend
This is the fastest way to run tests, but does not reproduce the continuous integration environment faithfully and your local environment may make the results unreliable. It's useful nevertheless when initially writing the tests, or for quick runs against your main host system.
To run the test suite from the root of a source package against the currently installed packages, run:
$ autopkgtest --output-dir /tmp/output-dir -B . -- null
For more details, see the documentation for the autopkgtest
package.
Using the lxc backend (default as of debci >= 1.0)
First step is to configure networking for the lxc containers. The easiest way to to that is by using the libvirt networking support. First, install the necessary packages and activate the default libvirt network:
# apt install lxc libvirt-clients libvirt-daemon-system
# virsh net-start default
# virsh net-autostart default
Note: the default libvirt network will use the
192.168.122.0/24
network. If that conflicts with your local
network, you will need to configure it to use a different IP range.
Now configure lxc to use the default libvirt network, by putting the
following content in /etc/lxc/default.conf
:
lxc.network.type = veth
lxc.network.link = virbr0
lxc.network.flags = up
Now install and configure debci
:
$ sudo apt install debci autopkgtest
You will also need permissions to run the lxc-*
commands as
root, preserving your environment. An easy way to do that is to add
yourself to the debci group.
$ sudo addgroup YOUR_USERNAME debci
You're now ready to create the lxc container:
$ sudo debci setup
This might take a few minutes since it will create a fresh container from scratch.
Now to actually run tests, we'll use autopkgtest
directly.
The following examples assume your architecture is amd64, replace it by
your actual architecture if that is not the case.
To run the test suite from a source package in the archive, just pass the source package name to autopkgtest:
$ autopkgtest --user debci --output-dir /tmp/output-dir SOURCEPACKAGE \
-- lxc --sudo autopkgtest-sid-amd64
To run the test suite against a locally-built source
package, using the test suite from that source package and the
binary packages you just built, you can pass the .changes
file
to autopkgtest:
$ autopkgtest --user debci --output-dir /tmp/output-dir \
/path/to/PACKAGE_x.y-z_amd64.changes \
-- lxc --sudo autopkgtest-sid-amd64
For more details, see the documentation for the autopkgtest
package.
Using the schroot backend
Install a configure debci
and schroot
:
$ sudo apt install debci autopkgtest schroot
$ sudo debci setup --backend schroot
Edit /etc/schroot/chroot.d/debci-SUITE-ARCH
(by default
SUITE
is unstable
and ARCH
is your
native architecture), and add your username to the users
,
root-users
and source-root-users
configuration
keys:
[...]
users=debci,$YOUR_USERNAME
[...]
root-users=debci,$YOUR_USERNAME
source-root=users=debci,$YOUR_USERNAME
[...]
To speed up test suite execution, you can also add the following line at the end:
union-overlay-directory=/dev/shm
This will mount the chroot overlay on tmpfs
which will make
installing test dependencies a lot faster. If your hard disk is already a
SSD, you probably don't need that. If you don't have a good amount
of RAM, you may have problems using this.
The following examples assume:
-
suite =
unstable
(the default) -
architecture =
amd64
To run the test suite from a source package in the archive, you pass the package name to autopkgtest:
$ autopkgtest --user debci --output-dir /tmp/output-dir SOURCEPACKAGE -- schroot debci-unstable-amd64
To run the test suite against a locally-built source
package, using the test suite from that source package and the
binary packages you just built, you can pass the .changes
file
to autopkgtest:
$ autopkgtest --user debci --output-dir /tmp/output-dir \
/path/to/PACKAGE_x.y-z_amd64.changes \
-- schroot debci-unstable-amd64
For more details, see the documentation for the autopkgtest
package.
How do I get my package to have its test suite executed?
Test suites must be included in source packages as defined in the DEP-8 specification. In short.
-
The fact that the package has a test suite must be declared by adding a
Testsuite: autopkgtest
entry to the source stanza indebian/control
. -
if the package is built with dpkg earlier than 1.17.6, you need to use
XS-Testsuite: autopkgtest
instead. -
tests are declared in
debian/tests/control
.
Please refer to the DEP-8 spec for details on how to declare your tests.
How exactly is the test suite executed?
Test suites are executed by autopkgtest. The version of autopkgtest used to execute the tests is shown in the log file for each test run.
How often are test suites executed?
The test suite for a source package will be executed:
-
when any package in the dependency chain of its binary packages changes;
-
when the package itself changes;
-
when 1 month is passed since the test suite was run for the last time.