latchd/docs/e2e-testing.md

End-to-end testing

Latchd has two test layers:

• make integration-test builds the binary and exercises metadata, TOML validation, preflight, and the non-authenticating preview path. It does not need PAM credentials, root, a VT, X11, or Wayland.
• make pam-fixture-test installs unique temporary PAM services only when run as root, executes authentication/password-change fault tests and the session metadata/environment handoff tests, then removes the services on exit. Non-root runs report SKIP.
• make system-e2e probes the host for PAM, faillock, VT, X11, Wayland, and systemd-logind capabilities. Missing capabilities are reported as SKIP, never as a successful test. Use make system-e2e-strict only in a prepared VM or privileged runner; strict mode fails when a capability is unavailable.

The Docker test image runs the first layer and starts an isolated Xvfb server when available. It does not use host display sockets, host PAM files, or a host VT. The password-change path is covered by FFI/conversation tests in the container, but a real PAM password rotation and login handoff require a disposable VM with a dedicated test account and an explicitly provisioned PAM policy. The container probe intentionally reports those checks as capability information only.

For a local release-style run:

make integration-test
make pam-fixture-test
make docker-test
make system-e2e

The preview interface is documented in ui.md. Its screenshots come from a Docker PTY and do not represent a host VT or compositor.

For a VM with a real seat, compositor, and logind:

make system-e2e-strict

Do not run strict mode on a normal developer workstation unless the VM's display-manager handoff and test PAM policy are isolated from the host.