[分享] AutoQA-Agent：用 Markdown 写验收用例， AI + Playwright 跑起来，跑通还能导出成 Playwright Test

[terryso]

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

• 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
- Test account exists

## Steps
1. Navigate to /login
2. Verify the login form is visible
3. Fill the username field with standard_user
4. Fill the password field with secret_sauce
5. Click the "Login" button
6. Verify the user is redirected to dashboard

说明：

• 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 。