Skip to content

Commit 9f68457

Browse files
docs: make the runbook resume-ready after the standalone session
- ManualTests.md resume checklist: current batch-B guest state (64 ROM systems, all standalone emulators + BIOS/keys), BUG-14/15 committed but not redeployed, remaining work narrowed to the full 33-scenario pass, the two live re-verifications and the unexercised manual items; item 9 now states the tree is clean through d181805. - docs/gui-test-harness.md: harness file table gains vm-systems2.json/seed-batch2.py/fix-arrays.py/launch-one.py, the coverage map and the resume paragraph record the standalone session outcome. - docs/manual-tests.md: the Linux/macOS launch pipeline item now records the verified CHD->ISO conversions (byte-identical to chdman, temp ISO cleaned up, Xbox boots), the DOSBox temp conf, and the no-config-injection confirmation across the new emulator launches.
1 parent d181805 commit 9f68457

3 files changed

Lines changed: 44 additions & 30 deletions

File tree

‎ManualTests.md‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -834,7 +834,7 @@ up with official firmware; the **AI Parameter Suggestion** feature stays out of
834834

835835
### Resume checklist (next session)
836836

837-
**Guest state left by the 2026-09-26 session** (all of this survives a host/VM reboot unless noted):
837+
**Guest state left by the 2026-09-27 standalone session** (all of this survives a host/VM reboot unless noted):
838838

839839
- VM `LinuxMint` running (or start it with `Start-VM LinuxMint`, elevated); guest IP is
840840
`172.31.176.191` (the Default Switch subnet reverted from `192.168.65.x` back to `172.31.x` at this
@@ -844,18 +844,20 @@ up with official firmware; the **AI Parameter Suggestion** feature stays out of
844844
`SimpleLauncher.Avalonia.dll` md5 `68d6f222edcfd0375dcf0ee18ca1bbec`); after the standalone session
845845
the app runs the **batch B** fixture (base 4 + PS1, PS2, PS3, Dreamcast, Saturn, WiiU, 3DS, PSP,
846846
Xbox, DOS, Model 3, FDS, Atari ST), no `-debug`, list view, window maximized by the harness. The
847-
BUG-14/15 fixes are in the working tree but **not deployed to the VM** (rebuild+redeploy if they
848-
need live verification). The Avalonia (686/686) and WPF (2122/2122) suites are green on the
849-
current working tree; everything through the MAME session is pushed (`aa87e469`..`693d7c68`), the
850-
BUG-13..15 fixes, the harness helpers and the session docs are uncommitted at stop time (item 9).
847+
BUG-14/15 fixes are committed but **not deployed to the VM** (rebuild+redeploy if they need live
848+
verification; the DOSBox item accessible name and the batch-exit log level were verified from the
849+
source/suites, not re-run on the VM). The Avalonia (686/686) and WPF (2122/2122) suites are green
850+
on the current working tree and everything is pushed through `d1818050` (item 9).
851851
- Emulator sweep session artifacts on the guest: RetroArch 1.22.2 + 491 cores under
852852
`~/SimpleLauncher/emulators/RetroArch/RetroArch-Linux-x86_64/`, OpenMSX 21.0 under
853-
`~/SimpleLauncher/emulators/OpenMSX/`, real ROMs for 36 systems under `~/roms/` (873 MB from
854-
`G:\`), per-system image folders under `~/images/`, `vm-systems.json` + `seed-batch.py` in
855-
`/home/vm/vision/`. Bundled Linux tools (`tools/SevenZip/7zz`,
856-
`tools/RetroAchievementsSharp/RetroAchievementsSharp`) were `chmod +x`-ed after SCP deploy.
857-
`settings.dat` has the RA username/API key/password configured (`petersonfernandes`) - the API key
858-
is **not** in this repo; re-enter it if the settings are wiped.
853+
`~/SimpleLauncher/emulators/OpenMSX/`, real ROMs for 64 systems under `~/roms/` (~3.9 GB from
854+
`G:\` + `E:/F:/I:/J:`), per-system image folders under `~/images/`, and in `/home/vm/vision/`:
855+
`vm-systems.json` + `seed-batch.py` (first sweep) and `vm-systems2.json` + `seed-batch2.py` +
856+
`fix-arrays.py` + `launch-one.py` (standalone session). Bundled Linux tools
857+
(`tools/SevenZip/7zz`, `tools/RetroAchievementsSharp/RetroAchievementsSharp`) were `chmod +x`-ed
858+
after SCP deploy. `settings.dat` has the RA username/API key/password configured
859+
(`petersonfernandes`) - the API key is **not** in this repo; re-enter it if the settings are
860+
wiped.
859861
- RetroAchievements: the account is the user's `petersonfernandes` (password + Web API key supplied
860862
by the user in chat; **not stored in this repo**). The VM's `settings.dat` currently holds them;
861863
ask the user again if the settings are wiped.
@@ -904,21 +906,18 @@ up with official firmware; the **AI Parameter Suggestion** feature stays out of
904906
linux-x64 --self-contained true -o D:\payload\linux-x64-annot`, then `Stop-VmApp`, SCP
905907
`SimpleLauncher.Core.dll` + `SimpleLauncher.Avalonia.dll` to `/home/vm/SimpleLauncher`, `Start-VmApp`.
906908
6. Remaining work (see open items): the full 33-scenario pass (31/31 on 2026-09-26 + MAME-01/02
907-
verified individually 2026-09-27), real-ROM launches for the other emulators, the successful Edit
908-
System save path, and the other unexercised items in open item 4. The WPF and Avalonia suites are
909-
green as of 2026-09-27.
909+
verified individually 2026-09-27; not re-run since), the successful Edit System save path, the
910+
unexercised items in open item 4, and the two live-verifications for BUG-14/15 after redeploying
911+
the payload. Real-ROM launches are done for 14 systems with 10 booting games; PS3/Vita/64DD/FDS/
912+
X68000/Model 3 are blocked by image/format/data issues (see the standalone session section).
913+
The WPF and Avalonia suites are green as of 2026-09-27.
910914
7. Run subsets while iterating and finally the full suite; on failures read the newest
911915
`reports\run-*.md` first (deterministic JSON + vision answer).
912916
8. Keep this section (and the AGENTS.md pointer) updated after every session; attach the report path
913917
and the coverage delta against `docs/manual-tests.md`.
914-
9. **Uncommitted work at stop time** (do not lose it): the **BUG-14 fix** (batch/exec exit logging
915-
now `Information` in `SimpleLauncher.Avalonia/Services/GameLauncher/LauncherService.cs` and
916-
`SimpleLauncher/Services/GameLauncher/GameLauncherService.cs`), the **BUG-15 fix**
917-
(`SimpleLauncher.Core/Models/DosBoxFileItem.cs` `ToString()`), the new harness helpers
918-
(`scripts/gui-test-harness/seed-batch2.py`, `fix-arrays.py`, `vm-systems2.json`,
919-
`launch-one.py`) and the session docs (`ManualTests.md`, `docs/manual-tests.md`,
920-
`docs/gui-test-harness.md`). Everything through the emulator-matrix session is pushed
921-
(`aa87e469`..`b9f9d157`, including the BUG-13 fix in `35f0c8b0`).
918+
9. **Nothing is uncommitted at stop time.** Everything is pushed through `d1818050`: BUG-07..15
919+
(`aa87e469`..`a22d4d32`), the two emulator fixtures and their session docs (`b9f9d157`,
920+
`d1818050`). Working tree clean; `dotnet test` green for both suites.
922921

923922
## 7. Cost
924923

‎docs/gui-test-harness.md‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,9 @@ tar -czf D:\payload\payload-annot.tar.gz -C D:\payload\linux-x64-annot .
113113
| `atspi_nav.py` | AT-SPI navigation library (deployed to `/home/vm/vision/`); `Nav` class + `Entry`; also a CLI (`tree`, `ready`, `dump`, `selftest`) | ~23 KB |
114114
| `fixture.py` | Seeds/clears the guest unified DB and files (deployed to `/home/vm/vision/`); commands `seed`, `arcade`, `empty`, `clean-state`, `dump` | ~8 KB |
115115
| `ask_vision.py` | One-shot OpenRouter vision call: `python ask_vision.py <png> "<prompt>" [--model M] [--max-tokens N] [--temperature T]`; reads `OPENROUTER_API_KEY`; prints the model text plus a `--- usage ---` JSON line | ~3 KB |
116+
| `vm-systems.json` + `seed-batch.py` | First emulator-matrix fixture (36 Easy-Mode systems, manifest emulator configs); `seed-batch.py <names...>` keeps the base systems + the requested batch | ~30 KB |
117+
| `vm-systems2.json` + `seed-batch2.py` | Standalone/CD fixture (25 manifest systems: PS1/PS2/PS3/DC/Saturn/WiiU/3DS/PSP/Xbox/DOS/Model 3/...); same batch semantics, adds `fix-arrays.py` to normalize scalar format strings the strict deserializer skips | ~20 KB |
118+
| `launch-one.py` | App-driven single-system launch (`launch-one.py <System> "<Game>" [wait]`): maximize, open system, letter bar, AT-SPI card right-click (coordinates fallback), DOSBox picker handling, window/process evidence, screenshot, cleanup — run one system per fresh app start | ~4 KB |
116119

117120
The scripts resolve their own locations from `$PSScriptRoot`, so the checkout can live anywhere.
118121
Only the guest-side paths (§4) and the VM IP/credentials need adapting. `shots\` and `reports\` are
@@ -444,8 +447,13 @@ login/hashing, gamepad hardware, CHD/ISO/XISO mounting, external tools, updater,
444447
and anything needing real network/emulators. The emulator sweep session on 2026-09-27 replaced the
445448
"real-ROM launches" gap with a full matrix: 36 systems seeded from the Easy Mode manifest, 29
446449
distinct emulators/cores launched through the UI with real ROMs, and the RetroAchievements settings
447-
login, profile page, per-game window and local CLI hashing verified live (see section 15 and the
448-
session notes in `ManualTests.md`). Easy Mode downloads were swept manually on 2026-09-26:
450+
login, profile page, per-game window and local CLI hashing verified live. A follow-up session the
451+
same day seeded 25 more systems from the user's `E:/F:/G:/I:/J:` collections and launched the
452+
standalone emulators: PS1/DuckStation, PS2/PCSX2, Dreamcast/Redream, Saturn/Ymir, WiiU/Cemu,
453+
3DS/Azahar, PSP/PPSSPP, Xbox/xemu, DOS/DOSBox Staging and Atari ST/Hatari booted real games, the
454+
DOSBox file picker was exercised, and the app's CHD→ISO conversion proved byte-identical to
455+
`chdman extractdvd`; PS3/RPCS3, FDS/mesen, N64DD/mupen64plus-next and X68000/px68k are blocked by
456+
image/format/data issues (see section 15 and the session notes in `ManualTests.md`). Easy Mode downloads were swept manually on 2026-09-26:
449457
**15/15 distinct emulator downloads and the shared RetroArch core install correctly** (after fixing
450458
BUG-03 `.tar.gz`, BUG-04 zip execute bits, BUG-05 `.tar.xz` and BUG-06 solid-7z extraction
451459
performance) — see `ManualTests.md` §6 "Easy Mode emulator/core install sweep" and §8. The Easy Mode
@@ -463,12 +471,19 @@ machine-description surfaces (list view, Game Details, Global Search "MAME Descr
463471
Favorites/Play History columns), the MAME sort toggle, a real `history.dat` entry, the `mame.dat`
464472
missing/corrupt paths and the GroupByFolder warning; MAME-01/MAME-02 automate the descriptions/sort
465473
and the real history entry, the rest stays ad-hoc (findings in `ManualTests.md` §6 open items).
466-
Update `docs/manual-tests.md` checkboxes only for items the suite actually verified.
474+
Two further sessions on 2026-09-27 used the user's ROM collections: an emulator sweep (`G:\`, 36
475+
systems, 29 RetroArch cores/emulators with real ROMs) and a standalone/BIOS session (`E:/F:/G:/I:/J:`,
476+
25 systems seeded; PS1/PS2/Dreamcast/Saturn/WiiU/3DS/PSP/Xbox/DOS/Atari ST launched with real games,
477+
Cemu/xemu/PCSX2 requiring their own data-dir fixes, RPCS3 rejecting the collection's ISO9660 images,
478+
and the DOSBox file picker exercised — see `ManualTests.md` and §15). BUG-13..15 were found and
479+
fixed. Update `docs/manual-tests.md` checkboxes only for items the suite actually verified.
467480

468481
**To resume this work later, follow `ManualTests.md` → "Resume checklist (next session)"**: it lists
469-
the VM/app state left behind, the console/screensaver recovery steps, how to rebuild+deploy the
470-
Avalonia payload, the remaining work (full 31-scenario pass, WPF suite re-run, real-ROM launches for
471-
the newly installed emulators) and the uncommitted files from the session.
482+
the VM/app state left behind (app on the batch-B fixture, all standalone emulators + BIOS/keys
483+
installed), the console/screensaver recovery steps, how to rebuild+deploy the Avalonia payload, the
484+
remaining work (full 33-scenario pass, the two BUG-14/15 live re-verifications after redeploy, the
485+
still-unexercised manual items) and confirms the working tree is clean (everything pushed through
486+
`d1818050`).
472487

473488
---
474489

‎docs/manual-tests.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ Common flow for **each** emulator:
119119
- [ ] Add a real ROM + point the launcher at a real emulator install; launch with "Show settings before launch" **off** → the emulator's own config file is rewritten with SimpleLauncher's settings and the game boots.
120120
- [ ] Launch with "Show settings before launch" **on** → the injection dialog appears; "Run" launches, "Cancel" does not launch.
121121
- [ ] Wrong/missing emulator path → the game still attempts launch without crashing; check the Debug log for injection errors.
122-
- [X] **Linux/macOS (Avalonia)** — the handlers are not registered and the "Inject emulator config" menu is hidden: launching any game writes no Windows-style config and opens no injection dialog (LB-08); check that no files appear under `~/Documents` or next to the emulator binary. (Verified 2026-09-26: launched real PSP/PPSSPP and Dreamcast/Redream games; no injection dialog, no Windows-style config next to the emulator binaries.)
122+
- [X] **Linux/macOS (Avalonia)** — the handlers are not registered and the "Inject emulator config" menu is hidden: launching any game writes no Windows-style config and opens no injection dialog (LB-08); check that no files appear under `~/Documents` or next to the emulator binary. (Verified 2026-09-26: launched real PSP/PPSSPP and Dreamcast/Redream games; no injection dialog, no Windows-style config next to the emulator binaries. Re-confirmed 2026-09-27 across DuckStation/PCSX2/RPCS3/Redream/Ymir/Azahar/Cemu/xemu/PPSSPP/DOSBox/Supermodel launches — the app only passes the ROM path/parameters; every emulator's config was the one prepared by hand for its Linux data dir.)
123123

124124
Per-emulator specifics:
125125
- [ ] **Ares** — config applied; dialog cancel aborts.
@@ -180,7 +180,7 @@ Shared flow per emulator (sample 3–4 in depth, then spot-check the rest):
180180
- [ ] **ISO mount** (`MountIsoFiles`) — PS3 ISO with `EBOOT.BIN` launches and the drive is dismounted after exit; ISO without EBOOT.BIN → error box + dismount; PowerShell execution-policy restricted → `UnabletomountIsOfile` box; 30 s timeout kill.
181181
- [ ] **XISO mount** (`MountXisoDrive`, `MountXisoFiles`) — original-Xbox XISO launches via Dokan; virtual drive letter (picked Z→D) is released after exit; missing `tools\SimpleXisoDrive\*.exe` → mount-error box; no free drive letter → error box; wrong XISO layout → timeout + error, no leaked process.
182182
- [ ] **External tools** (`ExternalToolLauncherService`) — run each tool from the UI: Create Batch Files (PS3/ScummVM/Windows/Xbox 360 XBLA), Batch Convert ISO→XISO, →CHD, →Compressed, →RVZ, Rom Validator, Find Rom Cover, Retro Game Cover Downloader — launches with correct folder/args; missing tool → "not found" box; UAC cancel (error 1223) → "canceled" box; corrupt exe → PE check rejects it.
183-
- [ ] **Linux/macOS launch pipeline (Avalonia)** — ZIP/7Z/RAR for ScummVM/RPCS3/XBLA extract to `%TEMP%/SimpleLauncher/ZipLaunch/<guid>` (upper-case ROM/EXE names found, Windows-authored `DIR\FILE.BIN` entries land in a real subfolder) and the temp folder is deleted after exit; a `.chd` for a non-DOSBox system is converted with CHDSharp and every temp file (including multi-track bins) is cleaned up (LB-19); a DOSBox `.iso`/`.chd` is `imgmount`ed directly or converted, with the temp conf deleted after exit; a mount service path on Linux logs a single Information-level "not supported on this platform" (no Warning, no bug report — LB-14); the `7zz` fallback extracts a broken 7z from a Debug build without a manual `chmod +x` (LB-15).
183+
- [ ] **Linux/macOS launch pipeline (Avalonia)** — ZIP/7Z/RAR for ScummVM/RPCS3/XBLA extract to `%TEMP%/SimpleLauncher/ZipLaunch/<guid>` (upper-case ROM/EXE names found, Windows-authored `DIR\FILE.BIN` entries land in a real subfolder) and the temp folder is deleted after exit; a `.chd` for a non-DOSBox system is converted with CHDSharp and every temp file (including multi-track bins) is cleaned up (LB-19); a DOSBox `.iso`/`.chd` is `imgmount`ed directly or converted, with the temp conf deleted after exit; a mount service path on Linux logs a single Information-level "not supported on this platform" (no Warning, no bug report — LB-14); the `7zz` fallback extracts a broken 7z from a Debug build without a manual `chmod +x` (LB-15). (Partially verified 2026-09-27 on Linux Mint 22.3: PS3 and Xbox `.chd` ROMs were converted to temp ISOs in `/tmp/SimpleLauncher/<guid>.iso` and handed to RPCS3/xemu, and the temp ISO was gone after the app exit; the app's conversion of the PS3 CHD is **byte-identical to `chdman extractdvd`** (`cmp`), and the Xbox ISO booted in xemu; a DOSBox game extracted from its zip produced a temp `_simplelauncher_dosbox.conf` and booted. The ZIP-mount paths, multi-track bins, LB-14 logging and LB-15 `7zz` case were not exercised here.)
184184

185185
## 8. Game file watcher (5.6.0) — end-to-end flow
186186

0 commit comments

Comments
 (0)