slhx agent
77 lines
4.0 KiB
Markdown
77 lines
4.0 KiB
Markdown
# Terminal E2E artifacts
|
|
|
|
`zig build terminal-e2e` runs `tools/terminal_e2e.py` against the compiled `mim`
|
|
binary and writes ignored artifacts under `.zig-cache/terminal-e2e/<scenario>/`.
|
|
It is the canonical local gate for terminal rendering/input/panel/workflow slices
|
|
(NS10). Run it after `zig build`, `zig build test`, and `zig build v1-smoke` when
|
|
a change can affect terminal-visible behavior; pure protocol/headless or docs-only
|
|
changes may use cheaper checks unless their claim is terminal-visible.
|
|
|
|
The command is expected to finish in seconds on a normal development machine
|
|
(current matrix target: under 30s). A timeout or nonzero exit should be treated as
|
|
a product regression or harness bug, not a flaky benchmark: inspect the scenario
|
|
artifact directory named in the failure output.
|
|
|
|
Matrix input profiles:
|
|
|
|
- `ios-default-qwertz-space-path` means the scenario may use only letters,
|
|
Shift+letters, and Space from the default iOS software keyboard. Shift is easy
|
|
to reach on iOS; Esc, Ctrl, Alt, function keys, arrow keys, and symbol-layer
|
|
punctuation should not appear in this profile. Use this for primary mobile
|
|
workflows.
|
|
- `attached-keyboard` is allowed to cover Esc, arrows, Home/End, punctuation, and
|
|
other physical-key aliases.
|
|
|
|
Artifact roles:
|
|
|
|
- `manifest.tsv`: stable scenario facts, hashes, bare-LF status, seen ANSI roles,
|
|
and artifact list.
|
|
- `visible-controls.normalized.txt`: primary semantic failure artifact. It shows
|
|
CR as `␍`, LF as `␊`, ESC as `␛`, tabs as `⇥`, and normalizes volatile temp
|
|
paths.
|
|
- `transcript.txt`: semantic terminal grid after escape/control interpretation,
|
|
including debug-only role markers such as `☻` for a cursor cell and `░` for
|
|
selection.
|
|
- `screenshot.svg` and `terminal.html`: browser-viewable visual evidence. SVG
|
|
includes color swatches for seen cursor/current-line/status/selection roles.
|
|
- `widths.tsv`: per-line semantic width report used to catch viewport overflow.
|
|
- `keystrokes.tsv`: logical user key-event count and raw byte count for scenario
|
|
payloads. A CSI sequence such as PageDown counts as one attached-key event
|
|
while still recording all raw bytes sent.
|
|
- `saved-files.tsv`: per-file hashes/byte counts for scenarios that assert more
|
|
than the launched file, such as multi-file coding workflows.
|
|
- `e2e-prelude.trace` (scenario temp dir only when needed): harness-only trace
|
|
lines consumed before raw-mode input to seed deterministic provider fixtures;
|
|
this is not a runtime config surface.
|
|
- `raw.bin`: exact PTY bytes for low-level debugging.
|
|
|
|
Failure triage:
|
|
|
|
1. Start with the scenario directory reported by the command.
|
|
2. Read `manifest.tsv` for hashes, CR/LF status, ANSI roles, key budget, and
|
|
artifact list.
|
|
3. Read `visible-controls.normalized.txt` for visible `␍`, `␊`, `␛`, and path
|
|
normalized raw terminal evidence.
|
|
4. Read `transcript.txt`, `widths.tsv`, `keystrokes.tsv`, and any
|
|
`saved-files.tsv` for semantic assertions before inspecting screenshots.
|
|
5. Use `screenshot.svg`/`terminal.html` to explain what a user would see.
|
|
|
|
Golden policy:
|
|
|
|
- Investigate before updating any expected artifact or assertion.
|
|
- Prefer semantic artifacts (`manifest.tsv`, `visible-controls.normalized.txt`,
|
|
`transcript.txt`, `widths.tsv`, `keystrokes.tsv`, `saved-files.tsv`) for
|
|
assertions; visual artifacts explain what a user would see.
|
|
- Updating artifacts is safe only after the change is intentional and the receipt
|
|
names the changed UI/control-byte behavior.
|
|
- Adding a mobile scenario must preserve the `ios-default-qwertz-space-path`
|
|
contract unless the issue explicitly targets attached keyboards.
|
|
- Bare LF in raw-mode terminal output is a regression unless a scenario explicitly
|
|
proves a non-raw stream. Raw-mode rendering should use CRLF to avoid diagonal
|
|
terminal skew.
|
|
- Scenario `max_key_events` budgets are regression guards for workflow burden,
|
|
not speed benchmarks. Raise a budget only after explaining the intentional
|
|
workflow change in the receipt.
|
|
- Generated artifacts must remain under ignored build output and must not dirty a
|
|
clean source tree.
|