交给编码 Agent 闭环，并接上 GitHub Actions 门禁

开始前

• 已完成第 1、2 课：能登录，手上有一个前端项目 ID（$PROJECT_ID）。
• 一个 Git 仓库，以及任一编码 Agent：Claude Code（正式支持）、Cursor、Codex、Cline、Windsurf、Copilot、Kiro、Antigravity（实验支持）。
• 应用需部署在公网可访问的预览或线上地址（Agent 也是让云端运行器去测部署好的应用，不是你的工作区）。

一、把技能装进仓库

在仓库根目录运行（第 1 课的 testsprite setup 已经为 claude 装过一次，这一步可以单独补装或换目标）：

testsprite agent install --target claude

对照结果（CLI 0.15.0 实测）：

claude       written      .claude/skills/testsprite-verify/SKILL.md
claude       written      .claude/skills/testsprite-onboard/SKILL.md
claude       written      .claude/skills/testsprite-ci/SKILL.md
[hint] Reopen (or restart) your coding agent (claude) so it picks up ...

官方文档写的是默认装 2 个技能（verify、onboard）；CLI 0.15 实测多了第 3 个 testsprite-ci。以你本机输出为准。

用 Cursor 的同学：

testsprite agent install --target cursor

文件会落在 .cursor/rules/testsprite-verify.mdc 等位置。同时装多个目标用逗号：--target claude,cursor。装完后重开一次 Agent 让它读到新技能。

技能安装是纯本地操作：只写仓库里的文件，不联网、不需要凭据。检查装好没有：

testsprite agent status

对照结果：你装的目标那几行显示 ok，其余目标显示 absent。升级 CLI 后若出现 stale（版本旧了）或 modified（被手改过），命令会返回 1，可以直接放进 CI 当检查项。

二、两个核心技能分别干什么

几条官方写明的行为，可以用来判断 Agent 是否照规矩办事：

• 创建测试前，它会先把计划文件或测试代码给你过目，确认一次。
• 每个改动收尾都有一行结论：测试 ID、名称、passed / failed / blocked / inconclusive 和 Dashboard 链接。
• 失败时只给一行根因假设，不会只凭假设就动手改，要先读失败包。
• 跑不了（没凭据、URL 不可达、项目没关联）时会直说「已改但未验证，原因是……」。
• 全量跑整个项目要花 credits，它会报出成本、交给你决定，不会自作主张。

三、把项目钉死，免得 Agent 选错

官方约定的项目解析顺序：环境变量 TESTSPRITE_PROJECT_ID → 仓库根目录 .testsprite/config.json 里的 projectId → 按名称匹配 project list → 问你。最稳的是提交一个配置文件：

mkdir -p .testsprite
cat > .testsprite/config.json <<EOF
{ "projectId": "$PROJECT_ID" }
EOF
cat .testsprite/config.json

对照结果：打印出 { "projectId": "你的项目ID" }。

第 2 课把失败包下载到了 .testsprite/failure/。要提交 config.json 但不想提交失败包和录屏，在 .gitignore 里加一行 .testsprite/failure/。

四、对 Agent 说什么（可直接复制）

不用报命令和参数，描述你关心的行为，并要求一个结论。以下几句是官方给的说法，英文原样可用，中文意思附在后面。

第一次搭测试：

Set up TestSprite for this repo and seed a starter test suite,
then smoke-run the most important flow.

（给这个仓库配好 TestSprite、写一套起步测试，并冒烟跑最重要的流程。）

日常验证一次改动：

Verify this change with TestSprite before you call it done.

针对某个行为：

Create a TestSprite test that covers the checkout happy path
and run it to a verdict.

驱动修复循环：

The TestSprite run failed — pull the failure bundle, fix the code,
and rerun until it passes.

官方特别提示：“run it to a verdict”（跑到出结论） 这句最有用——它告诉 Agent，只写了计划没跑，不算完成。

对照结果：Agent 回复里应当出现它执行的 testsprite test create ... --run --wait 或 testsprite test rerun ... --wait，最后给出一行带 passed 或 failed 和 Dashboard 链接的结论。

你自己在终端里手动跑测试、而仓库里没装 verify 技能时，CLI 会在 stderr 打一行提醒；确定要手动驱动可以设 TESTSPRITE_NO_SKILL_WARNING=1 关掉。

五、生成 GitHub Actions 门禁

CLI 自带工作流生成器。先用 dry-run 看它会写什么（不改任何文件）：

testsprite --dry-run ci init github --project "$PROJECT_ID"

对照结果（实测节选）：开头是 [dry-run] would write the workflow below — no files changed, no secret set:，随后是完整 YAML，其中关键几步：

- run: npm i -g @testsprite/testsprite-cli@latest

# REPLACE ME — where does this PR's preview URL come from? Pick one:
- name: Get this PR's preview URL
  id: preview
  run: |
    echo "::error::Replace the placeholder step ..."
    exit 1

- name: Run TestSprite tests on this PR's preview
  run: >-
    testsprite ci run
    --project "你的项目ID"
    --env "<your-env-name>"
    --target-url "$PREVIEW_URL"
    --fail-on-skipped
    --summary-file testsprite-summary.json

确认无误后去掉 --dry-run 真正写入：

testsprite ci init github --project "$PROJECT_ID"
ls .github/workflows/

对照结果：出现 testsprite.yml。然后按 CLI 打印的 Next steps 收尾，共三处。

改掉 REPLACE ME 那一步

• 平台会给每个 PR 自动部署预览（如 Vercel 的 Git 集成）：删掉这一步，并把触发器 pull_request 换成 deployment_status，工作流会从部署事件里读预览地址。
• 预览在这个工作流里自己部署：把这一步换成你的部署命令，最后一行输出 echo "url=<预览地址>" >> "$GITHUB_OUTPUT"。

不改的话，这一步会故意报错退出，检查一直是红的。

添加仓库密钥

gh secret set TESTSPRITE_API_KEY

按提示粘贴 key；也可以在 GitHub 网页 Settings → Secrets and variables → Actions 里添加。

提交并设为必过检查

提交并推送 .github/workflows/testsprite.yml，开一个 PR，确认 TestSprite 检查跑在这个 PR 的预览地址上；要阻止不过测试的合并，在分支保护里把它设为 required check。

为什么能当门禁：CLI 在 CI 里读 TESTSPRITE_API_KEY 环境变量，不需要先跑 setup；任何没通过的结果（失败、阻塞、取消、超时）都返回非零退出码，GitHub 自动把这一步判为失败。生成的工作流还默认跳过来自 fork 的 PR 和草稿 PR（fork 拿不到仓库密钥）。

千万不要把 key 直接写进工作流文件或任何提交到仓库的脚本，一律从密钥库读取。

六、CI 里的两个好习惯

正式测试前先自检，缺 key、地址错、API 不通会在这一步就失败；WARN 不会让它失败：

testsprite doctor && testsprite test run --all --project "$PROJECT_ID" --wait

失败时把失败包留下来，方便事后看（官方 CI 文档写法）：

testsprite test run "$TEST_OK" --wait --output json > result.json || \
  testsprite test failure get "$TEST_OK" --out ./.testsprite/failure

记得在这之前 mkdir -p .testsprite，原因见第 2 课。

本课检查清单

• testsprite agent status 里你用的 Agent 显示 ok
• 仓库里有 .testsprite/config.json
• 对 Agent 说「Verify this change with TestSprite before you call it done.」后，它给出了带结论和链接的一行
• .github/workflows/testsprite.yml 已提交，TESTSPRITE_API_KEY 密钥已设置，PR 上能看到 TestSprite 检查

到这里，你的编码 Agent 每次说「做完了」之前，都会先让真实浏览器替你验一遍。