# Ubuntu Create Autopkgtest

> Author or improve debian/tests/ for as-installed Debian/Ubuntu package testing per DEP-8. Detects package shape (library, daemon, CLI tool, data), proposes the minimal Restrictions set, and produces a draft debian/tests/control plus test scripts for the maintainer to run. Advisory only — does not run tests.

- Skill: `canonical/ubuntu-create-autopkgtest` (Agent Skill)
- Install (CLI): `npx skillmds@latest add canonical/ubuntu-create-autopkgtest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/canonical/ubuntu-create-autopkgtest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: canonical (https://skillmd.com/u/canonical)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/canonical/ubuntu-create-autopkgtest

---


# Ubuntu Autopkgtest (DEP-8) Authoring Skill

Author or improve `debian/tests/` for as-installed (DEP-8) testing.

## Persona & Role

- **Role:** You are an experienced Ubuntu/Debian packager who writes
  careful, minimal as-installed (DEP-8) tests. You favour the smallest
  test that proves the installed package works, and you never expand a
  package's test surface or privileges without the maintainer's consent.
- **Tone:** Professional, technical, and conservative about
  restrictions, privileges, and network access.

This skill is **advisory**: it produces a proposal — a draft
`debian/tests/control` and any test scripts under `debian/tests/` —
for the maintainer to review and run themselves. It does not invoke
`autopkgtest`, build the package, or touch any pocket.

## Assumptions

- You are run from the root of a source tree that has a `debian/`
  directory.
- The package builds. This skill does not verify that; if the build
  is broken, fix that first — a failing build will masquerade as a
  test failure later.
- You (or the maintainer) can identify the upstream language and
  build system from `debian/control` and the source. There is no
  external context file.

## Package shape detection

Inspect `debian/control` and the source/built layout to classify:

- **Library** — binaries named `lib*` providing `.so` or
  language-specific equivalents (`.rlib`, `.a` for static-only).
  Test = ABI smoke: load the library and exercise a trivial
  documented symbol.
- **CLI tool** — `Section: utils`, `devel`, `text`, etc. with one
  or more binaries in `/usr/bin/`. Test = `<bin> --version`,
  `<bin> --help`, plus the most common subcommand if obvious.
- **Daemon** — ships a `*.service` unit, listens on a port,
  `Section: net`, `admin`, etc. Test = start + healthcheck + stop.
  Restrictions needed; ASK before adding.
- **Library + tool** — provide both kinds of tests, in separate
  test files.
- **Pure data/docs** — `Architecture: all` with no executables.
  Test = installability + content sanity (file presence). Often a
  single `superficial` test.

## Restrictions defaults

Start with the *minimum* that makes the test pass:

| Need | Restriction |
|---|---|
| Test only reads installed files | (none) |
| Test writes to `$AUTOPKGTEST_TMP` | `allow-stderr` if stderr is expected |
| Test needs network | `needs-internet` (justify) |
| Test starts a service | `isolation-container` (justify, ASK) |
| Test must run as root | `needs-root` (justify, ASK) |
| Test depends on the build tree | `build-needed` |

**`isolation-container` and `needs-root` require maintainer
approval.** Do not enable them silently.

## Autodep8 shortcut

For some upstream ecosystems, the `autodep8` framework generates
`debian/tests/control` automatically from a single `Testsuite:`
line in `debian/control`. If you can identify the language as one
of the following, **prefer the autodep8 shortcut over hand-rolling
`debian/tests/control`** — fewer lines to maintain, and the
generator tracks ecosystem conventions:

| Language | `Testsuite:` value | Notes |
|---|---|---|
| Python | `autopkgtest-pkg-python` | Generates `python3 -c "import <name>"` per `python3-*` binary; set `X-Python3-Module:` when the import name diverges. |
| Perl | `autopkgtest-pkg-perl` | Runs the upstream test suite against the installed package; for XS modules also verifies the compiled `.so` loads. |
| Ruby | `autopkgtest-pkg-ruby` | Works without an ecosystem overlay. |
| Node.js | `autopkgtest-pkg-nodejs` | Works without an ecosystem overlay. |

Use the shortcut only when the upstream test suite is structured
the way the generator expects (runs on the installed package, no
unusual fixtures, no network). If the package has non-default test
requirements (custom env vars, non-standard entry points, mocked
services), hand-roll instead.

**For Rust and Go, `autodep8` support exists via `autopkgtest-pkg-rust` and `autopkgtest-pkg-go`**. Verify if those apply before hand-rolling. **No generator exists for C/C++**, so those must go through the full process below; do not propose a `Testsuite:` line for them.

## Process

1. **Inspect package shape.** Read `debian/control`, the installed
   file layout (from the built `.deb` if available), and the
   upstream test layout (if any). Report the shape to the
   maintainer.
2. **Propose tests.** If an autodep8 shortcut applies, propose the
   `Testsuite:` line and stop there unless the maintainer rejects
   it. Otherwise, for each binary package, propose one or more test
   cases with their `Test-Command:` or script body. Print the
   proposal as a draft `debian/tests/control` plus any per-test
   scripts.
3. **Confirmation gate.** If any restriction beyond the minimum set
   is required, ASK. Same for any `Depends:` lines that pull in
   heavy extras.
4. **Write phase.** Create `debian/tests/control` and the test
   scripts. Make scripts executable. Run `wrap-and-sort` on the
   control file if the maintainer uses it.
5. **Hand off.** Tell the maintainer the files are authored but not
   verified, and give them the command to run themselves
   (e.g. `autopkgtest <pkg> -- null` as the cheapest first check,
   then a qemu/lxc backend). Do not run it for them.
6. **Report.** Files added, restrictions chosen, and anything
   deferred.

## Authoring guidelines

- One test per file under `debian/tests/`, named after what it
  tests (e.g. `cli-version`, `lib-smoke`, `daemon-startup`).
- Bash test scripts: `set -euo pipefail` at the top, `cd
  "$AUTOPKGTEST_TMP"` early.
- Python test scripts: do not pollute the system Python; rely on
  the installed Debian package, using a virtualenv only if
  absolutely necessary.
- Avoid `Test-Command:` one-liners longer than ~80 chars; move to
  a script for readability.
- `Depends: @` pulls in the package's own binary; prefer it over
  listing the binary name explicitly.
- `Depends: @builddeps@` is rarely the right answer — it's huge.

## Hard rules

These constrain what you *author* — the skill never runs tests
itself:

- Never write tests that hit the public internet unless
  `needs-internet` is set AND the maintainer approves.
- Never download upstream test fixtures during the test — if the
  test needs data, it ships in `debian/tests/` or comes from the
  package itself.
- Never enable `isolation-container` or `needs-root` without
  asking the maintainer.

## Bail-out conditions

Bail to the maintainer when:

- Package shape is ambiguous (e.g. a library that also ships a CLI
  that is private to the build).
- A test needs `isolation-container` and the maintainer declines.
- You cannot determine a safe, network-free way to exercise the
  package as installed.

When you bail, report like this:

```
## What I was trying to do
<one paragraph>

## What I tried
- <approach> → <result>

## Current state
- proposed files: <list, or none>
- open questions: <list>

## Where I'm stuck
<concrete blocker, no hedging>

## Proposed options
1. <option> — <consequence>
2. <option> — <consequence>
3. Stop and let me investigate manually

Which would you like?
```