vamos: tests before the HDF spins up

What we are automating (so the tests make sense)

Games on the second drive are usually WHDLoad slaves: a folder per title with a *.slave file WHDLoad launches instead of a floppy. You can copy a finished pack from the community archive. When you only own the original ADFs, WHDLoad’s official Install drawer on whdload.de contains a small AmigaDOS script. For many titles that script’s “version 0” step means: run RawDIC with an .islave recipe and read tracks from DF0: until the game’s data files exist on the hard disk. Our catalog marks those titles rawdic_batch.

The live pipeline on quo (install WinUAE + startInstallAmiga.sh) roughly looks like this:

1. Catalog — games/whdload-catalog.json lists each game, ADF paths, and install drawer location under build/whdload-installs/.
2. Plan — whdload_install_plan.py resolves host paths and Amiga paths (Source:…, WHDLoad:UserTools/<prefix>) and picks a backend: prebuilt copy, host file copy, guest batch installer, or RawDIC.
3. Engine — whdload_install_engine.py routes the plan. For RawDIC it calls guest_whdload_rawdic.run_rawdic_batch(). --dry-run --json prints the exact rawdic_body without launching UAE.
4. Shell entry points — install_whdload_games.sh and install_whdload_live.sh wrap the engine for one game or a batch, with optional skip-launch for planning only.
5. Guest driver — guest_whdload_rawdic.py does the work AmiPilot cannot infer: host_prepare() copies .islave into the host mirror of the install folder; floppy_insert.py pushes the first ADF into UAE’s floppy0 via the WinUAE pipe; run_rawdic_guest() assigns WHDLoad: / Source:, uploads SYS:T/whdload-<prefix>.cmd, and Executes it; drive_rawdic_gui() polls the RawDIC window and clicks Start (unless headless Auto — see the RawDIC-Auto note); host_finalize() copies resulting *.slave and icons into build/WHDLoad-games/UserTools/.
6. Cmd text (shared) — whdload_guest_cmd.py builds the script body in one place so tests and the guest agree. Example for version 0:

CD WHDLoad:UserTools/KillingGameShow
C:RawDIC SLAVE=KillingGameShow.islave SOURCE=DF0:

That two-liner is what tier-one unit tests lock. Tier-two vamos runs the C:RawDIC … line against a real m68k binary with host directories mapped to the same volume names — still without booting the acceptance HDF.

What vamos is (and is not)

vamos comes from amitools. People call it “Wine for Amiga”: it traps Exec and DOS library calls and runs a 68000 executable on your CPU. You pass host paths as Amiga volumes (-V WHDLoad:/tmp/…, -V C:/tmp/c) and invoke the binary with the same arguments Workbench would use on the command line.

It is not WinUAE. There is no emulated Paula chip reading a floppy, no trackdisk.device, no Intuition window server, no RTG. RawDIC inside vamos can parse arguments and maybe open files; it cannot complete a WHDLoad install, because imaging is precisely “read these tracks from DF0 (or from an ADF via TrackWarp) and write Disk.* files according to the .islave.” That is why our integration tests treat “imaging finished” as a failure if it ever happened under vamos — it would mean the test was lying.

Four layers of “Amiga correct”

Tier	What runs	What it proves about the scripts above
1 — Host unit	python -m unittest on Mac/Linux CI	Catalog → plan → rawdic_body; path algebra; artifact scans on fixture trees
2 — vamos	test_vamos_rawdic.sh, vamos_rawdic_spike.py	Same argv and volume layout as guest; hunk sanity on .islave; live run proves RawDIC cannot image here
3 — Emulator smoke	fs_uae_integration_smoke.sh	Config + HDF + ROM present; boot path exists
4 — AmiPilot guest	install_whdload_live.sh on quo	DF0 insert, RawDIC GUI or Auto, *.slave on disk, acceptance JSON

Tier one runs on every push to amiga-utils. Tier two is one maintainer command after the venv is created. Tiers three and four need ROMs, hardfiles, and the RDP session described in puppeteer.

Scripts vamos tests exercise

These are the pieces wired together; vamos touches the bold rows most directly.

Script / module	Role	vamos relationship
whdload_guest_cmd.py	Builds SYS:T/whdload-*.cmd text; reads WHDLOAD_RAWDIC* env for Auto/headless/INPUT	Unit + layout tests assert HEADLESS and SLAVE lines; spike writes planned.cmd beside the run
whdload_install_plan.py	Turns catalog entries into InstallPlan (prefix, ADF list, dest paths, backend)	Spike uses fixture catalog (KGS = rawdic_batch)
vamos_rawdic_spike.py	Maps host dirs to WHDLoad:/Source:/C:, runs stock or Auto argv under vamos, classifies log	Main probe; documents vamos_silent_exit vs path errors
test_vamos_rawdic.sh	Creates .venv-vamos312, installs git amitools + greenlet, optional WHDLoad_dev RawDIC fetch, runs unittest	Entry point for tier two
guest_whdload_rawdic.py	Full guest orchestration (AmiPilot + pipe + GUI poll)	Not run under vamos; cmd body must match what vamos tested
validate_whdload_artifacts.py	Checks an install folder for slaves, icons, expected names	Host-only; complements vamos (structure after a real install)

Fixture catalog: CI uses tests/fixtures/whdload-repo/ — tiny placeholder .islave hunks and empty ADF stubs so plans resolve without multi-gigabyte game archives. vamos integration optionally uses the real C:RawDIC binary extracted from official WHDLoad_dev (local build/ only, never committed).

Running tier two locally

PyPI amitools 0.8.1 and current machine68k broke vamos on our machines (set_exc_func, missing greenlet). Pin git amitools via scripts/requirements-vamos.txt:

cd amiga-utils
./scripts/test_vamos_rawdic.sh              # layout + log tags + hunk check
./scripts/test_vamos_rawdic.sh --integration # live vamos (expect no imaging)
./scripts/test_vamos_rawdic.sh --spike       # human-readable spike output

Volume mapping lesson we paid for: assign C: with -V C:/absolute/host/path, not -a C:… with a bare POSIX path — vamos reports path setup failed otherwise. The spike mirrors the guest: install drawer files under WHDLoad:UserTools/<prefix>, ADF under Source:, RawDIC on C:.

Pass conditions for integration: exit code may be 0 with an empty log (vamos_silent_exit) — the guest binary returned without imaging. We also accept classified failures mentioning trackdisk or Intuition. We reject path_assign_error (our layout bug) and unexpected_success with a rich log (would imply imaging completed on the laptop, which should not happen).

Hero images: use real bench photography (a1200-bench-hero.jpg, bench/reference/Commodore_Amiga_A1200.jpg). If regenerating with Nano Banana, pass those paths as referenceImages — do not use generic “retro PC” prompts without references.

Why we still wanted vamos after writing the RawDIC patch

We briefly hoped vamos could act as an end-to-end test for RawDIC-Auto — run the patched binary with HEADLESS on the Mac and assert Disk.* files appear in a host folder. That does not work: headless only removes the Start button wait on real AmigaOS; imaging still needs trackdisk.device or TrackWarp reading an ADF. vamos provides none of that. The full story — what RawDIC does, why we patched it, and what we tried under vamos — is on the RawDIC-Auto page. Proof of the patch stays on WinUAE tier four.