rose-ash/plans/lib-guest-test-runner.md

lib/guest/test-runner.sx — extraction plan

Status

• Phase 1 — Kit + Kernel. lib/guest/test-runner.sx extracted (5 forms, ~50 LoC). Seven Kernel test files migrated (parse.sx, eval.sx, vau.sx, standard.sx, encap.sx, hygiene.sx, metacircular.sx). 322/322 tests unchanged. 84 LoC removed.
• Phase 2 — Per-guest migrations. 35 additional test files match the standard (define X-test-pass 0) pattern across 7 guests; each needs the test runner's (load "lib/guest/test-runner.sx") line and a per-file harness rewrite. Variant shapes (Tcl, Smalltalk, APL alternate) need different extraction targets.

The kit

(refl-make-test-suite)              → {:pass 0 :fail 0 :fails (list)}
(refl-test SUITE NAME ACT EXP)      → mutates suite (dict-set! + append!)
(refl-test-report SUITE)            → {:total :passed :failed :fails}
(refl-test-pass? SUITE)             → bool
(refl-test-suite? V)                → predicate

Each migrated test file collapses from a 14-line harness boilerplate to:

(define X-suite (refl-make-test-suite))
(define X-test  (fn (n a e) (refl-test X-suite n a e)))
;; ... tests ...
(define X-tests-run! (fn () (refl-test-report X-suite)))

Per-guest migration status

Guest	Std-pattern files	Variant?	Migration commit
kernel	7	-	landed (Phase 1)
prolog	23	-	pending
common-lisp	4	-	pending
erlang	4	sub-prefix per file	pending
apl	1	uses set! over append, args are got expected	needs variant adapter
forth	1	-	pending
minikanren	1	-	pending
ruby	1	-	pending
tcl	0 (uses different shape — see below)	tcl-X-pass/-failures, append! a STRING	needs variant kit
smalltalk	0 (uses SUnit)	own framework	not applicable
haskell, hyperscript, js, lua	0	no per-suite harness	not applicable

Variant shapes that need their own extractions

Tcl-flavour (lib/tcl/tests/*.sx)

(define tcl-X-pass 0)
(define tcl-X-fail 0)
(define tcl-X-failures (list))   ; not -fails

(define tcl-assert
  (fn (label expected actual)    ; arg order: label, expected, actual
    (if (= expected actual)
      (set! tcl-X-pass (+ tcl-X-pass 1))
      (begin (set! tcl-X-fail (+ tcl-X-fail 1))
             (append! tcl-X-failures
                      (str label ": expected=" (str expected) " got=" (str actual)))))))

Difference from canonical: failures hold formatted strings, not dicts. Could be unified by passing a formatter cfg, but the API divergence is real (Tcl's report just lists strings; the kit's :fails holds dicts). Either:

• Add refl-make-string-formatting-test-suite variant, or
• Migrate Tcl's reports to dict-of-name-expected-actual (preferred — converges the shape).

APL-flavour

(define apl-test
  (fn (name got expected)        ; arg order: name, got, expected
    (if (= got expected) ...
      (set! apl-test-fails (append apl-test-fails (list {:got got :expected expected :name name}))))))

Difference: uses functional append, not append!. Argument order: got expected, not actual expected. Minor; renaming n a e in the kit call site to n got expected is the only change.

Migration playbook (for the loop that finishes Phase 2)

1. Pick a guest from the table.
2. Run /tmp/migrate_harness.py lib/<guest>/tests/*.sx. SKIP entries are variant-shaped; ignore them or hand-migrate.
3. Add (load "lib/guest/test-runner.sx") to that guest's test.sh and conformance.sh (before the first guest .sx load that uses the harness).
4. Run the guest's full test suite; counts should be unchanged.
5. Commit test-runner: migrate <guest> — N files, NN LoC saved.

Estimated effort: 1–2 hours per guest, dominated by verification time. Prolog (23 files) is the biggest single commit but the most mechanical.