docs: document pkh test

Add the DEP-8 runner to the command list and a usage section: default
chroot testbed sharing the deb tarball cache, binary reuse from pkh deb
with in-process rebuilds, the local and vm modes, and the 0/1/2 exit
contract. autopkgtest joins the shell-out list (vm mode) and the
roadmap bullet comes off — the feature exists.

README.md

@@ -22,8 +22,8 @@ cargo install --path .
 ```
 
 At runtime pkh shells out to the Debian packaging toolchain (git,
-dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, ...): install the
-ones your workflows use, or build the classic snap from
+dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, autopkgtest, ...):
+install the ones your workflows use, or build the classic snap from
 `snap/snapcraft.yaml` (`snapcraft pack`), which carries them.
 
 ## Usage and features
@@ -55,6 +55,7 @@ Commands:
   build  Build the source package (into a .dsc)
   put    Upload the built source package to a PPA
   deb    Build the source package into binary package (.deb)
+  test   Run the package's DEP-8 as-installed tests (autopkgtests)
   lint   Lint the package (lintian wrapper + pkh-native checks)
   prune  Prune residual pkh build artifacts and caches
   help   Print this message or the help of the given subcommand(s)
@@ -133,11 +134,38 @@ A plain `pkh deb` never reuses a session — everything is rechecked from
 scratch — and it replaces the session of its target. `pkh deb --resume`
 refuses to adopt a session built for a different series/architecture.
 
+### Running the DEP-8 tests
+
+`pkh test` runs the package's as-installed tests (`debian/tests/control`,
+declared by `Testsuite: autopkgtest` in `debian/control`) through a
+native runner on a pkh testbed, and reports one verdict per test:
+
+```
+pkh test                 # test this tree: builds it first if needed
+pkh test --mode local    # on the current context, no isolation
+pkh test --mode vm --image img.qcow2   # in a VM, via autopkgtest
+pkh test --json --fail-on skip         # CI-shaped
+pkh test --list-tests    # what does this package test?
+```
+
+By default the tests run in an ephemeral unshare chroot bootstrapped
+from the same cached tarballs as `pkh deb`, against the binaries pkh deb
+just built next to the tree (stale or missing output is rebuilt first;
+`--no-build` refuses, `--debs` overrides). Pockets and PPAs resolve test
+dependencies like in `pkh deb` (`-p`, `--ppa`), and `--test-name`,
+`--skip-test`, `--shell-fail` and `--setup-commands` cover the day-to-day
+debugging loop. Tests needing a real machine (`isolation-machine`,
+`needs-reboot`) run only in `--mode vm`, which execs the installed
+`autopkgtest` with its qemu runner.
+
+Exit codes: 0 all tests passed (skips and flaky allowed), 1 at least one
+test failed (or a `--fail-on` trigger), 2 runtime errors (no declared
+tests, no usable testbed, ...).
+
 ## Future improvement ideas
 
 - pull: try to fetch the correct git branch for series on Debian
 - deb: asynchronous build, detachable and monitorable
 - put: allow uploads to Debian or Ubuntu archives
-- test: add 'pkh test' to run autopkgtests
 - pull: cache Sources.gz files to improve speed
 - pull: 'pkh pull' in a package tree should git pull and re-fetch orig tgz