refactor: split the TUI and refresh project docs
Move login state, authentication, discovery, input, rendering, and tests into focused TUI modules. Add detailed CLI error reports with recovery commands, align the build and host-check documentation, and keep the legacy Go tree outside normal builds. Checks: make check; make integration-test; go test ./... (legacy/go).
This commit is contained in:
@@ -1,43 +1,85 @@
|
||||
# End-to-end testing
|
||||
# End-to-end checks
|
||||
|
||||
Latchd has two test layers:
|
||||
Latchd has checks for a development host, the Docker image, and a disposable VM.
|
||||
|
||||
* `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.
|
||||
## Check matrix
|
||||
|
||||
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.
|
||||
| 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 |
|
||||
|
||||
For a local release-style run:
|
||||
Run the local set with:
|
||||
|
||||
```sh
|
||||
make check
|
||||
make integration-test
|
||||
make pam-fixture-test
|
||||
make docker-test
|
||||
make system-e2e
|
||||
```
|
||||
|
||||
The preview interface is documented in [`ui.md`](ui.md). Its screenshots come from a Docker PTY and do not represent a host VT or compositor.
|
||||
## Docker
|
||||
|
||||
For a VM with a real seat, compositor, and logind:
|
||||
`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:
|
||||
|
||||
```sh
|
||||
docker image rm latchd-test:local
|
||||
```
|
||||
|
||||
The UI screenshots use a Docker PTY and preview mode.
|
||||
|
||||
## PAM fixture
|
||||
|
||||
Run the fixture as root:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
make build
|
||||
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.
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user