企业官网建设流程全解析

TestSprite退出码速查清单：14个AWS风格退出码含义与CI门禁防假绿技巧

【免费下载链接】testsprite-cliOfficial TestSprite CLI — AI-powered automated testing from your terminal项目地址: https://gitcode.com/gh_mirrors/te/testsprite-cli

TestSprite 是一个从终端驱动 AI 自动化测试的开源 CLI 工具，它让 Agent 打开你的线上应用、像真实用户一样操作并定位缺陷。在 CI/CD 里，它的退出码（exit code）就是整个流水线的门禁开关——读懂这张速查清单，你就能把"跑完测试"变成"真正可信的绿/红判定"，从根上杜绝假绿。

本文面向新手，带你5 分钟吃透 TestSprite 的退出码含义、--wait批量优先级，以及 5 个防假绿的实战技巧。

🧭 为什么"退出码"是 CI 门禁的核心？

很多团队在 CI 里踩的坑，不是测试失败，而是测试没真正跑却被当成通过。TestSprite 借鉴了 AWS CLI 一类的风格化退出码契约：每个错误类型都映射到一个固定、稳定、可预测的退出码，脚本和 Agent 只需分支判断数字，不用去解析人类可读的报错文本。

这套契约的稳定映射定义在 src/lib/errors.ts 的exitCodeFor函数里，并与后端、MCP 插件三方保持同步。

💡 一句话记住：退出码 = 机器契约，文字 = 给人看的提示。只要分支写对数字，就不会"假绿"。

📋 14个退出码速查表

下表是 TestSprite 的完整退出码清单（信号码合并为一行，共 14 行）。收藏这一张就够了：

🔍 高频退出码逐个拆解

真正在日常和 CI 里反复出现的，是下面这几个：

• 0全绿：只有当所有run 都通过时才会出现。这是门禁唯一认可的"绿"。
• 1有失败：最常见的非零退出码，代表真实的测试失败。运维排查时按requestId而非退出码定位（INTERNAL也归到1）。
• 3认证：缺 key、key 失效、缺权限都归这里。CI 里看到3基本就是"环境变量没配对"。
• 5校验 / 零测试：⚠️ 这是防假绿的关键。当一次调用一个测试都没分发（空项目、--filter没匹配到任何用例）时，也会退出5——这是故意的，因为"在 0 个测试上变绿的门禁，比没有门禁更糟"。
• 7超时：等待超--timeout（默认 600s）；也可能是后端尚无该路由。

关于认证类退出码的判断，TestSprite 不维护第二份字符串列表，而是直接由exitCodeFor推导（auth === exit 3），见 src/lib/errors.ts。

⚙️--wait批量任务的退出码优先级

当你用test run --all --wait、批量test rerun --wait或testlist run --wait跑一整批任务时，如果结果混合（有的过、有的失败、有的超时），进程退出码不是随便挑一个，而是走一张固定优先级表：

3/14（批量级不可重试）→ 12/13（按 run 不可重试）→ 4/5/6（按 run 错误）→ 11/10（可重试）→ 7（超时）→ 1（通用失败）

这张表定义在 src/lib/wait-exit.ts，核心思想是："重试也救不回来"的配置问题，永远压过"稍后重试就行"的瞬时问题。一个超出契约的退出码（如0、99、泄漏的信号码）会被折叠进通用失败桶，既不会抢占真实判定，也不会造成"打印了失败却退出绿"。

🛡️ CI 门禁防假绿：5个实战技巧

把退出码用对，才是防假绿的根本。下面 5 个技巧可直接落地：

1. 0只在全通过时给绿。用--wait阻塞到所有 run 终结，退出码即门禁：0= 全过，否则就是红。
2. 警惕5，并善用--allow-empty。默认情况下"分发 0 个测试"会退出5把流水线拉红。只有当你真的预期空跑时，才显式加--allow-empty放行。
3. 前后端全覆盖，用测试清单（testlist）。test run --all只跑后端；要门禁前端或跨项目，把用例组进test list再testlist run <id> --wait，避免"前端被静默跳过"造成的假绿。
4. 机器可读，别靠眼睛。所有路径都支持--output json，同一份信息进 stdout /error信封，脚本分支无需抓文本。配合--report junit --report-file <path>和--summary-file <path>输出 JUnit 与机器摘要，喂给任何 CI 测试报告步骤。
5. 别手搓 YAML，直接脚手架。一条testsprite ci init github就能生成.github/workflows/testsprite.yml（逻辑见 src/commands/ci.ts），它会在"跳过/部分运行"时让 job 变红而不是报绿。

📡 信号退出码：129 / 130 / 143

在--wait期间按 Ctrl-C（SIGINT）、收到 SIGTERM 或 SIGHUP，CLI 会优雅断开：中断在飞请求、stdout 给出部分结果、stderr 告知信号并给出test wait/test cancel续跑提示。对应的退出码遵循 POSIX 惯例128 + 信号号（SIGHUP=1、SIGINT=2、SIGTERM=15），映射定义在 src/lib/errors.ts。

⚠️ 注意：普通 run 的 Ctrl-C 只是断开，服务端任务继续执行且继续计费；想真正取消请test cancel <run-id>。

📎 相关模块与源码

想深挖契约细节，这几处是入口：

• 退出码映射与错误信封：src/lib/errors.ts
• --wait批量优先级表：src/lib/wait-exit.ts
• 退出码 e2e 回归测试（防契约回归）：test/e2e/exit-code.e2e.test.ts
• 完整命令参考与退出码章节：DOCUMENTATION.md
• CI 脚手架实现：src/commands/ci.ts

把这张 14 行速查表贴在工位或 PR 模板里，你的 TestSprite 门禁从此不再假绿。

【免费下载链接】testsprite-cliOfficial TestSprite CLI — AI-powered automated testing from your terminal项目地址: https://gitcode.com/gh_mirrors/te/testsprite-cli