最近在折腾“验收自动化”时一个反复踩的坑：
- 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就够了？
欢迎提 Issue / PR。
