autopkgtest

Build the package in the current directory and run all tests directly on the system

$ autopkgtest -- [null]

$ autopkgtest --test-name=[test_name] -- [null]

$ autopkgtest [package] -- [null]

$ autopkgtest -- [chroot] [path/to/new/root]

$ autopkgtest [[-B|--no-built-binaries]] -- [null]

autopkgtest [options] {<source-package> | <deb-package> | <changes-file> | <dsc-file>} [-- <test-arguments>]

--testbed=<spec> or -B
    Specifies the isolated testbed environment (e.g., schroot, qemu, lxc) where tests will be executed.

--apt-source-path=<path>
    Adds a directory containing APT sources list files to be used for package installation within the testbed.

--architecture=<arch>
    Defines the target architecture for the testbed and package installation, essential for cross-architecture testing.

--schroot=<spec>
    Uses a pre-configured schroot environment as the testbed, providing a chroot with additional capabilities.

--qemu=<spec>
    Utilizes a QEMU virtual machine as the testbed, enabling full system emulation and testing on different hardware architectures.

--lxc=<spec>
    Employs an LXC (Linux container) as the testbed, offering lightweight process and filesystem isolation.

--timeout=<seconds>
    Sets a maximum runtime for the entire test suite, preventing tests from hanging indefinitely.

--output-dir=<dir>
    Specifies a directory where test results, logs, and any generated artifacts will be stored.

--shell
    Opens an interactive shell inside the testbed after tests complete (or fail), useful for manual debugging.

--verbose
    Increases the verbosity of the output, showing more detailed information about the testing process.

--debug
    Enables debug output, providing extensive diagnostic information for troubleshooting.

autopkgtest is a powerful command-line tool primarily used in Debian and Ubuntu for running automated tests on binary and source packages. Its main purpose is to help package maintainers and distribution developers ensure that packages function correctly after being built and that new package versions do not introduce regressions.

The command executes tests defined by the package itself (typically in a debian/tests/control file) within an isolated testbed environment, such as a schroot, QEMU virtual machine, or LXC container. This isolation is crucial as it prevents tests from interfering with the host system or other tests, ensuring reproducible and reliable results.

autopkgtest plays a vital role in continuous integration (CI) systems, enabling proactive detection of bugs, dependency issues, and build failures. This contributes significantly to the overall stability and quality of the distribution by providing a robust framework for comprehensive quality assurance across various architectures and releases.

Requires a pre-configured testbed environment (e.g., schroot chroots, QEMU images, LXC containers) to function correctly.
Testing can be resource-intensive, demanding significant CPU, RAM, and disk space, especially for QEMU testbeds or large test suites.
Relies heavily on the debian/tests/control file within the package for test definitions; a missing or malformed file will prevent tests from running.
Tests often require network access to fetch dependencies, which must be appropriately configured within the testbed environment.

autopkgtest relies on "testbeds" to provide isolated environments for executing tests. Common testbed types include schroot (a chroot with additional configuration), QEMU (a full system emulator for hardware isolation and cross-architecture testing), and LXC (lightweight Linux containers offering process isolation). This isolation ensures that tests run in a clean, reproducible state without impacting the host system or other packages, making the test results reliable.

For autopkgtest to run tests on a package, the package must contain a debian/tests/control file. This file specifies various test cases, their dependencies, and how they should be executed. It acts as a manifest, guiding autopkgtest on what to run and how to set up the test environment within the chosen testbed. This declarative approach allows package maintainers to define robust and repeatable tests.

autopkgtest was developed as a critical component of Debian's quality assurance infrastructure, aiming to automate and standardize the testing of packages. Its inception was driven by the need to prevent regressions and ensure the stability of the distribution amidst a vast number of package uploads and updates.

It gained prominence as Debian and Ubuntu moved towards more robust continuous integration (CI) practices, becoming an integral part of automated build systems like ci.debian.org and salsa.debian.org (Debian's GitLab instance). The tool has continuously evolved to support various isolation technologies (schroot, QEMU, LXC) and features, reflecting the diverse testing requirements of a large Linux distribution.

dpkg-buildpackage(1), deb(5), debian/tests/control(5), schroot(1), qemu-system-x86_64(1), lxc(1)