QA Wolf CLI：终端端到端测试工具

项目简介

QA Wolf CLI 让你可以在终端或 CI 中运行 QA Wolf 的 flows（测试流程）。它负责在本地运行和管理 flows；而 flow 创建、AI 生成测试、托管云端执行和团队协作则属于完整的 QA Wolf 平台。

使用前需要一个 QA Wolf 账号（在 qawolf.com 注册），<env-id> 可在 QA Wolf 控制台的 Settings → Environments 中找到。完整文档见 docs.qawolf.com。

主要功能

• 本地运行 flows：qawolf flows run 从本地 .qawolf/<env> 缓存执行团队的 flows，缓存不存在时才从平台拉取，并安装所需运行时依赖。
• 平台运行管理：qawolf run 通过公开 API 触发和管理平台上的 run。
• 失败排查：qawolf attempt 汇总并查看已完成 run attempt 的 trace 与日志，支持时间线、网络请求、快照、截图、控制台和日志等多种证据。
• 项目初始化与诊断：qawolf init 搭建纯本地项目，qawolf doctor 诊断问题，qawolf install 安装运行时依赖。
• Agent 集成：仓库提供符合 Agent Skills 规范的 qawolf-cli 技能，可用于 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode 等兼容工具。
• Runner SDK：用 TypeScript 驱动交互式 runner（@qawolf/cli/runner-sdk），支持启动、运行、录制视频等操作，并可通过 listRecordings 查看录制历史。

安装与使用

安装：

npm install -g @qawolf/cli
# or: pnpm add -g @qawolf/cli
# or: yarn global add @qawolf/cli
# or: bun add -g @qawolf/cli

免安装试用：

npx @qawolf/cli --help

支持的 Node 版本：Node 24.14.1+。此外每个 GitHub Release 都附带免 Node 的预编译二进制：qawolf-linux-x64、qawolf-linux-arm64、qawolf-darwin-x64、qawolf-darwin-arm64、qawolf-windows-x64.exe。

curl -fsSL -o qawolf https://github.com/qawolf/cli/releases/latest/download/qawolf-darwin-arm64
chmod +x qawolf && ./qawolf --help

快速开始：

qawolf auth login                  # 或在 CI 中设置 QAWOLF_API_KEY
qawolf flows run --env <env-id>

刷新本地缓存用 qawolf flows pull --env <env-id>；脱离平台在本地编写 flows，先运行 qawolf init。

运行示例 flows：

qawolf install   # 一次性安装浏览器运行时
qawolf flows run examples/example.flow.ts

排查一次 run attempt：

qawolf run get --run-id <run-id> --flow-statuses failed
qawolf attempt investigate --attempt-id <attempt-id>
qawolf attempt inspect --attempt-id <attempt-id> --timeline --limit 20
qawolf attempt inspect --attempt-id <attempt-id> --request <request-id>

attempt inspect 需要且只能指定 --action、--timeline、--network、--request、--snapshot、--screenshot、--console、--log 中的一个。快照 HTML 可直接返回或写入新文件，截图必须写入文件，且 CLI 拒绝覆盖已存在的路径：

qawolf attempt inspect --attempt-id <attempt-id> --snapshot <snapshot-id> --format html
qawolf attempt inspect --attempt-id <attempt-id> --snapshot <snapshot-id> --format html --output-file snapshot.html
qawolf attempt inspect --attempt-id <attempt-id> --screenshot <screenshot-id> --output-file screenshot.jpeg

安装 Agent Skill：

npm install -g @qawolf/cli
npx skills add qawolf/cli --skill qawolf-cli --global

非交互地指定目标 Agent：

npx skills add qawolf/cli \
  --skill qawolf-cli \
  --global \
  --agent claude-code \
  --agent codex \
  --yes

注意事项

• trace 与日志由 qawolf attempt get 返回的签名链接下载，并在本机解析；下载、输出文本、HTML、请求体和日志保留都有限制，incomplete、truncated、malformed 等状态字段表示证据未能完整读取。
• Runner SDK 中，ok: false 表示请求失败（含传输、鉴权或本地校验）；runner 拒绝请求时返回 ok: true 并附带 outcome 与 failureReason。
• record 还支持 { action: "status" } 和 { action: "auto", enabled: true }（或 false）；重试 start/stop 时请保留同一个 UUID。
• 许可证为 Apache-2.0。

---

本作品整理自 GitHub 开源项目 qawolf/cli，原作者 @qawolf，许可证 Apache-2.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。