4a5041811d79f95f11000fbc3fc310f9a4ae417a
braney
  Sun Sep 13 15:36:26 2026 -0700
docent: a test run clears up after itself, refs #38252

A run left a log per script and a stills/ directory per script, and nothing
ever removed them, so `git status` in the test directories reported 89 files
that were not work.  The obvious answer is a .gitignore, and it is the wrong
one: the files stay on disk, and git is taught to look away from the directory
new tests are written in.

`make test` now removes a passing script's log, stills and sessions.  Nothing
reads any of it once the run is over -- nightly.sh reads this target's OUTPUT,
and the failure branch prints a failing log into that output while the file is
still there.  A failing script keeps its log, and so does an xfail that passed,
which is the flip `make proof` is about and the one morning someone will want to
read the whole run.  `parity` does the same with its three logs and the mp4 its
slow run records.

WARNING lines are echoed before the log goes.  make test sends each script's
output to its log and prints only "ok", so a docent warning on a PASSING script
reached a file nobody opens -- and "tooltip never showed its own text" means the
step measured nothing.  None of the 67 scripts warns today; the point is that
one that starts to will say so.

Five orphan logs are removed by hand in passing: rm36212.xfail.log,
rm36540.log, rm37388ui.xfail.log, rm37389.xfail.log and rm38272.xfail.log, left
behind when those scripts were renamed.  make test deliberately does not sweep
logs it did not just write, since a rename in progress should not lose its
evidence; make clean is still there for a full wipe.

Measured: 67 of 67 green in 10m39s and the directory came back with nothing
untracked in it, the fifteen language tests next door pass and clear their
sessions/ too, and a script made to fail on purpose kept its log and its stills.

diff --git src/hg/utils/docent/tests/regress/makefile src/hg/utils/docent/tests/regress/makefile
index f6d6dfaf395..eb296ca5057 100644
--- src/hg/utils/docent/tests/regress/makefile
+++ src/hg/utils/docent/tests/regress/makefile
@@ -1,30 +1,35 @@
 # Docent REGRESSION tests: one script per bug we have already fixed, asserting the
 # behavior the ticket says is correct. Separate from ../ on purpose, and run nightly
 # against genome-test.
 #
 # Measured 2026-09-04: the eleven scripts next door take 56s all together (3-8s each, all
 # in FAST mode). A `convert:` test measured 16s, because a quickLift hop is hgConvert plus
 # a hub build plus the click through to the browser. Fourteen of the forty here open with
 # `convert:`, so the estimate for a full run is about seven minutes, not the half hour a
 # guess would suggest. Re-measure rather than trusting this comment.
 #
 #     make test               # every *.docent.yaml here
 #     make test T=rm36382     # just one
 #     make proof              # what evidence each script has that it would catch its bug
 #     make derive             # the derivation alone, for the scripts with a baseline
 #
+# A run clears up after itself: a script that passed leaves no log and no stills
+# directory, and any WARNING it printed is echoed here before the log goes. A script that
+# failed keeps its log, and so does an xfail that passed, since that is the flip. So
+# `git status` in this directory shows work in progress and nothing else.
+#
 # Naming: rm<ticket>.docent.yaml, so the ticket is the filename. Every script says in its
 # first lines which ticket it is, what the symptom was, and what the assertion would
 # catch -- a regression test whose comment does not name the bug is unmaintainable, since
 # the next reader cannot tell a deliberate assertion from an accident.
 #
 # Most of these assert the FIXED behavior and were never watched to fail on a buggy build,
 # so the assertions are deliberately tight: `exact:` and `noRows:` rather than a bare
 # `rows:`, and `noText:` on the exact error string the ticket quoted. A loose assertion
 # here is indistinguishable from no test at all.
 #
 # Which ones HAVE been watched to fail for their own reason is recorded in each script's
 # `proof:` key and counted by `make proof`. See README.txt for the levels and for the two
 # ways to earn one.
 
 DOCENT = ../../docent.js