ADR-0095: A headless run never asks a human anything

• Status: Accepted
• Date: 2026-09-11
• Deciders: jka
• Decision: D95

Context

While ADR-0094 was being built, the GUI test suite deleted fixture directories while tabs on them were still open. The new stale-buffer check correctly asked whether to keep each deleted file open, on the maintainer's real display, once per buffer. The maintainer answered them, so green test runs had been obtained with a human in the loop, and those answers shaped the state later checks ran against.

Decision

A dialog that reports is useful; a dialog that asks a decision must never reach someone who cannot know whether their answer changes the result. Under RIO_GUI_HEADLESS, dialogs go to the run's output instead of the screen.

• tk_messageBox and the file and directory choosers are replaced: each prints what it would have asked to standard error and raises an error.
• Every such dialog is recorded, and an exit wrapper turns a non-empty record into a non-zero exit status. Raising alone is not enough: most dialogs are reached from event callbacks, where Tcl passes the error to the background handler and the run continues and reports success.
• bgerror is replaced as well, because wish's default background error handler is itself a dialog.
• There is no exception for informational dialogs. An error dialog in a test means an operation failed unexpectedly.

The guard is keyed on RIO_GUI_HEADLESS, which every suite and the documented test invocation already set, rather than on the test sandbox, which one suite deliberately does not use.

Consequences

• The exit status, not the summary line, is the verdict of a GUI test.
• Messages are preserved as copyable text.
• Fixture teardown closes tabs before deleting their files (sandbox_drop_fixture), except in suites that deliberately keep using a deleted file's buffer.
• A suite that forgets to set the variable is not protected.