f963b73576b5c69915366893da7dfa6afe633456
braney
  Sat Aug 8 14:04:23 2026 -0700
docent: add a tests directory and a browser-free derive mode, refs #37892

tests/ holds Docent scripts that assert with expect:, run by hand with `make
test` rather than by the tree's test target, since each one drives a real
server. Nine of them: the two-request composite split (#37953), hideKids on a
view and on a superTrack, the cCREs expansion that once overran the request
line, addCustomTrack, a 3x run, and the session/loadSession round trip. A
script named *.xfail.docent.yaml is expected to fail, which is how the
hideKids-aimed-at-the-composite trap is pinned rather than only written down,
and how expect: itself is checked.

DOCENT_DERIVE=1 prints what each track: step turns into and stops, with no
browser and no navigation. That derivation is where most of Docent's own
decisions are, and it was previously visible only in the log of a full run.
`make derive` diffs it against baselines in tests/expected/ for the scripts
whose derived set is small enough to be stable.

The track: verb now calls trackRounds() for that derivation instead of doing
it inline. No behaviour change intended; the tests above pass before and after.

Two things the tests turned up, both recorded in tests/README.txt: turning on
anything under a superTrack sends <superTrack>=show and undoes an earlier
hide: all for its other members, and hideKids on a view has to enumerate
leaves, so one such step sends 188 variables in a 6,986-character request.

diff --git src/hg/utils/docent/tests/views.docent.yaml src/hg/utils/docent/tests/views.docent.yaml
new file mode 100644
index 00000000000..0525b5ff1c7
--- /dev/null
+++ src/hg/utils/docent/tests/views.docent.yaml
@@ -0,0 +1,39 @@
+# hideKids on a composite that has VIEWS, which is two levels, not one.
+#
+# `hideKids` hides views as units, so it has to go on the view that actually holds the
+# subtrack. Aim it at the composite instead and the view your subtrack lives in is
+# hidden with it, and the row silently disappears -- see views.xfail, which pins that.
+#
+# This one is the form that works: hideKids on the Signal view, the sibling views hidden
+# by name, one subtrack left showing. wgEncodeRegDnaseUwWerirb1Signal is `parent
+# wgEncodeRegDnaseSignal off` in trackDb, so it also exercises the `_sel` checkbox --
+# without it the subtrack stays deselected and nothing is drawn.
+target: genome-test
+db: hg38
+position: chr7:155799529-155812871
+reset: true
+fast: true
+steps:
+  - go: chr7:155799529-155812871
+  - hide: all
+  - track:
+      wgEncodeRegDnasePeak: hide
+      wgEncodeRegDnaseHotspot: hide
+      wgEncodeRegDnaseSignal: hideKids
+      wgEncodeRegDnaseUwWerirb1Signal: full
+
+  # The subtrack we asked for is drawn, and the nine Signal subtracks that trackDb marks
+  # `parent wgEncodeRegDnaseSignal on` are not -- which is what the view-level hideKids
+  # is for. Without it they all come up alongside.
+  - expect:
+      rows: [ruler, wgEncodeRegDnaseUwWerirb1Signal]
+      noRows: [wgEncodeRegDnaseUwK562Signal, wgEncodeRegDnaseUwGm12878Signal,
+               wgEncodeRegDnaseUwHepg2Signal]
+      noText: "Too Long"
+
+  # No `exact:` above, and this is why. wgEncodeRegDnase sits under the wgEncodeReg
+  # superTrack, so turning anything on beneath it sends `wgEncodeReg=show`, and every
+  # member of that superTrack then comes up at its own trackDb visibility -- H3K27ac is
+  # `visibility 2`, so it reappears however much the `hide: all` above hid it. Asserting
+  # it is HERE rather than working around it: the day that changes, this says so.
+  - expect: {rows: [wgEncodeRegMarkH3k27ac]}