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

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

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

快速上手

bash 复制代码

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 用例长啥样（示例）

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 下一轮调整策略
有护栏限制（避免无限重试/成本失控）

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

每次运行会落盘：

text 复制代码

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