装好 CLI：用 --dry-run 离线演练，再登录自检

你将得到什么

• 一个可用的 testsprite 命令
• 知道 --dry-run 能干什么、不能干什么
• 一份已验证的登录凭据（保存在 ~/.testsprite/credentials）
• 看懂 auth status 和 doctor 的每一行

一、检查 Node 版本

node --version

对照结果：版本号必须落在 20.19+、22.13+ 或 24+ 之一，例如 v20.19.2、v22.13.0、v24.x。奇数版本 21.x、23.x 不受支持；版本不对就先到 https://nodejs.org/ 换一个 LTS。

二、安装 CLI

全局安装（官方推荐）：

npm install -g @testsprite/testsprite-cli
testsprite --version

对照结果：

0.15.0

官方安装页的示例输出写的是 0.3.x，那是旧版本号；只要能打印出版本号就说明装好了。2026-10-19 npm 上的最新版是 0.15.0。

不想全局安装，也可以临时用 npx：

npx @testsprite/testsprite-cli --version

三、用 --dry-run 离线演练

官方 Quickstart 的提示：在任何命令里加上 --dry-run，CLI 不联网、不需要 API key，直接返回一份和真实接口同结构的样例数据。每段输出第一行都会标明 [dry-run] sample response — not from the server。

先跑一次自检

testsprite --dry-run doctor

对照结果（实测）：

TestSprite doctor

  [OK]   CLI version   0.15.0
  [OK]   Node.js       v20.19.2 (supported range: 20.19+, 22.13+, or 24+)
  [OK]   Profile       default
  [OK]   API endpoint  https://api.testsprite.com
  [WARN] Credentials   no API key (not needed under --dry-run)
  [WARN] Connectivity  skipped under --dry-run
  [WARN] Local tunnel  skipped under --dry-run
  [WARN] Verify skill  not installed here; run `testsprite setup` ...

0 failure(s), 4 warning(s).

四条 WARN 在 dry-run 下是正常的：没有 key、不联网、没装 Agent 技能。

看看项目和测试列表长什么样

testsprite --dry-run project list

对照结果（样例数据，ID 每次一样）：

[dry-run] sample response — not from the server
ID                NAME          TYPE      FROM    CREATED   ...
project_b3c91efa  Checkout      frontend  portal  2026-04-15...
project_a47b2c11  Internal API  backend   mcp     2026-03-01...

testsprite --dry-run test list --project p_dryrun_2026

对照结果：三条样例测试，状态分别是 failed、passed、blocked——这正是你以后在真实项目里会看到的三种结局。

看一份失败分诊卡

testsprite --dry-run test failure summary test_dryrun_create_2026

对照结果（节选）：

testId:               test_8f2a4d10
status:               failed
failureKind:          assertion
snapshotId:           snap_2026_05_05_b2f9a1c8
rootCauseHypothesis:  Submit button has `opacity: 0.4` and is rendered
                      as disabled. ...
recommendedFixTarget: kind=code reference=src/components/CheckoutForm.tsx:412

记住这几个字段：failureKind（失败类型）、rootCauseHypothesis（根因假设）、recommendedFixTarget（建议改哪里）。第 2 课你会在自己的测试上看到真实版本。

dry-run 也会校验你的文件

官方说明：--plan-from、--plans、--steps 传入的文件在 dry-run 下仍会在本地读取并校验。故意写一个错的计划文件试试：

cat > bad.plan.json <<'JSON'
{ "projectId": "x", "type": "frontend", "name": "bad",
  "planSteps": [ { "type": "click", "description": "Click" } ] }
JSON
testsprite --dry-run test create --plan-from ./bad.plan.json
echo "exit=$?"

对照结果（实测）：

Error: Invalid request.
Field `planSteps[0].type` is invalid: must be one of: "action", "assertion".
exit=5

这说明两件事：计划步骤只有 action 和 assertion 两种；退出码 5 表示参数或文件校验失败。写完计划文件先用 dry-run 过一遍，能省掉真实运行的 credits。

四、注册账号并创建 API key

1. 打开 https://www.testsprite.com/auth/cognito/sign-up 注册（免费档每月 150 credits，见 https://www.testsprite.com/pricing ）。
2. 登录后进入 Dashboard 的 Settings → API Keys，点 Create new key。
3. key 只显示一次，立刻复制。新建的是工作区 key，前缀为 sk-member-；每个成员在每个工作区最多 2 个有效 key，满了要先撤销一个。

默认权限（scopes）已经覆盖 CLI 需要的全部：read:me、read:projects、read:tests、write:tests、run:tests。

把 key 当密码。官方说明 CLI 从不接受把 key 写在命令参数里，也不会写进日志；不要把它贴进聊天、截图或提交到仓库。

五、登录：testsprite setup

在你的项目根目录运行：

testsprite setup

它会提示粘贴 key（输入不回显），验证通过后把 key 存到 ~/.testsprite/credentials，并顺带给默认 Agent（claude）装好验证技能。对照结果（官方文档示例，邮箱等会是你自己的）：

TestSprite API key: ********
TestSprite initialized.

  profile:  default
  env:      production
  email:    alice@example.com
  scopes:   read:me, read:projects, read:tests, write:tests, run:tests

  agent:    claude (installed)

只想配置凭据、暂时不装 Agent 技能：

testsprite setup --no-agent

在 CI 或脚本里不想交互，用环境变量（第 3 课会用到）：

TESTSPRITE_API_KEY=$TS_KEY testsprite setup --from-env --yes

六、确认登录成功

testsprite auth status

对照结果（官方示例）：

userId    u_01abc...
name      Alice Example
email     alice@example.com
keyId     key_01xyz...
env       production
scopes    read:me, read:projects, read:tests, write:tests, run:tests

如果缺少某个 scope，CLI 会多打印一行 note: 告诉你哪些命令会被拦住。

再跑一次真正联网的自检，这次不加 --dry-run：

testsprite doctor

对照结果：Credentials 和 Connectivity 两行变成 [OK]，结尾 0 failure(s)。doctor 只有真正的失败才返回非零，WARN 不会让它失败。

常见错误对照

下一课：写计划文件，让 TestSprite 在云端真实浏览器里跑你的第一条测试。