67efa330d2830c30741f9524abfd72b59f8791f8
braney
  Fri Sep 4 11:17:46 2026 -0700
docent: share the test rules, add tests/regress, and stop an empty suite passing

Moves the test rules out of tests/makefile into tests/docentTest.mk so a second
directory of Docent tests runs the same code rather than a copy. tests/makefile
and the new tests/regress/makefile each set DOCENT and include it.

tests/regress/ is for one script per already-fixed bug, asserting the behavior
its ticket says is correct, to be run nightly against genome-test (#38252). It
is kept out of tests/ so that suite stays short enough to run before a commit:
measured, its eleven scripts take 56 seconds.

Two fixes to the rules while they moved:

- make derive strips "trackDb: N tracks for DB from .../hubApi" from both the
run and the baseline. docent.js caches the trackDb listing for a day and
prints that line only on a cold fetch, so the first make derive of any day
reported CHANGED against a baseline captured warm. Verified cold and warm,
and make derive-accept reproduces the three committed baselines byte for byte.
- make test with no *.docent.yaml, and make derive with no baseline, now fail
instead of printing "docent tests passed". An empty tests/regress reported a
pass before this.

refs #37892 #38252

diff --git src/hg/utils/docent/tests/regress/makefile src/hg/utils/docent/tests/regress/makefile
new file mode 100644
index 00000000000..8b039cbe243
--- /dev/null
+++ src/hg/utils/docent/tests/regress/makefile
@@ -0,0 +1,27 @@
+# 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 derive             # the derivation alone, for the scripts with a baseline
+#
+# 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.
+#
+# 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.
+
+DOCENT = ../../docent.js
+
+include ../docentTest.mk