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/makefile src/hg/utils/docent/tests/makefile
index b4c1a84ca93..01b38990068 100644
--- src/hg/utils/docent/tests/makefile
+++ src/hg/utils/docent/tests/makefile
@@ -5,16 +5,18 @@
 #     make test               # every *.docent.yaml here
 #     make test T=composite   # just one
 #     make parity             # same script FAST and slow, and twice over
 #
 # A test passes by exiting 0. It fails when an `expect:` step does not hold, which
 # names what it wanted and what was actually drawn, and exits 1.
 #
 # A script named *.xfail.docent.yaml is expected to FAIL, and the run fails if it
 # passes. That is how a documented trap gets pinned: views.xfail asserts that
 # `hideKids` aimed at the composite really does lose the row, so the day that
 # changes, someone is told rather than left to notice.
 
 DOCENT = ../docent.js
 PARITY ?= composite
 
+PREFLIGHT = ./preflight.js
+
 include docentTest.mk