最近在折腾 “验收自动化” 时一个反复踩的坑：

  • UI 改一点点，locator 就碎，维护成本越来越高
  • 用例脚本对 PM/QA 不友好，最后还是开发在写
  • 失败排查要截图 /trace/log 到处拼，效率很低

所以做了个小工具：AutoQA-Agent（开源 CLI）。核心思路是 Docs-as-Tests（文档即测试）：

  • 用 Markdown 写用例（Preconditions + Steps）
  • 用 Claude Agent SDK 做 “观察 → 思考 → 行动” 的执行闭环
  • 底层用 Playwright 真实驱动浏览器
  • 失败不直接崩：把错误 / 上下文回流给 agent，按护栏重试（自愈）
  • spec 跑通后：会把动作沉淀成 IR，并可 自动导出 @playwright/test 用例（可接 CI）

TL;DR

  • 写：specs/*.md
  • 跑：autoqa run <spec-or-dir> --url <baseUrl>
  • 看产物：.autoqa/runs/<runId>/（log/screenshot/snapshot/trace）
  • 跑通可导出：tests/autoqa/*.spec.ts

快速上手

git clone https://github.com/terryso/AutoQA-Agent.git
cd AutoQA-Agent
npm install
npm run build
npm link # 可选，全局使用 autoqa

autoqa init

# 跑一个示例（仓库里有 SauceDemo 用例）
autoqa run specs/saucedemo-01-login.md --url https://www.saucedemo.com/

# 本地观察执行过程
autoqa run specs/saucedemo-01-login.md --url https://www.saucedemo.com/ --debug

Markdown 用例长啥样（示例）

# Login ## Preconditions - 测试账号已存在

## Steps 1. 访问 /login 页面
2. 验证登录表单可见
3. 在用户名输入框中填写：standard_user

4. 在密码输入框中填写：secret_sauce
5. 点击"登录"按钮
6. 验证用户已跳转到仪表盘

说明：

  • Base URL 目前由 --url 提供（Preconditions 里的 Base URL 只做可读性）
  • 以 Verify/Assert（也支持 “验证 / 断言”）开头的步骤会识别为断言

稳定性思路（简单说）

  • 每次交互前先拿 accessibility snapshot（里面会有更稳定的 ref）
  • ref-first 优先点 / 填，失败再回退到语义描述
  • 工具 / 断言失败不 throw：返回结构化错误，让 agent 下一轮调整策略
  • 有护栏限制（避免无限重试 / 成本失控）

失败排查 / 产物（我自己最想要的部分）

每次运行会落盘：

.autoqa/runs/<runId>/
├── run.log.jsonl
├── ir.jsonl
├── screenshots/
├── snapshots/
└── traces/

目前状态

  • Epic 1-4 核心能力已实现：init/run、断言 + 自愈护栏、IR 记录、导出 Playwright Test
  • Epic 5（环境 / 变量 / 敏感数据注入）也已落地（.env + 模板变量思路）

想听听大家的反馈（求喷 / 求建议）

我比较关心的问题：

  • 你们更想要哪种导出风格？（更 “人写” 的 Playwright 代码还是更原子化的 steps）
  • 断言映射要做到什么程度才 “够用”？
  • 对 CI 产物你们更偏好 JUnit/JSON 还是保留 trace + log 就够了？

Repo：https://github.com/terryso/AutoQA-Agent

欢迎提 Issue / PR。

📌 转载信息
转载时间：
2025/12/25 17:35:32