latchd/docs/e2e-testing.md

End-to-end checks

Latchd has checks for a development host, the Docker image, and a disposable VM.

Check matrix

Command	What it covers	Requirement
make check	formatting, Rust tests, Clippy, and rustdoc	Rust toolchain and PAM development files
make integration-test	release CLI, configuration validation, preflight, and preview paths	local build
make docker-test	release build, CLI checks, Xvfb, capability probe, and PAM fixture	Docker
make pam-fixture-test	denied login, password change, session metadata, and returned environment	root for temporary /etc/pam.d/ files
make system-e2e	PAM library, faillock, VT device, X11, Wayland socket, and logind seat	host capabilities
make system-e2e-strict	all host capability checks	prepared VM

Run the local set with:

make check
make integration-test
make docker-test
make system-e2e

Docker

Dockerfile.test installs Rust 1.88, the PAM development files, Xvfb, and xauth, then runs the release checks inside the image.

Use a disposable VM for VT, compositor, and systemd-logind checks.

The Docker test keeps the image as latchd-test:local. Remove it after the run when required:

docker image rm latchd-test:local

The UI screenshots use a Docker PTY and preview mode.

PAM fixture

Run the fixture as root:

sudo make pam-fixture-test

The script creates temporary service names below /etc/pam.d/, builds a small session module, runs the Rust fixture tests, and removes the temporary files after the run.

The fixture checks these handoffs:

• a denied authentication returns an error;
• an expired password enters the password-change path;
• the selected TTY, session type, desktop, seat, and VT reach the session stack;
• session values returned by the module reach the child environment.

Host capability probe

Use make system-e2e to inspect host capabilities.

The probe checks /dev/tty0, Xvfb, a Wayland socket, the PAM library, faillock, /etc/pam.d/latchd, and systemd-logind.

Strict VM check

Prepare a disposable VM with:

• the latchd binary and /etc/latchd/config.toml;
• a test account and /etc/pam.d/latchd configured for it;
• a real virtual terminal and an available seat0;
• systemd-logind;
• the X11 or Wayland stack under test;
• the desktop files and executables named by the config.

Build the binary, then run:

make build
make system-e2e-strict

Reading failures

• configuration errors point to a value or ownership check; run --preview --show-config to isolate it
• session errors point to a desktop entry, executable, home directory, X11 server, or child process; run --preview --no-tui and read the client log
• PAM errors point to account or service setup; check /etc/pam.d/latchd and the service journal
• terminal errors mean the process lacks a controlling terminal; use preview mode for non-interactive checks