How Piuparts Tests Debian Package Installation

This article examines how piuparts (package installation, upgrading, and purging action testing tool) automates the quality assurance process for Debian packages. It covers the mechanics of how the tool creates isolated environments, executes clean installations, tests upgrade paths from previous releases, verifies complete package removal and purging, and checks for lingering filesystem artifacts.

Isolated Environment Creation

To ensure tests are deterministic and do not alter the host system, piuparts runs its tests inside an isolated environment, typically a minimal chroot, container, or virtual machine.

Before starting any package operation, piuparts initializes this environment with a bare minimum base system (usually created using debootstrap). It records a complete snapshot of the filesystem, logging all existing files, directories, symbolic links, and their respective permissions and ownership metadata. This initial snapshot serves as the baseline against which the system state is later compared.

Clean Installation Testing

The clean installation test evaluates whether a package can install reliably on an unmodified system:

  1. Dependency Resolution: piuparts invokes apt-get to fetch and install all required runtime dependencies from configured Debian repositories.
  2. Package Unpacking and Configuration: The package under test is unpacked, and its maintainer scripts (preinst and postinst) are executed.
  3. Execution Verification: piuparts monitors the exit codes of these scripts. If any maintainer script fails or returns a non-zero exit status, the test immediately flags an installation failure.
  4. Log Inspection: The process captures logs to detect warnings, deprecated command usage, or unexpected script output.

Upgrade Testing

Debian requires smooth transitions between package releases and stable distribution upgrades. piuparts verifies this by simulating package upgrades:

  1. Baseline Version Installation: piuparts first installs the older, currently released version of the package from the Debian archive.
  2. Transition Execution: It then instructs the package manager to install the new candidate .deb package over the existing version.
  3. Lifecycle Script Verification: This tests whether the transition scripts—specifically the old package's prerm and postrm and the new package's preinst and postinst—execute in the correct sequence without data loss, broken configuration files, or dependency deadlocks.

Package Removal and Purging

Debian Policy dictates that removing a package should delete its program files while preserving configuration files, whereas purging must eradicate all files associated with the package. piuparts tests both stages:

  1. Removal (apt-get remove): The tool uninstalls the package, ensuring that binaries, libraries, and auxiliary files are removed, while configuration files (conffiles) are left intact.
  2. Purging (apt-get purge): The tool instructs the package manager to purge the package, triggering the postrm purge script, which must remove all configuration files, state files, generated directories, and dynamically created system users.

Post-Purge Filesystem Comparison

The final phase is the integrity check. Once the purge operation completes, piuparts scans the entire filesystem again and compares the resulting state with the initial snapshot taken before the package was introduced.

The test fails if it detects any of the following anomalies:

  • Leftover Files: Unowned files, empty directories, or log files that were created by the package or its maintainer scripts but were not deleted upon purging.
  • Modified System Files: Files belonging to other packages or the base system that were unexpectedly altered.
  • Broken Symlinks: Dangling symbolic links pointing to resources that were removed.
  • Permission Changes: Unintended modifications to system directory permissions or ownership.

If the final filesystem state matches the initial baseline (allowing only for explicitly whitelisted system logs or state files), piuparts marks the package as compliant with Debian Policy.