Add GPU startup visual test gate

2026-05-19 10:23:22 -07:00
parent de02b20786
commit 11a13042b6
5 changed files with 191 additions and 2 deletions
@@ -0,0 +1,71 @@
+# Packaged Client GPU Startup Visual Test
+
+This test validates the packaged Windows investor demo through the real GPU
+desktop path. Do not use QEMU guest-agent screenshots for this gate; they are
+useful for administration but cannot prove that the interactive rendered
+desktop is visible, focused, or readable.
+
+## Purpose
+
+Run this before calling an investor package visually ready. The test is meant
+to catch the problems that headless automation misses: black screens, unfocused
+menus, mouse capture problems, startup credits appearing under gameplay, missing
+foliage or terrain visuals, and pause/save/quit menu confusion.
+
+## Required Path
+
+- Windows build VM with the packaged demo in `Builds\WindowsDevelopment`.
+- Sunshine running on the Windows build VM.
+- Moonlight connected to the Windows build VM desktop from a real viewing
+  client.
+- The packaged demo launched from the investor launcher, preferably
+  `Start Agrarian Demo - DX12.cmd`; use the compatibility launcher only when
+  validating fallback rendering.
+
+## Capture Set
+
+Save screenshots or a short clip under:
+
+`Saved\VisualQA\GpuStartup\<YYYYMMDD-HHMM>\`
+
+Required evidence:
+
+- `01-startup-credits` - cinematic credits are full-screen and no gameplay
+  interaction appears active underneath.
+- `02-character-selection` - the UMG character selection segment is readable,
+  clickable, and focused.
+- `03-server-join` - the server/join segment is readable and separate from the
+  character segment.
+- `04-loading` - the loading segment is readable and does not show accidental
+  gameplay input.
+- `05-first-spawn` - first playable view after closing the frontend.
+- `06-pause-menu` - Escape opens the pause menu, mouse cursor is visible, and
+  gameplay is blocked.
+- `07-save-quit` - Save & Quit shows the saving segment before closing.
+
+Create `visual-startup-check.txt` in the capture folder with:
+
+- package path;
+- launcher used;
+- capture method, normally Sunshine plus Moonlight;
+- tester name;
+- pass/fail result;
+- notes on visible defects.
+
+## Windows Helper
+
+Run this from the Windows project checkout before the capture session:
+
+```bat
+Scripts\RunWindowsGpuStartupVisualCheck.bat --check-tools
+```
+
+To print the full capture checklist:
+
+```bat
+Scripts\RunWindowsGpuStartupVisualCheck.bat
+```
+
+This helper intentionally does not accept QEMU guest-agent screenshot evidence.
+It verifies the packaged demo path and Sunshine service, then tells the tester
+what real-GPU startup captures to collect.
@@ -40,6 +40,11 @@ Keep these LAN-only. Do not expose Sunshine directly to the public internet.

 Codex should continue using the headless build/control path for normal code, cook, package, and commandlet work. Use Sunshine only when a visual inspection is actually needed.

+For packaged investor-demo startup validation, use the dedicated checklist in
+`Docs/Ops/PackagedClientGpuStartupVisualTest.md` and run
+`Scripts\RunWindowsGpuStartupVisualCheck.bat --check-tools` on the Windows
+builder before capturing through Moonlight.
+
 ## Verification

 The setup was validated by:
@@ -59,4 +64,3 @@ The GTX 1660 SUPER does not support AV1 NVENC. Sunshine may log an AV1 encoder f
 - If Moonlight shows a black screen after using RDP, disconnect RDP, restart `SunshineService`, and reconnect through Moonlight.
 - If controller input is required later, install and validate the ViGEmBus gamepad driver. It is not required for visual inspection.
 - If Unreal rendering differs under RDP, use Moonlight before changing graphics settings.
-