Files
VDI-Linux/debian/test/README.md
T
Mistercoolertyper 6ddb1d251a Add Debian 13 (trixie) support alongside Fedora
The provisioning path now runs on both package families. Fedora behaviour is
unchanged: the Fedora publishing code issues the same ten operations in the
same order as before, verified by recording the call sequence from both
implementations against a stubbed environment.

update_local_repo.py
  Detects the family from /etc/os-release and dispatches to sync_fedora() or
  sync_debian(). Release assets are filtered by extension, so neither family
  sees the other's packages. The Debian path builds a flat apt-ftparchive
  repository at the same /var/local/citrix-repo, publishes
  local-citrix-repo.list, and runs apt-get update.

  Fixes found while testing:
  - tqdm is now an optional dependency. A stock Debian 13 image has no pip and
    no tqdm, and dying at import would take down provisioning over a progress
    bar.
  - sync_debian prunes stale *.deb files before repopulating. The Fedora path
    gets this for free by writing fixed filenames; Debian filenames carry the
    version, so without pruning every old version stayed indexed and apt always
    picked the highest, making rollback impossible.
  - The apt source file is resolved next to the script rather than from the
    working directory, with a hardcoded canonical fallback, so a foreign cwd or
    a missing file cannot break the 10-minute cron job.

local-citrix-repo.list
  The apt counterpart of local-citrix-repo.repo, which stays as-is for dnf.
  Uses trusted=yes rather than a signature: the repository is generated on the
  machine from packages this script downloaded itself, so a signature would only
  prove the machine signed its own work, and it would add a gpg dependency that
  Debian 13 does not ship by default. Index integrity is still enforced through
  the hashes in Release.

debian/preseed.cfg
  The debian-installer equivalent of ks.cfg. Same locale, keyboard, timezone,
  passwords, inventory-derived hostname/user/password, disk auto-detection,
  Firefox managed bookmarks, Citrix and TeamViewer installs, auto-update script,
  cron jobs and disable-sleep unit. Every directive was checked against the
  templates in the real trixie udebs. Documented gaps, all inherent to preseed
  vs kickstart: uppercase usernames are rejected by user-setup and so are
  created in late_command; d-i has no lsblk, openssl, chvt or openvt, so disk
  detection reads /sys/block and the inventory prompt goes to /dev/console with
  a kernel-cmdline override and a timeout; pip install tqdm becomes
  python3-tqdm from apt because of PEP 668.

debian/test/
  Harness covering the Debian path on a real Debian 13 machine: repo build,
  sources.list validity, apt visibility after purging the list cache, install
  resolution, idempotency, stale-package pruning, corrupt-index rejection, and
  Fedora non-regression. 52 pass, 3 skip (each skip states why).

Known limitations are listed in README.md under "What the tests do NOT prove":
no real d-i install has been run, and the generated post-install script is
verified as well-formed rather than executed against a target root.
2026-11-04 09:24:57 +01:00

256 lines
12 KiB
Markdown

# Debian port test harness
`run-tests.sh` proves that the Debian side of the VDI-Linux port actually works,
and that the Fedora side has not regressed. It is a real harness: it builds a
real apt repository from the real Citrix `.deb` packages, adds a real apt
source, and asks real apt whether it can install the result. Nothing is
simulated except the parts that would change the machine.
```sh
sudo bash debian/test/run-tests.sh
```
Run as root. It needs the two Citrix `.deb` files (see [Fixtures](#fixtures)).
Exit status is 0 when no test FAILED, 1 otherwise. A SKIP does not fail the run,
but every skip prints why it skipped and what it would have checked. **A skip is
not a pass**, and the summary says so.
## What it tests
| Test | What it proves |
|------|----------------|
| T00 | Environment: root, required tools, trixie, fixtures present |
| T01 | The `.deb` fixtures really are version `26.08.0.225` |
| T02 | `python3 -m py_compile` passes for `update_local_repo.py` and `configure_kde.py` |
| T03 | Both modules **import** cleanly on Debian (no `tqdm`, no `pip`) |
| T04 | The `tqdm` fallback is usable, not merely importable |
| T05 | The flat repo builds; `Packages` has exactly 2 stanzas at the right version |
| T06 | `apt-get update` exits 0 with no `E:`, no `Err:` and no warnings for the source |
| T07 | apt can *see* the package: correct candidate, correct origin, install resolves |
| T08 | Rebuilding twice is byte-identical and produces no duplicate stanzas |
| T09 | `sync_debian` prunes stale `.deb` files (version bump cannot leave two versions) |
| T10 | A corrupted index is rejected even with `trusted=yes` (control for T06/T07) |
| T11 | The production `local-citrix-repo.list` has the shape the harness verified |
| T12 | GPG `signed-by` path (design check; skips without a signing tool) |
| T13 | Fedora path unregressed: tracked files identical, `sync_fedora` command sequence identical |
| T14 | `bash -n` on every shell script the port adds |
| T15 | Nothing was left behind: no source file, no cached indexes, no installs, no `__pycache__` |
### The repo build it tests
The exact production sequence, on a copy of the real `.deb` files in a temp
directory:
```sh
cd "$repo"
apt-ftparchive packages . > Packages
gzip -c Packages > Packages.gz
apt-ftparchive release . > Release
```
and the exact production source line:
```
deb [trusted=yes] file:/var/local/citrix-repo ./
```
with the path substituted for the temp directory. A flat ("trivial") archive:
no `dists/` tree, suite `./`.
## What it does NOT test, and cannot
Being explicit matters more than the green summary.
1. **A real d-i install.** The harness never boots an installer. `debian/preseed.cfg`
is owned and validated by another change; this harness does not test it at all.
Note that `debconf-set-selections` validates line shape only - it silently accepts
an invented question name - so it is not evidence that directives exist.
2. **An actual GUI session.** Nothing here starts Plasma, and no test asserts that
`configure_kde.py` produces a working desktop. T03 proves it *imports*; whether
the touchpad and power settings take effect on a real session is untested.
`kwriteconfig6` is not installed here, so `configure_kde.KWRITE` is `None` and
every write would no-op. That path needs a real Plasma machine.
3. **The Citrix preinst/postinst maintainer scripts.** `apt-get install --simulate`
resolves dependencies; it does not run the package's scripts. Whether
`icaclient`'s postinst succeeds on a real machine is untested. This is the
single biggest gap: a dependency-resolvable package can still fail to configure.
4. **A real d-i/target filesystem for the repo path.** The harness builds the repo
in a temp directory, never at `/var/local/citrix-repo`. It asserts the
*shape* is identical (T11), not that the production path is writable in a
target environment.
5. **The network path.** The Gitea release API and the download code are not
exercised. T09 redirects the source files to a local directory, so
`download_file` is only exercised indirectly. A changed release asset name
would not be caught here.
6. **`apt-get update` inside a d-i chroot.** The preseed's `late_command` runs in
an `in-target` context where apt behaves differently (no `_apt` user, different
permissions). Untested.
7. **Fedora at runtime.** T13 compares source and command sequences; it does not
run `createrepo_c`/`dnf`/`rpm` on Fedora. The command sequence matching is
strong evidence but it is not an execution test. A Fedora 44 WSL distro exists
on the development machine and was not used.
## Two spec'd checks that cannot fail, and what replaced them
This is the most important thing in this file. Two checks that look like tests
are not tests.
### `apt-get update` exiting 0 with no `E:` lines
Measured on Debian 13: a repo whose `Packages` is **unreadable** produces
```
Err:4 file:/tmp/.../repo ./ Packages
Could not open file .../Packages - open (13: Permission denied)
```
and `apt-get update` still **exits 0 with no `E:` lines**. The same is true of a
repo with **no `Release` file at all**, and of a repo with **duplicate stanzas**.
So "exit 0 and no `E:`" passes on a broken repo.
The harness runs the spec'd check as T06 *and* the stronger check separately: no
`Err:` lines, no `W:` lines for that source, and then T07 requires apt to name the
exact version from that exact directory. T10 is the control that proves the
strong checks can fail: it corrupts `Packages` after `Release` was built and
asserts apt **rejects** it with a hash mismatch. Without T10, T06/T07 could be
passing vacuously.
### `git diff main -- ks.cfg`
`ks.cfg` is **not in the repository**. It is not in `main`, not in `debian-port`,
and `git log --all -- ks.cfg` is empty. It lives one level above the repo, in the
parent directory, untracked.
So `git diff main -- ks.cfg` exits 0 and prints nothing - because the path does
not exist on either side, not because the file is unchanged. The harness detects
this with `git cat-file -e main:ks.cfg` and reports it as **SKIP, explicitly
labelled VACUOUS**, rather than as a pass. It then prints the sha256 of the real
out-of-tree file so a change to it is at least visible.
## Line endings will fool you
This repo is checked out on Windows. Every tracked file in the working tree has
CRLF line endings; every blob in git has LF. A plain `git diff main` therefore
reports **all five files as completely rewritten**, including
`RPM-GPG-KEY-citrix-local` with 104 changed lines - the key itself is byte-identical.
The harness compares modulo CRLF (`tr -d '\r' | cmp`). If you see a huge diff,
check line endings before believing it.
## The apt index cache will fool you
`apt-cache policy` and `apt-get update` read cached indexes in
`/var/lib/apt/lists`. During development, a **wrong GPG key** appeared to be
accepted - `exit 0`, no `E:`, package still visible - purely because a good index
was cached from an earlier run.
Every case that must fail purges that repo's cached index files first
(`purge_apt_lists_for`). Any test that checks "can apt see the package" without
purging is testing the cache, not apt.
Related: `/tmp` is wiped between separate `wsl` invocations on this machine
(`systemd-tmpfiles`). Anything expected to survive across invocations must live
in `/root`.
## GPG signing: why `trusted=yes` is the right call
Production does not sign the Debian repo, and T12 exists to check that decision
rather than assume it. A stock trixie ships **no `gpg`** - only `/usr/bin/sqv`,
the Sequoia verifier that apt calls internally. So signing would add a `gpg`
dependency that Debian 13 does not have by default, in an installer environment
where new dependencies are the fragile thing.
The signing path was measured out of band (a throwaway key generated with Fedora
WSL's `gpg`, because Debian has none), with the apt cache purged between cases:
| Keyring | Result |
|---------|--------|
| armored `.asc`, correct key | exit 0, no `E:`, package visible |
| armored `.asc`, **wrong** key | exit 100, `E:`, `Missing key`, not visible |
| binary `.gpg`, correct key | exit 0, no `E:`, package visible |
| binary `.gpg`, **wrong** key | exit 100, `E:`, `Missing key`, not visible |
| `trusted=yes`, no signature | exit 0, no `E:`, package visible |
Two conclusions:
- `signed-by` **works correctly** on a flat `file:` repo on trixie, for both
keyring formats. It is not broken; it is simply not worth it here.
- `trusted=yes` does **not** mean "no integrity checking". T10 shows a tampered
`Packages` is rejected with `E: ... Hash Sum mismatch` regardless. Signing
would only add proof of *authorship*, which is meaningless for a repository the
machine builds from packages it just downloaded and verified itself.
T12 skips loudly when no signing tool is present, which is the normal case on a
stock trixie. Install `gpg` to make it run.
## Fixtures
The two real packages are expected next to the repo, not inside it:
```
LinuxISO/
icaclient_26.08.0.225_amd64.deb (256 MB)
ctxusb_26.08.0.225_amd64.deb (178 KB)
VDI-Linux/ <- the repo
debian/test/run-tests.sh <- this harness
```
Override with `DEB_DIR=/path/to/debs sudo -E bash debian/test/run-tests.sh`.
The 256 MB file is copied into a temp directory, which is fast on native
filesystem and slow off `/mnt/c`. If `/tmp` is small, set `TMPDIR` to somewhere
with ~600 MB free.
## Requirements
- Debian 13 (trixie), root.
- `apt-ftparchive`, `apt-get`, `apt-cache`, `dpkg-deb`, `python3`, `gzip` - all
present in a stock install.
- `git` **for T13 only**. It is not part of a stock trixie image; without it T13
skips and says so. Install it if you want the Fedora regression checks to run:
`apt-get install -y --no-install-recommends git`. Note this changes the test
machine, which is why the harness treats its absence as a skip rather than
installing it itself.
- `gpg` **for T12 only**, and only if you want to re-check the signing decision.
## Safety
The harness is designed to be safe to run on a machine you care about.
- It never writes to `/var/local/citrix-repo`. It records that directory's mtime
before the run and asserts it is unchanged in T15.
- It never installs anything. The only `apt-get install` is `--simulate`. T15
compares the installed package count before and after.
- It adds exactly one apt source file, `/etc/apt/sources.list.d/zz-vdi-test-$$.list`,
and removes it. T15 verifies the removal happened.
- It removes only the apt index files it created, matched by the encoded repo path,
never `/var/lib/apt/lists` wholesale.
- It removes any keyring it installed, matched by the `zz-vdi-test-*` prefix, and
only `rmdir`s `/etc/apt/keyrings` (which fails harmlessly if it was already there
with other keys in it).
- It never writes `__pycache__` into the repo: `PYTHONDONTWRITEBYTECODE=1` and
`PYTHONPYCACHEPREFIX` are set, and T15 asserts the repo is clean.
- All scratch work happens in one `mktemp -d` directory, removed at the end.
- A failing test does not abort the run, so you get the whole picture in one pass.
## Interpreting a failure
- **T05/T06/T07 failing together** - the repo build is broken. Look at T05 first.
- **T07 fails but T05 passes** - the repo is fine but apt cannot consume it; check
directory permissions (apt drops to `_apt`, so the repo path must be traversable).
- **T09 fails** - `sync_debian` is leaving old versions in the published
directory. On Debian, filenames carry the version, so copying without deleting
leaves every previous release indexed and makes rollback impossible.
- **T13 fails on the command sequence** - compare the printed `MAIN-CMDS` and
`FEDORA-CMDS` lists. Both sides are normalised to `<REPO>`; if they differ, the
Fedora path genuinely changed.
- **T15 fails on residue** - the teardown did not finish. Check the messages
immediately above it.