tui-testing-debugging

使用快照、PTY、虚拟终端和 ConPTY 测试与调试 TUI

当 TUI 需要可靠的测试，或需要在真实终端会话之外复现交互式终端问题时，请使用此技能。

四层测试策略

1. 纯状态测试。 在不使用终端的情况下测试 reducer、更新函数、焦点切换、验证、排序、筛选和命令调度。
2. 组件／渲染快照。 在固定的宽度、高度、主题、色彩级别、区域设置和时间下渲染组件。比较稳定的文本或单元格网格。
3. 虚拟终端测试。 将 ANSI 输出输入终端模拟器，并断言最终单元格、光标、样式、回滚缓冲区和清理结果。
4. PTY 集成测试。 启动真实程序，发送按键／粘贴／调整大小操作，并断言可见行为和退出状态。

稳定快照

冻结或规范化：

• 终端尺寸。
• 主题和色彩支持。
• 时间、随机 ID、网络数据、加载动画、光标闪烁。
• Unicode 模式和模糊宽度假设。
• 跨平台运行测试时的文件路径。
• 进度速率和异步调度。

优先使用语义断言测试行为，使用快照验证稳定的视觉约定。

调试工作流

1. 使用最小终端尺寸和输入序列复现问题。
2. 怀疑协议行为时，捕获原始输入和输出字节。
3. 分离 stdout、stderr、日志和备用屏幕输出。
4. 禁用动画和颜色，以便将布局与样式区分开。
5. 如果相关，在 tmux/screen/SSH 内外进行测试。
6. 在 Windows 上，如果声明支持 Windows，请通过 ConPTY 进行测试。

CI 规则

• 不要假设 CI 有真实 TTY。
• 集成测试需要终端行为时，使用 PTY 包装器。
• 明确标记特定于终端模拟器的测试。
• 确保快照具有确定性且便于审查。
• 失败时，将日志和最终终端画面作为构件保存。

故障模式

症状	可能原因	修复方法
快照不稳定	时间、加载动画、随机数据、终端宽度	冻结输入并规范化输出
手动运行正常，CI 中失败	没有 TTY 或 TERM 不同	创建 PTY 或使用非 TUI 模式
仅 Windows 测试失败	假设使用 Unix PTY	通过 ConPTY 测试，并处理换行符
原始字节不同，但屏幕相同	测试了控制序列而非最终单元格	断言虚拟终端状态
调试日志破坏 UI	日志写入受控屏幕	将日志写入文件或面板

参考文件

• references/test-strategy.md - 各生态系统的测试层、工具和断言。
• references/debugging-playbook.md - 字节捕获、终端重置、CI、Windows 和不稳定测试的分诊。