AI-test-agent（一）刚入门测试也能读懂：一个基于 LangGraph + Playwright 的开源测试工作台

把「生成用例 → 真正执行 → 出报告」焊成一条流水线：开源仓库 ai_test_agent 入门讲解

仓库地址：github.com/ywq2019/ai_...

许可证：MIT

本文性质：学习笔记 + 仓库导读，不是官方文档翻译 ，也不是作者本人。

适合读者：刚接触软件测试、想搞清楚「AI 测试平台」到底在干什么的同学。

写在前面

我刚入门测试不久。最近工作里经常听到一句话：自动化生成测试样例，对功能执行测试，再输出测试报告。听起来很完整，但真正上手时会卡住三件事：

用例从哪来？难道每条都手写？
「执行」到底是发 HTTP，还是打开浏览器去点？
报告怎么才能给别人看，而不是只剩一堆终端日志？

后来我在 GitHub 上找到这个开源仓库 ywq2019/ai_test_agent 。它不是一篇概念demo，而是一个已经能部署、能点、能跑的测试工作台。星数不算多（本文写作时大约 40 star、10 fork），但文档和设计说明写得很认真。我尽量按自己能听懂的方式，把仓库尽量给别人讲明白，方便同样刚入门的同学少走弯路，当然，我使用了AI辅助撰写。

先说清楚边界：

我会讲它「是什么、怎么分层、为什么这么设计、建议怎么学」。
不会把官方 README 整页粘贴过来，也不会写成安装排障大全。
渗透测试模块只做能力介绍和合规提醒，不教扫描步骤。
文中不出现任何公司内网地址、Cookie、账号。

如果你只有 3 分钟，记住这一句就够了：

这是一个「人选定测什么，AI 起草用例，机器真正去请求或点页面，最后吐出 Excel / PDF」的开源测试平台。LangGraph 是可选的大脑，真正干活的是两台发动机：接口（httpx）和网页（Playwright）。

一、仓库名片

项目	内容
仓库	github.com/ywq2019/ai_...
默认分支	`master`
许可证	MIT（可学习、可修改、可商用，保留版权声明）
主要语言	Python（后端）+ Vue 3（管理界面）
打开方式	本机 `http://localhost:4000`，Docker 也是 4000 端口
设计文档	仓库根目录 `DESIGN.md`
作者社区帖	测试之家：平台介绍、测试之家：大升级说明

作者在设计文档里写过一个出发点，我翻译成人话就是：

能让 AI 做的事，人不做。

但「点哪个按钮」这种事，不能全靠 AI 猜。

这句话几乎能解释后面所有模块为什么长成现在这样。

二、先忘掉功能列表，用一条传送带理解它

打开 README，功能表会很长：文档生成用例、WebUI 录制、接口自动化、压测、Mock、测试计划、工作空间、渗透扫描......入门时不要从上到下记。

请先只看这条传送带：

text 复制代码

准备材料                     生成用例                    真正执行                 写出报告
需求文档 / curl / 页面操作     AI 起草正常/异常/边界        发 HTTP 或点浏览器        Excel / PDF
Swagger / 代码片段             人可以改、可以禁用           断言过没过                失败原因、建议

常说的的「写用例 → 跑用例 → 出报告」，在这里变成了软件流水线。差别只是：

生成可以交给大模型（也可以导入 Postman / HAR / 自己录）。
执行必须交给确定性的引擎，不能让模型口头说「我觉得通过了」。
报告是给同事和流水线看的交付物，不是聊天窗口里的一段话。

LangGraph 在这个仓库里的角色，也建议先这样理解：

它负责编排顺序（先解析、再生成、再执行、再出报告）。
设计文档写得很明确：核心测试引擎可以不依赖 Agent。LangGraph 是可选层。
所以学习顺序应该是：先搞懂执行引擎，再看 Agent 怎么把节点串起来。不要一上来就死磕图。

三、三台"发动机"

仓库对外宣传常说「WebUI + 接口」双引擎，后来又加了渗透。刚入门记住下面三块即可。Mock、计划、工作空间都是给这三块「加油」的配件。

1. 接口自动化：用程序代替你在浏览器里点「发送」

很多人第一次接触接口测试，其实已经做过手工版：打开开发者工具 Network，把请求 Copy as cURL，再在终端里重放。

这个仓库把同一件事做成了产品流程：

你把材料贴进去：Swagger / OpenAPI、curl、自然语言、实现代码、Postman / HAR。
AI 生成一组用例：正常流、异常流、边界值，并尽量带上断言。
执行引擎用 httpx 真正发 HTTP。
报告页能看到每条请求和响应，还能再复制回 curl；也可以导出 PDF。

它特意强调过几件「入门时特别容易误解」的事：

curl 不是装饰。粘贴后会拆出 method、URL、headers、body。设计文档第 23 节还专门修过一个坑：早期 POST 的请求体解析了却没喂给模型，生成出来的用例会缺 body。
生成质量靠探测，不靠瞎编。链路大致是：先对真实接口做探测 → 强制 JSON 输出 → 缺字段补全 → 模块名校验 → json_path 自检。你可以把它理解成「AI 写草稿，规则当质检员」。
接口天然能并发。和网页测试不同，发 HTTP 不依赖「当前页面点到哪了」，所以单独做成一台发动机，避免和浏览器状态搅在一起。

参数化是接口这条线真正能跑「登录 → 拿 token → 再调业务接口」的关键：

写法	含义（人话）
`{{gvar:token}}`	全局变量，跨项目还能用
`{{var:user_id}}`	这一次执行链里的局部变量
`{{uuid()}}` / `{{timestamp()}}`	执行时当场算出来的值
自定义脚本函数	签名、加密这类不好写死的东西

前置依赖、CSV 数据驱动、项目级 Bearer / Basic / API Key、Hosts 映射、HTTP/SOCKS 代理，都是为了让它能贴近真实测试环境，而不是只能打 httpbin 这种演示站。

如果你现在只会抄 curl： 这一台发动机就是你和仓库之间最近的桥。先学它，性价比最高。

2. WebUI 自动化：电脑替你点网页，但「点哪里」尽量由人录出来

网页自动化用的是 Playwright。新手最容易幻想的流程是：

把页面截图丢给大模型 → 模型直接写出 click('#btn-submit') → 永远能跑。

作者在 DESIGN.md 第 17 节把这个幻想否掉了：AI 生成的 selector 本质是猜的。SPA 动态 id、弹窗时序、条件渲染，随便一个对不上，脚本就红。

所以这个仓库的主线不是「AI 写脚本」，而是：

text 复制代码

AI 规划「测什么场景」
        ↓
人在真实页面上录一遍「怎么点」
        ↓
程序把录制结果健壮化（多候选选择器、自动补等待和断言）
        ↓
以后回放、出报告，必要时再导出 pytest 脚本

几个值得记住的设计，都是为了「下次还能跑」：

统一步骤模型 ActionStep：录制、AI、执行引擎说同一种话。字段包括动作类型、选择器、候选选择器列表、期望值、是否可选失败等。
选择器回退 ：录制时会按 data-testid > #id > name > aria-label ...... 生成多个候选；执行时按序探测，谁能点上用谁。
健壮化（step_hardener）：给选择器打 A/B/C/D 稳定性等级，动态数字 id、哈希 class 会标红；登录/提交后自动插等待和可见性断言。
登录态快照 ：批量跑之前先跑一遍登录，把 storage_state 存下来，后面每条用例直接恢复，不必每条都重新登。
控制流 ：支持 if/else 和 while 轮询。条件用白名单求值，不用危险的随意 eval。更复杂的 for/goto 在设计文档里规划了，但第一阶段会明确报错，避免「写了却静默不执行」。

一句话：AI 决定考哪些题，人演示标准答案怎么操作，机器负责以后反复批改。

对刚入门、当前任务以接口为主的同学：WebUI 可以后学。先知道「为什么不能让模型直接编点击脚本」，就已经值回票价。

3. 文档驱动用例：上传需求说明，按测试方法出一张用例表

这一块甚至可以先不执行，只解决「用例从哪来」。

你上传需求文档（支持常见办公格式和 HTML），平台会：

按模块切开，并行让模型写用例（有并发上限，避免一次把模型打爆）。
覆盖测试课本里那几招：等价类、边界值、判定表、场景法、错误推测、状态转换。
导出 Markdown / XMind / Excel（带优先级颜色）。
需求变了不是全盘推翻：AI 做 Diff，尽量只改变化的模块；旧用例默认保守保留。
还有「需求追踪矩阵」：从需求条目出发，看每条需求有没有被用例盖住，缺口可以再生成补充用例。

长文档怎么喂给模型？它用了 RAG：文档切成约 900 字一段（带重叠），生成时按模块检索相关段落。Docker 里用 PostgreSQL + pgvector；本机 SQLite 会降级成关键词匹配。这是为了避免「文档后半截根本没进提示词」。

入门提醒： 模型很会写「看起来像那么回事」的期望值。业务对不对，仍然要人对照真实系统核对。工具能加速起草，不能代替你懂业务。

四、配件箱：让流水线能进团队、进 CI

三台发动机之外，还有一组「看起来不像测试、但没有它们平台就只是玩具」的模块。

Mock

内置轻量 Mock，路径挂在 /mock/*，不走登录 JWT，方便前端先联调。按 method + path 匹配，可配延迟、记请求日志。

测试计划

把不同项目的接口用例拖进一条计划：登录 → 下单 → 查询，步骤之间共享变量。支持 Cron 定时（服务重启后会把启用的计划重新注册）。

CI/CD 的用法在 README 里写得很直白：先生成 webhook token，再在 Jenkins / GitHub Actions 里 POST .../trigger?token=...。这就是「合代码之前自动跑一轮接口」的挂钩，不必先学会整本 Jenkins。

工作空间

顶层隔离单元。AI 用例、WebUI 任务、接口项目、测试计划都挂在空间下。成员分 owner / member。WebSocket 进度也按空间隔离，避免你跑任务时刷到别人的进度条。

实时进度

生成、执行、压测、录制预览都是：HTTP 立刻返回，后台慢慢跑，WebSocket 推进度。断线也不全完，结果会落库，前端可以再拉。

渗透测试

它基于你已经有的接口用例，对已授权 目标做安全向扫描，并让 AI 写修复建议、导出 PDF。仓库自己用粗体写了声明：仅限内部授权、委托书、CTF 等场景，禁止打未授权目标。

学习这个仓库时，我的建议是：先跳过 pentest 目录。那不是入门测试的主线，也很容易踩合规红线。

五、几个真正值钱的设计决策

下面这些不是「又多了一个按钮」，而是作者在 DESIGN.md 里写明的取舍。

决策 1：UI 和接口拆成两台发动机

UI 依赖浏览器当前状态，步骤必须基本串行。
接口是无页面状态的 HTTP，天然并发。
硬揉成一套执行器，会互相污染。所以路由层下面是并列的两套引擎，上面再共用数据库、JWT、大模型、WebSocket。

决策 2：Agent 可选，引擎必达

「AI 测试」很容易做成：离开大模型整个系统都不能跑。这个仓库反过来：没有 Agent，录制回放和 httpx 执行仍然成立。模型挂了，你至少还能跑已有用例。这对真实工作很重要。

决策 3：Prompt 放 YAML，不写死在 Python 里

skills/prompts/ 下面按场景拆文件（文档用例、UI 场景规划、接口生成、代码分析）。改提示词不必改代码、不必重启（懒加载 + 缓存）。调「生成得像不像人写的测试用例」，应该先动 YAML，而不是先重构工程。

决策 4：废弃和禁用是两件事

字段	人话	跑不跑	算不算覆盖率
`enabled`	我暂时不想跑这条	前端可以不选它	仍算「设计过」
`deprecated`	需求变了，这条已经没意义	强制跳过	排除

很多测试平台把「先不跑」和「已经作废」塞进同一个开关，覆盖率数字会骗人。

决策 5：需求变更默认保守合并

重新生成最大的事故是：旧用例被全量覆盖，手工改过的断言全没了。这里的策略是：默认留旧的；只有功能点确认消失才标废弃；如果一下子废弃超过一半，会当成模型过激并重置。这是工程经验，不是模型能力。

决策 6：大模型统一走 HTTP，页面上切换

配置页会判断 Anthropic 格式还是 OpenAI 兼容格式。Claude、DeepSeek、GPT、Gemini、Ollama、以及各种兼容代理（国内很多团队会把千问一类模型接到兼容地址）都可以切。密钥配在环境变量或页面上，不要写进 Git。

决策 7：本机 SQLite，生产 PostgreSQL

本地 python main.py 用文件数据库，零配置。Docker Compose 用 PostgreSQL + pgvector。两边数据不互通。想认真用，官方更建议直接 Docker。

六、代码目录怎么读

不必一天就把每个文件看完。按「请求从哪进、活谁来干」记五层：

text 复制代码

你看见的网页          ui/          Vue 3 + Element Plus
对外 HTTP             api/routes/  FastAPI
真正干活的技能        skills/      生成、执行、录制、压测、RAG
可选的大脑            agent/       LangGraph 编排
基础设施              tools/       浏览器池、数据库、LLM 客户端、PDF

入门建议打开的顺序：

DESIGN.md
为什么这么做。比 README 功能表更重要。
skills/api_case_generator.py
curl / Swagger 怎样变成用例。
skills/api_executor.py
用例怎样真正发出去、断言怎样判。
skills/action_runner.py + skills/recorder.py
网页那台发动机。
agent/langgraph_agent.py
最后再看图是怎么串的（解析 → 生成 → 执行 → 报告，中间有路由）。

前端入口可以对照：AiCases.vue（文档用例）、ApiTest.vue（接口）、Execution.vue / Cases.vue（WebUI）、TestPlan.vue（计划）、LLM.vue（模型配置）。你即使不写 Vue，看页面名字也能把「产品功能」和「代码位置」对上。

技术栈速查（和 README 一致，便于对号入座）：

层	选型
后端	Python 3.11+、FastAPI、Uvicorn
Agent	LangGraph、LangChain
数据	SQLAlchemy；SQLite 或 PostgreSQL
浏览器	Playwright
接口执行	httpx
前端	Vue 3、Vite、Element Plus、ECharts
可选队列	ARQ + Redis
定时	APScheduler

注意：前端是 Vue 不是 React。如果你所在团队写 React，请把它当「管理面交互参考」，不要假设能整页搬过去。

七、想自己跑一份时，最小心智负担的路径

官方推荐 Docker。环境需要 Docker 20.10+（Compose v2）。克隆后重点改 .env.docker：

SECRET_KEY：自己生成，不要用仓库默认值。
POSTGRES_PASSWORD：同时改 DATABASE_URL 里的密码。
AI_API_KEY / AI_API_URL / AI_MODEL：也可以部署后再到「大模型配置」页填写。

然后：

bash 复制代码

git clone https://github.com/ywq2019/ai_test_agent.git
cd ai_test_agent
docker compose up -d

浏览器打开 http://localhost:4000。默认账号见官方 README（登录后立刻改密码）。

安全与礼貌：

只打你自己的 Mock、公开演示接口，或你明确有权测试的环境。
不要把工作密钥、Cookie、内网 curl 贴到公共仓库或社交平台。
默认 admin 密码属于演示用途，对外网暴露 4000 端口前必须改密、改密钥。

本机无 Docker 时：Python 3.11+、Node 18+，复制 .env.docker 为 .env，装依赖、装 Chromium、构建前端，再 python main.py。细节以仓库 README「本地启动」为准------版本会变，本文不代替官方步骤。

八、这个仓库适合谁，不适合谁

适合

想建立「生成 → 执行 → 报告」完整心智模型的测试新人。
正在学接口自动化，已经会 Copy as cURL，想看看「下一步产品长什么样」。
对 LangGraph / FastAPI / Playwright 感兴趣，需要一个带真实业务形状的样本，而不是只有 50 行 demo。
团队想给测试平台找对照实现：变量池、计划编排、webhook、工作空间隔离。

不适合（或至少不要一上来就这样用）

指望 star 数量当工业标准。它是个人维护的完整工具，不是测试行业规范。
把整仓部署进公司，替代现有业务平台。业务断言、账号体系、数据形态都对不上。
用渗透模块去扫未授权站点。
第一周并行打开全部模块。体量很大，会把主线冲掉。

我自己的判断很简单：当教练、当样板，可以打高分；当开箱即用的公司交付物，分数会掉下来。 学它的流水线和设计决策，比复刻每一个页面更重要。

九、给刚入门测试同学的学习路线（按周，不要并行）

下面是我给自己排的顺序，你可以按实际情况压缩，但尽量不要把 1 和 4 对调。

第 1 周：先当用户，不当开发

通读 README 的功能表，对照本文第三节，能讲出三台发动机的差别。
精读 DESIGN.md 的开头架构、接口生成（约第八、二十三节）、以及「AI 只做测什么」（第十七节）。
用自己熟悉的一个公开 HTTP 接口（或仓库自带 Mock）走通：贴 curl → 看生成了哪些用例 → 执行 → 打开报告。
练习一件事：指出 AI 写错的断言。这比「生成成功」更重要。

第 2 周：只深挖接口引擎

对照 api_case_generator.py / api_executor.py，画一张自己的图：输入有哪些、中间质检有哪些、输出落在哪。
搞懂三种变量：全局、局部、函数占位符。自己设计一条「先登录，再带 token 调业务」的假想链路（可以用 Mock）。
看测试计划 + webhook 小节，知道以后怎么挂到 CI，但先不必真配 Jenkins。

第 3 周：网页自动化只学「为什么这样」

录一个极短流程（打开页面、填一个框、点一下）。
在步骤编辑器里看选择器等级，尝试理解为什么有的是 D 级。
读 ActionStep 字段，知道「录制结果」和「AI 场景规划」不是同一份东西。

第 4 周及以后：才碰 Agent 和二次开发

读 langgraph_agent.py，只回答：节点叫什么、状态里大概有哪些字段、失败时怎么走。
如果要做自己的测试 Agent：抄状态结构 （用例、结果、报告分开），抄生成与执行分离，不要抄成巨石应用。
验证门继续用规则（状态码、关键业务字段），不要让模型自己宣布系统通过。

十、常见误解

「有了 AI 平台就不用懂业务。」

错。生成器不知道你们两个名字很像的页面是不是同一条业务线。期望值必须人定。
「这个 GitHub 仓库等于被测系统的 openapi.json。」

错。它是测试工作台 。openapi.json 是被测系统自己的说明书。工作台会读别人的 OpenAPI，它自己不是那份说明书。
「LangGraph 就是测试本身。」

错。测试本身是请求、点击、断言。LangGraph 只是把步骤排好。
「模型切换了，提示词不用管。」

不完整。不同模型听话程度差很多。这个仓库把 Prompt 抽到 YAML，就是为了让你按模型去调，而不是怪框架。
「星少就没有阅读价值。」

对学习而言，完整的设计说明 + 能跑的代码，往往比只有星数的空壳更有用。但也不要把它神化成唯一答案。

十一、声明、致谢、延伸阅读

项目版权与实现属于仓库作者及贡献者。本文是独立学习分享，如有理解偏差，以仓库当前代码和 DESIGN.md 为准。
许可证为 MIT，二次使用请保留原许可证与版权声明。
再次强调：渗透与扫描类能力仅用于授权范围。

延伸阅读（都短，建议按序）：

仓库 README：安装、功能表、默认端口。
仓库 DESIGN.md：设计决策（强烈建议）。
测试之家两篇作者帖：可以看到产品是怎么迭代「业务痛点」的。
Playwright / httpx 官方文档：执行引擎那一层的基础。
你自己的浏览器 Network → Copy as cURL：这是接口发动机的日常燃料。

附录 A：一张图，发给只会问「这仓库干啥」的同事

text 复制代码

          ┌─────────────┐
文档/curl │  生成用例    │  AI 起草 + 规则质检
页面录制  │  （可人工改） │
          └──────┬──────┘
                 ▼
          ┌─────────────┐
          │  执行引擎    │  httpx 或 Playwright
          │  断言过/不过 │
          └──────┬──────┘
                 ▼
          ┌─────────────┐
          │  Excel/PDF  │  给人看，也可给 CI 看
          │  报告        │
          └─────────────┘
                 ▲
                 │  可选：LangGraph 负责排队和路由

引擎可以参考，业务断言要自己写。

（完）

写作时仓库默认分支为 master，信息核对自公开 README 与 DESIGN.md。若仓库日后大改，请以 GitHub 最新文件为准。