cthulhu/docs/testing/key-echo.md

Key echo verification

Debug records named delivering accessible presentation already include utterance and custom_echo. custom_echo: true identifies a delivery attempt using the custom echo path; false uses the ordinary voice path, including existing uppercase, system and hyperlink voice choices. These records describe what the reader sends to its speech backend, not what was audibly heard. Normal, non-debug logs omit utterances. Password-role delivery text is redacted.

Run the repeatable speech check:

python3 tests/check_speech.py

It requires the echo regression tests to pass, alongside the existing queue, title and interruption checks. It uses private services and silent test speech. The focused equivalent is:

go test -race ./internal/presentation ./internal/app ./internal/input -run 'Echo|Capital|EditorParagraph' -count=1

The tests cover:

• All eight combinations of character, word and sentence echo, with echo enabled and disabled and printable key categories independently disabled.
• All sixteen combinations of the four custom-voice selections, with the custom-voice master setting on and off. The matrix checks the resulting utterance, character/text backend call and custom_echo delivery record.
• Word punctuation, repeated delimiters, Unicode, sentence precedence over word echo, Enter completion and multi-character paste presentation.
• Real SSIP client routing for key, character, word and sentence output, using private recorded speech endpoints, both directly and through the configured speaker. Existing checks cover uppercase choices, preferences Apply, persistence, edit-fields-only, Wine character feedback, key-name completion ordering and fresh-input interruption.

Verify Enter against a real GTK TextView and native AT-SPI capture:

python3 tests/native_test_session.py env CTHULHU_NATIVE_TYPING_ECHO=1 go test ./internal/app -run '^TestNativeTypingEchoLineSplit$' -count=1 -v -timeout=30s

This private Xvfb/D-Bus check presses Enter in the middle and at the beginning of existing text, for word and sentence echo. Only text before Enter may be completed. A known empty position before the caret must stay empty; the rest of the line must not be substituted into the completion context. The test captures native events and checks presentation without starting a reader or using an audio device. GTK3 Python bindings, Xvfb and xdotool are required.

Wine's insertion protocol currently supplies individual character labels, without the text context needed to complete words or sentences. The Wine tests cover the supported character/key routing; they do not establish Wine word or sentence echo. Native browser and application behavior also needs acceptance in the target application.

After reviewing the diff and rebuilding, listen with the updated reader:

1. Enable character echo with a distinctive custom character voice. Type lowercase, capitals, digits, punctuation and spaces. Disable that custom selection, then the custom-voice master setting, and check normal speech.
2. Enable word echo and type Hello world, slowly. Test with character echo both on and off. Check the Words custom-voice selection independently.
3. Enable sentence echo and type First. Second. , including the spaces. Repeat with word and character echo enabled together; sentence completion should use the Sentences voice selection.
4. In a multiline editor, put the caret between Hello and following text and press Enter. Word/sentence completion should say Hello, never following text. At the start of a line, Enter must not echo the following text. Repeat on a blank line and with a line ending in punctuation.
5. Check key echo disabled and edit-fields-only, pasted text, Backspace, Left/Right navigation, rapid typing and interruption during long speech. Right's echoed key name should finish before normal caret feedback.

Automated routing and ordering do not prove audible voice identity, physical keyboard behavior, Braille output or normal-profile acceptance. Human review and these listening checks remain required before submission.