e128682fd48d974c0eaa74366087d2be47080bf5
braney
  Fri Sep 4 11:43:52 2026 -0700
docent: add make preflight, which checks the fixtures a test suite does not own

A Docent test that loads a saved session or attaches a hub depends on something
outside the tree, and the failure when that thing goes away is silent rather
than loud. A session that has been renamed or deleted is not an error: hgTracks
answers HTTP 200 with a page titled "Very Early Error" whose body reads "Could
not find session NAME for user USER", the page carries no track image, and every
noText: assertion on it passes. The run goes green having tested nothing.
Verified both ways: a bogus session name passes a test whose only check is
noText:, and fails once the script also asserts noText: "Could not find
session".

preflight.js reads the fixtures out of the scripts themselves -- loadSession:,
hub:, addHub:, addCustomTrack: url:, and hubUrl= inside a goto: -- so the list
cannot drift from what the scripts actually use. It needs no browser, runs in a
couple of seconds, and exits non-zero if anything is unreachable, which is what
lets a nightly run tell "the fixtures are gone" from "a bug came back".

Checking it against the sessions cited by the tickets in #38252 found four that
do not exist on genome-test because they were saved on the RR or on beta, and
corrected one I had wrongly called missing: session names store a dash as %2D,
so a MySQL LIKE with a literal dash misses them. The HTTP check has no such
problem, which is a reason to prefer it over a query against namedSessionDb.

refs #37892 #38252

diff --git src/hg/utils/docent/tests/regress/makefile src/hg/utils/docent/tests/regress/makefile
index 8b039cbe243..5d6f4edf8b8 100644
--- src/hg/utils/docent/tests/regress/makefile
+++ src/hg/utils/docent/tests/regress/makefile
@@ -1,27 +1,29 @@
 # 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
 
+PREFLIGHT = ../preflight.js
+
 include ../docentTest.mk