Ubuntu logo

Packaging Guide

3. autopkgtest : tests automatiques pour les paquets

The DEP 8 specification defines how automatic testing can very easily be integrated into packages. To integrate a test into a package, all you need to do is:

  • ajoutez un fichier appelé debian/tests/control qui spécifie les exigences pour le banc d’essai,
  • ajoutez les tests dans debian/tests/.

3.1. Exigences du banc d’essai

In debian/tests/control you specify what to expect from the testbed. So for example you list all the required packages for the tests, if the testbed gets broken during the build or if root permissions are required. The DEP 8 specification lists all available options.

Ci-dessous, nous voyons un aperçu du paquet source glib2.0. Dans un cas très simple, le fichier devrait ressembler à ceci:

Tests: build
Depends: libglib2.0-dev, build-essential

Pour le test dans debian/tests/build, cela permettrait de s’assurer que les paquets libglib2.0-dev et build-essential sont installés.

Note

Vous pouvez utiliser @ de la ligne Depends pour indiquer que vous souhaitez tous les paquets installés construits par la paquet source en question.

3.2. Les tests réels

Le test accompagnant l’exemple ci-dessus pourrait être :

#!/bin/sh
# autopkgtest check: Build and run a program against glib, to verify that the
# headers and pkg-config file are installed correctly
# (C) 2012 Canonical Ltd.
# Author: Martin Pitt <martin.pitt@ubuntu.com>

set -e

WORKDIR=$(mktemp -d)
trap "rm -rf $WORKDIR" 0 INT QUIT ABRT PIPE TERM
cd $WORKDIR
cat <<EOF > glibtest.c
#include <glib.h>

int main()
{
    g_assert_cmpint (g_strcmp0 (NULL, "hello"), ==, -1);
    g_assert_cmpstr (g_find_program_in_path ("bash"), ==, "/bin/bash");
    return 0;
}
EOF

gcc -o glibtest glibtest.c `pkg-config --cflags --libs glib-2.0`
echo "build: OK"
[ -x glibtest ]
./glibtest
echo "run: OK"

Ici, un morceau très simple de code C est écrit dans un répertoire temporaire. C’est ensuite compilé avec les bibliothèques système (en utilisant les drapeaux et chemins des bibliothèques fournis par pkg-config). Ensuite, le binaire compilé, qui fait juste appel à quelques fonctionnalités glib de parties du noyau, est exécuté.

While this test is very small and simple, it covers quite a lot: that your -dev package has all necessary dependencies, that your package installs working pkg-config files, headers and libraries are put into the right place, or that the compiler and linker work. This helps to uncover critical issues early on.

3.3. Exécution du test

While the test script can be easily executed on its own, it is strongly recommended to actually use autopkgtest from the autopkgtest package for verifying that your test works; otherwise, if it fails in the Ubuntu Continuous Integration (CI) system, it will not land in Ubuntu. This also avoids cluttering your workstation with test packages or test configuration if the test does something more intrusive than the simple example above.

The README.running-tests (online version) documentation explains all available testbeds (schroot, LXD, QEMU, etc.) and the most common scenarios how to run your tests with autopkgtest, e. g. with locally built binaries, locally modified tests, etc.

The Ubuntu CI system uses the QEMU runner and runs the tests from the packages in the archive, with -proposed enabled. To reproduce the exact same environment, first install the necessary packages:

sudo apt-get install autopkgtest qemu-system qemu-utils

Now build a testbed with:

autopkgtest-buildvm-ubuntu-cloud -v

(Please see its manpage and --help output for selecting different releases, architectures, output directory, or using proxies). This will build e. g. adt-trusty-amd64-cloud.img.

Then run the tests of a source package like libpng in that QEMU image:

autopkgtest libpng --- qemu adt-trusty-amd64-cloud.img

The Ubuntu CI system runs packages with only selected packages from -proposed available (the package which caused the test to be run); to enable that, run:

autopkgtest libpng -U --apt-pocket=proposed=src:foo --- qemu adt-release-amd64-cloud.img

or to run with all packages from -proposed:

autopkgtest libpng -U --apt-pocket=proposed --- qemu adt-release-amd64-cloud.img

The autopkgtest manpage has a lot more valuable information on other testing options.

3.4. Exemples complémentaires

Cette liste n’est pas exhaustive mais elle peut vous aider à mieux comprendre comment les tests automatiques sont implémentés et utilisés dans Ubuntu.

  • The libxml2 tests are very similar. They also run a test-build of a simple piece of C code and execute it.
  • The gtk+3.0 tests also do a compile/link/run check in the “build” test. There is an additional “python3-gi” test which verifies that the GTK library can also be used through introspection.
  • In the ubiquity tests the upstream test-suite is executed.
  • The gvfs tests have comprehensive testing of their functionality and are very interesting because they emulate usage of CDs, Samba, DAV and other bits.

3.5. infrastructure Ubuntu

Packages which have autopkgtest enabled will have their tests run whenever they get uploaded or any of their dependencies change. The output of automatically run autopkgtest tests can be viewed on the web and is regularly updated.

Debian also uses autopkgtest to run package tests, although currently only in schroots, so results may vary a bit. Results and logs can be seen on http://ci.debian.net. So please submit any test fixes or new tests to Debian as well.

3.6. Faire passer le test dans Ubuntu

Le processus de soumission d’un autopkgtest pour un paquet est très similaire à corriger un bogue dans Ubuntu. Essentiellement, il vous suffit de :

  • exécuter bzr branch ubuntu:<nomdupaquet>,
  • modifier debian/control pour activer les tests,
  • ajouter le répertoire debian/tests,
  • write the debian/tests/control based on the DEP 8 Specification,
  • ajouter votre cas de test(s) à debian/tests,
  • valider vos modifications, les téléverser vers Launchpad, proposer une fusion et obtenir son examen, exactement comme pour toute autre amélioration dans un paquet source.

3.7. Ce que vous pouvez faire

The Ubuntu Engineering team put together a list of required test-cases, where packages which need tests are put into different categories. Here you can find examples of these tests and easily assign them to yourself.

If you should run into any problems, you can join the #ubuntu-quality IRC channel to get in touch with developers who can help you.