集成测试与沙箱矩阵

集成测试位于官方仓库 integration-tests，运行构建后的 CLI 并验证文件系统等行为。它们不包含在默认 npm run test 中，需要独立执行。

先构建被测产物

npm run bundle
npm run test:e2e

CLI 源码变化后必须重新 bundle；仅修改测试时不必因此重建程序。否则可能出现用新测试验证旧产物的情况。

缩小执行范围

按文件名运行一组测试：

npm run test:e2e list_directory write_file

按测试名称筛选：

npm run test:e2e -- --test-name-pattern "reads a file"

文件位于 integration-tests，示例省略 .test.js 后缀。按名称筛选时先确认实际匹配用例，避免将零匹配误读为功能通过。

沙箱矩阵

npm run test:integration:all 覆盖不使用沙箱、Docker、Podman 三类环境。分别执行的脚本为：

相应运行时需在测试机器可用。官方 chained_e2e.yml 用于 main 的 PR 与 merge queue 集成检查，实际 CI 定义以当前分支为准。

模型响应 golden files

部分测试使用录制的模型响应。需要重新录制时：

REGENERATE_MODEL_GOLDENS="true" npm run test:e2e

新响应可能包含本机或用户信息，纳入仓库前需检查内容。官方要求用例结束执行 await rig.cleanup()，否则 golden files 不会更新；清理不是可省略的收尾步骤。

新测试的稳定性

官方要求新增集成用例至少重复运行 5 次，可使用：

npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"

也提供 deflake.yml 工作流，按分支与 test_name_pattern 运行。行为评估的三次本地重复要求属于另一套流程，不能替代这里的五次检查。

失败产物

KEEP_OUTPUT=true VERBOSE=true npm run test:integration:sandbox:none

KEEP_OUTPUT 保留临时目录，VERBOSE 增加诊断输出；同时启用时，输出也保存到测试目录日志。产物组织为 .integration-tests/<run-id>/<test-file>/<test-case>/，便于按运行和用例定位。

内存与性能基线测试另见回归测试，它们也不属于默认 e2e。