如何为终端复用器写测试:boo 基于真实 PTY 的端到端集成测试实践
如何为终端复用器写测试:boo 基于真实 PTY 的端到端集成测试实践
boo 是一个用 Zig 编写、构建在 libghostty 之上的 GNU screen 风格终端复用器(terminal multiplexer)。这篇文章带你走进它的测试体系,看一个"终端软件如何测终端":不开 mock,直接给测试程序配一块真实 PTY,把 attach、detach、重连、鼠标、键盘协议整个流程端到端跑一遍。
为什么终端复用器的测试必须上"真实 PTY"
先看 boo 的架构(README.md 中):
your terminal <-(raw tty)-> boo client <-(unix socket)-> session daemon
`- PTY + ghostty-vt Terminal
客户端把你的 TTY 切到 raw 模式,字节流经 src/protocol.zig 定义的带帧 Unix socket 协议交给守护进程;守护进程持有 PTY,子进程的输出持续喂给 src/window.zig 里的 libghostty 终端仿真器,PTY 相关逻辑在 src/pty.zig 与 src/daemon.zig。
这样的系统里,"测试"的对象本身就很特殊:
- 字节流有状态:光标移动、SGR 颜色、清屏、备用屏切换,都是转义序列,中间任何一步理解错,最终画面就错;
- 时序敏感:detach 时按住的键还在自动重复、SIGWINCH 到达时应用正写着屏;
- 交互双通道:用户终端里的字节(in-band)和
boo ls/boo peek这类 CLI 命令(out-of-band)互相印证。
用 mock 终端去"假装"这些行为,成本比真机还高。boo 的选择很直接:给每个测试开一块真 PTY,测试程序自己扮演用户终端。全部集成测试集中在 test/integration.zig(约 3000 行、70+ 个用例),开头注释把策略说得很明白:
a test "terminal" (PTY master) hosts the attach client as its controlling terminal, exactly like a user's terminal would.
三层测试结构:单元测试、PTY 集成测试、微基准
测试入口在 build.zig 里注册了四个步骤:
| 命令 | 作用 |
|---|---|
zig build test |
单元测试(进程内,不需要 TTY) |
zig build test-integration |
真实 PTY 的端到端测试(本文主角) |
zig build test-all |
以上全部 |
zig build bench |
boo ui 视口渲染热路径微基准,见 bench/render.zig |
其中集成测试模块会拿到编译好的真实二进制路径(build.zig 的 exe_path 选项),并链接 libghostty——这个依赖后面断言"用户到底看到了什么"时会再用到。Nix 用户可以先 nix develop 进入带 Zig 0.15.2 的环境;flake.nix 里 doCheck 只跑单元测试,因为沙箱里没有 TTY,PTY 集成测试留给 CI 用 zig build test-all 执行。
测试骨架一:Harness——每个测试一座隔离沙箱
直接测一个常驻守护进程的复用器,最大的坑是测试之间互相污染。boo 的解法是一个 Harness 结构(test/integration.zig):
init时在/tmp下生成随机目录/tmp/bootest-<12位hex>,把环境变量BOO_DIR指过去——boo 的会话 socket 都落在这里,天然与其他测试、与你机器上正在跑的 boo 实例互不干扰;run/runIn封装执行真实二进制,支持自定义工作目录(测默认会话名依赖 cwd 的用例就靠它);deinit时先boo kill --all兜底杀掉残留守护进程,再删掉目录,保证测试失败也不留尸体。
在这层之上又有一组"动词级"助手,把测试意图写成一句调用:startDetached(boo new -d)、sendLine(boo send --text … --enter)、waitPeekContains(轮询 boo peek 直到屏幕出现目标文本)、waitUnread/waitBell(轮询 ls --json 的标志位)。
测试骨架二:PtyClient——测试自己当"用户终端"
这是整个测试文件里最有价值的一块(PtyClient),它复刻了"用户打开终端"的完整物理过程:
- 开 PTY 对:
posix_openpt→grantpt→unlockpt→ptsname_r拿到从设备路径(spawnProgram); - 设尺寸:
IOCSWINSZ指定行数列数,测试可以精确构造 12×57、24×80 等形状; - fork 后走 login_tty 套路:子进程
setsid+TIOCSCTTY把 PTY 从设备设为主控终端,dup2到 stdin/stdout/stderr 再execve——于是被测的boo attach以为自己真跑在一个人格完整的终端里; - 操控接口:
send往主端写字节(模拟敲键盘,包括\x01d这类原始控制字符)、pump用poll抽干输出、waitFor带超时地等目标字节出现、setSize动态改尺寸触发 SIGWINCH、waitExit拿退出码。
还有一个巧思:spawnProgram 允许 PTY 里跑任意程序而不只是 boo。比如测"detach 后按键泄漏"时,它启动一个 shell 包装器包住 attach——这个 shell 就是登录 shell 的替身,detach 后任何漏进终端的字节都会被它的 read 捕获并打印 GOT<a href="https://link.gitcode.com/i/9fd4d77c46890ec32aa63b4e0dfa8114" target="_blank">…,泄漏无所遁形([expectNoDetachKeyLeak)。
所有等待都挂在一个 Deadline 上(定义):10 秒总预算、25ms 一次 tick,没有一处裸 sleep 赌时序。超时不是干巴巴报错,而是把"最后一次看到的画面/输出"整段 dump 出来——对终端类调试,现场比错误码值钱得多。
断言什么:字节流,还是"用户看到的屏幕"?
只匹配原始字节有个致命问题:它无法分辨内容后来是否被清掉了(代码注释原话:raw byte matching cannot tell whether content survives on screen)。boo 因此准备了两档断言:
第一档:原始序列断言。 验证协议层的"事件顺序"。比如断言进入备用屏的 \x1b<a href="https://link.gitcode.com/i/5944b75ab58761294abfd3665f6608bb" target="_blank">?1049h 必须出现在会话内容之前、退出备用屏的 \x1b[?1049l 必须出现在 "detached from …" 提示之前([attach 测试)——顺序错了,用户就会看到一帧闪屏。
第二档:渲染后屏幕断言。 测试侧用 libghostty 再仿真一遍捕获到的字节流,还原出屏幕矩阵(renderScreen),然后像人一样读屏:断言第 3 行以 4 个空格开头(证明光标定位生效、peek 反映的是屏幕几何而非字节流,VT 序列测试);断言 200 行滚动后屏上 LINE-N 严格递增且最新一行是 LINE-200(抓"滚动时复用了陈旧行缓存"这类 bug)。
还有一个值得抄的防误配细节:很多用例要等屏幕上出现一个标记,但敲进去的命令本身会被回显。boo 的做法是把标记拆成 printf 参数在运行时拼装(如 T=EDGE; printf "...${T}Z"),回显的命令里只有碎片,永远不可能提前满足等待条件。
覆盖地图:70+ 个集成测试都在防什么
| 场景类别 | 典型用例 | 源码位置 |
|---|---|---|
| 屏幕再水合 | detach 期间写的内容,reattach 后从 libghostty 状态重绘,标题一并恢复 | reattach 测试、标题测试 |
| 尺寸与 SIGWINCH | 初始 --rows/--cols 直达子 PTY;改外层终端尺寸沿 client→daemon→PTY 传播 |
window size 测试 |
| 备用屏与终端查询 | 应用的 alt-screen 开关被过滤、画面从状态重绘;CPR 查询在 passthrough 期间由 daemon 代答 | alt screen 测试、CPR 测试 |
| 现代键盘协议 | kitty keyboard(CSI u)、modifyOtherKeys 下编码的 C-a 仍是前缀;按住前缀键的自动重复不得漏进 shell("SSH 会话杀手"变体) |
kitty 测试、按键泄漏测试 |
| 会话生命周期 | detach 后会话存活、kill 通知 attach 客户端、peek 在 kill 后确定性返回 exit 3(重复 10 次放大竞态) |
kill 竞态测试 |
boo ui 全屏管理器 |
侧边栏排序/焦点、SGR 鼠标点击、拖选复制走 OSC 52、滚轮翻 scrollback、steal 语义、重命名提示、隐藏侧边栏 | ui 测试区 |
| 机器接口与退出码 | ls --json/peek --json 字段校验;usage=2、无会话=3、wait 超时=4 逐一断言 |
退出码测试 |
| Agent 循环 | 无 TTY 下 new→send→wait→peek→kill 完整走通(这正是 AI agent 驱动 boo 的标准姿势) | agent loop 测试 |
其中"按键泄漏"一组用例最能体现真实 PTY 的价值:它按远程链路上真人按键的时序施压——按下瞬间的首次自动重复与键合并为一次 read 到达、松开滞后一个重复间隔、慢键盘还要再补一发 450ms 后的迟到重复。这种时间线上的 bug,任何静态 mock 都复现不出来。
可以抄走的 4 条经验
- 双通道观测:一半断言走 PTY 客户端(用户视角),一半走无 TTY 的 CLI(
peek/ls --json,系统视角)。单看字节流是猜谜,两路交叉才是证据; - 断言"渲染后的屏幕":拿被测系统同款终端仿真器回放捕获字节,断言用户可见结果,而不是原始字节;
- 标记防回显误配:等待的标记用运行时拼装生成,让命令回显永远凑不出完整标记;
- Deadline 轮询替代 sleep:统一 10 秒预算、小步 tick,超时时 dump 最后一帧现场。
快速上手:如何运行这些测试
git clone https://gitcode.com/gh_mirrors/boo10/boo
cd boo
zig build test # 单元测试
zig build test-integration # 真实 PTY 的端到端测试
zig build test-all # 全部
要求 Zig);用 Nix 的话 nix develop 一步到位。跑完你会发现:终端软件的可靠性,恰恰是"把终端原样搬进测试里"换来的。