cthulhu/docs/testing/text-control-labels.md

Native text-control labels

Unnamed text controls can expose their labels through AT-SPI LABELLED_BY relationships. Cthulhu uses those labels for text, entry and password-text snapshots when the control has no accessible name. An existing name takes precedence. The lookup follows only explicit targets, with a maximum of 16 targets and 4096 bytes; it does not guess from neighboring widgets or use the field's value as its label.

Run the native GTK and presentation regression in a private display and bus:

python3 tests/native_test_session.py env CTHULHU_NATIVE_TEXT_LABELS=1 go test ./internal/presentation -run '^TestNativeTextLabelRelations$' -count=1 -timeout=40s -v
go test ./internal/atspi ./internal/presentation ./internal/braille
env CTHULHU_SPEECH_METADATA=1 python3 tests/native_atspi.py

The native regression covers empty and populated entries with mnemonic labels, an explicit accessible name differing from its visible label, a password field, an unlabeled entry beside unrelated labels, and multiple relationship targets. It checks the captured names and resulting focus speech text. It does not establish audible speech or physical Braille acceptance.

For live verification with a rebuilt reader, open I38's Create Desktop Shortcut dialog. Tab and Shift+Tab through Target and Shortcut name while empty, then populate both fields and repeat. Each focus announcement should include its label and current value. Confirm editing and caret navigation still read field contents normally. Check an explicitly named search field in the application picker, plus ordinary labeled entries and password fields in another GTK application. Password contents must remain private. If using Braille, confirm labels appear and routing still reaches the editable text. Review and test these changes before submission.