From 27dec5ab4a42b42751716644c348a7d81ab7e094 Mon Sep 17 00:00:00 2001
From: michael <operations@dangerousthings.com>
Date: Mon, 27 Apr 2026 09:26:17 -0700
Subject: [PATCH] docs(gui): smoke-test recipe and CI gate

---
 gui/TESTING.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 gui/TESTING.md

diff --git a/gui/TESTING.md b/gui/TESTING.md
new file mode 100644
index 0000000..f2e6ffc
--- /dev/null
+++ b/gui/TESTING.md
@@ -0,0 +1,47 @@
+# Testing the AuthForge GUI
+
+## Automated gate
+
+```bash
+cargo build -p authforge-gui
+cargo clippy -p authforge-gui --all-targets -- -D warnings
+cargo test -p authforge-gui            # 4 error-classifier tests
+```
+
+CI runs all three on every push (libgtk-4-dev / libadwaita-1-dev are
+installed in the workflow image).
+
+The GUI requires libadwaita 1.5 (Ubuntu 24.04+) for `adw::AlertDialog` and
+the v1_5 feature gate enabled in `gui/Cargo.toml`. Older distros need the
+plan's MessageDialog fallback (not implemented in v1).
+
+## Manual smoke
+
+Requires a USB FIDO2 device (Yubikey 5, Solo, etc.) and a built daemon.
+
+```bash
+# Terminal 1 — daemon (permissive polkit so you don't get prompted).
+AUTHFORGE_POLKIT_BYPASS=1 \
+  AUTHFORGE_POLICY_DIR=/tmp/af/policy.d \
+  AUTHFORGE_PENDING_DIR=/tmp/af/pending \
+  AUTHFORGE_USERDB=/tmp/af/users.db \
+  target/release/authforged
+
+# Terminal 2 — GUI.
+target/release/authforge
+```
+
+Walk-through:
+
+1. Window opens, Keys tab visible. Empty list with hint text "No keys
+   enrolled yet."
+2. Click "Enroll a new key" → modal opens with spinner + "Touch your
+   security key now". Touch the device.
+3. Modal closes, the list re-renders with one row showing the key's
+   short id.
+4. Click the trash icon on the row → row vanishes immediately.
+5. Pull the security key, click Enroll → modal opens, swaps to error
+   text ("authenticator: no FIDO2 device found") with a Close button.
+6. Kill the daemon (`pkill authforged`), click Enroll → toast appears
+   with the disconnected message; Retry on the page reconnects after
+   restart.