如果觉得有帮助，欢迎在 GitHub 上点个 ⭐ 支持！
🤖 WebQA Agent 是全自动网页评估测试 Agent，具备多模态网页理解、智能生成测试用例、精准执行的核心能力，一键完成性能、功能与交互体验的全面测试评估 ✨ 支持 GUI/CLI 直接使用，且支持 OpenClaw Skill 调用
WebQA-Agent 提供两种测试模式，满足不同场景需求: 🤖 自动探索模式和 📋 执行模式
| 能力 | 🤖 自动探索模式 (Generate模式) | 📋 执行模式 (Run模式) |
|---|---|---|
| 核心特性 | AI 自主探索 -> 动态生成 -> 精确执行 | 依据指令执行和预期验证 |
| 适用场景 | 新功能探索、全面质量保障 | 适合可重复、可回归的测试场景 |
| 用户输入 | 极简：只需 URL 或一句话业务目标 | 结构化：简单的自然语言步骤描述 |
| 优势 | 具备反思能力，自适应 UI 变化；配置功能/性能/安全/UX 评估，提供全面质量保障 | 结果稳定可预期，摆脱繁琐的Selector维护；实时监控 Console/Network 状态 |
使用与部署：支持 CLI 命令行运行，可参考 CLI 使用说明；同时支持以完整前后端形态部署（Local / Docker / K8s），通过 Web 界面进行可视化管理。详见 全栈部署。
默认工具（始终启用）：
- UI 操作: 浏览器交互（点击、输入、导航）
- UI 断言: 状态验证
- UX 验证: 文本错误检查、布局分析
自定义工具（可选，通过配置启用）：
- 性能测试: 基于 Lighthouse 的性能测试
- 安全测试: Nuclei 漏洞扫描
- 链接检测: 动态链接发现
在 config.yaml 中启用自定义工具：
test_config:
custom_tools:
enabled:
- lighthouse
- nuclei
您可以根据需求选择 🛠️ 命令行快速上手 或 🖥️ 全栈部署 (Web 管理平台)。
推荐使用 uv (Python>=3.11) 安装:
# 1) 创建项目并安装包
uv init my-webqa && cd my-webqa
uv add webqa-agent
# 2) 安装浏览器（必需）
uv run playwright install chromium
# 3) 自动探索模式 (Generate)
uv run webqa-agent init -m gen # 初始化配置，编辑 config.yaml 填入 URL 和 API Key
uv run webqa-agent gen # 启动 AI 自动测试
# 4) 执行模式 (Run)
uv run webqa-agent init -m run # 初始化配置，编写自然语言测试用例
uv run webqa-agent run # 启动测试执行详见 CLI 使用说明 获取更多 CLI 参数。
如果您需要可视化界面、测试管理和执行历史，请使用 Docker Compose 一键启动：
git clone https://github.com/MigoXLab/webqa-agent.git
cd webqa-agent/deploy/docker-compose
cp .env.example .env
# 编辑 .env 文件，填入您的 LLM API Key
./start.sh启动后访问
http://localhost。其他部署方式请查看 全栈部署。
WebQA Agent 提供简洁的命令行工具，支持初始化、自动探索、用例执行及 Web UI 启动。
| 命令 | 说明 | 常用参数 |
|---|---|---|
init |
初始化配置文件 | -m <gen/run>: 指定模式；-o <path>: 输出路径；--force: 强制覆盖 |
gen |
自动探索模式：AI 自动生成并执行用例 | -c <path>: 指定配置文件；-w <n>: 并发 Worker 数 |
run |
执行模式：运行 YAML 定义的测试用例 | -c <path/dir>: 指定文件或文件夹；-w <n>: 并发 Worker 数 |
示例：
# 初始化 Run 模式配置
webqa-agent init -m run
# 以 4 并发运行指定目录下的所有测试用例
webqa-agent run -c ./my_cases -w 4- 性能测试（Lighthouse）：
npm install lighthouse chrome-launcher（需 Node.js ≥18） - 安全测试（Nuclei）：
brew install nuclei # macOS
nuclei -ut # 更新模板
# Linux/Windows: https://github.com/projectdiscovery/nuclei/releases配置文件需包含 test_config 字段，用于定义需要执行的测试类型。
- 业务目标: 指定测试的业务目标，以指导 AI 规划测试重点和覆盖范围。
- 自定义工具: 可选启用性能（Lighthouse）、安全（Nuclei）、按钮检查、链接检测等工具。
- 动态步骤生成: 启用后，在执行过程中检测到新的 UI 元素时，会自动生成额外的测试步骤。
- 过滤模型: 配置一个轻量级模型，用于预过滤页面元素，从而提高规划效率。
更多教程，请参考 docs/MODES&CLI_zh-CN.md
target:
url: https://example.com # 需要测试的网站 URL
description: 网站质量保证测试
test_config:
business_objectives: 测试搜索功能，生成3个测试用例
custom_tools: # 可选：启用自定义测试工具（通过 step_type）
enabled:
# - lighthouse # Lighthouse 性能测试
# 需要：npm install lighthouse chrome-launcher（本地，推荐）
# 或：npm install -g lighthouse chrome-launcher（全局）
# - nuclei # Nuclei 安全扫描
# 需要：go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
# 或从以下地址下载：https://github.com/projectdiscovery/nuclei/releases
# - traverse_clickable_elements # 可点击元素遍历测试
# - detect_dynamic_links # 动态链接发现和验证
llm_config: # LLM 配置，支持 OpenAI、Anthropic Claude、Google Gemini 以及 OpenAI 兼容格式模型（如豆包、通义千问等）
model: gpt-5.4 # 主模型
filter_model: gpt-5-mini # 轻量级模型用于元素过滤（可选）
api_key: your_api_key # 或通过环境变量设置 (OPENAI_API_KEY)
base_url: https://api.openai.com/v1 # 可选，API 端点。对于 OpenAI 兼容格式模型（豆包、通义千问等），设置为对应的 API 端点
browser_config:
headless: False # Docker 环境自动设为 True
language: en-US
report:
language: en-US # zh-CN 或 en-USRun 模式配置文件需包含 cases 字段，用于定义具体的测试用例。
- 多模态 AI 交互式能力：使用
action描述页面上可见的文字、图片或相对位置。支持浏览器操作：点击、悬停、输入、清空、键盘按键、页面滚动、鼠标移动和滚轮滚动、文件上传、拖拽、等待等；以及页面操作：跳转url、页面后退。 - 多模态 AI 验证能力：使用
verify，确保 Agent 没“跑偏”。校验页面符合预期：视觉内容确认、URL 与路径校验、组合图片和页面元素验证等。 - 全链路自动监控：获取浏览器的
Console日志和Network请求状态，同时支持配置ignore_rules来忽略已知的浏览器 console 和 network 错误。
更多教程和测试用例编写规范，请参考 docs/MODES&CLI_zh-CN.md
target:
url: https://example.com # 目标网站 URL
llm_config: # LLM 配置
api: openai
model: gpt-5-mini
api_key: your_api_key_here
base_url: https://api.openai.com/v1
browser_config:
viewport: {"width": 1280, "height": 720}
headless: False # Docker 环境自动设为 True
language: en-US
# cookies: /path/to/cookie.json
ignore_rules: # 忽略规则配置（可选）
network: # 网络请求忽略规则
- pattern: ".*\\.google-analytics\\.com.*"
type: "domain"
console: # 控制台日志忽略规则
- pattern: "Failed to load resource.*favicon"
match_type: "regex"
- pattern: "Warning:"
match_type: "contains"
cases: # 测试用例列表
- name: 图片上传 # 用例名称
steps: # 测试步骤
- action: 上传图标是输入框内的图片图标，位于百度搜索按钮旁边，用于上传文件
args:
file_path: ./tests/data/test.jpeg
- action: 等待图像上传
- verify: 验证输入字段是否显示张开的手掌/手图标图像
- action: 输入"图片中有多少根手指？"在搜索输入框中，然后按Enter键，等待2秒测试报告生成在 reports/ 目录下，打开 HTML 文件即可查看详细结果。
WebQA Agent 支持自定义工具开发，满足特定领域的测试需求。
| 文档 | 描述 |
|---|---|
| 自定义工具开发 | 自定义工具开发快速参考 |
| LLM 上下文文档 | AI 辅助开发的完整指南，可用于氛围编程 |
欢迎贡献！查看现有工具示例获取参考。
如果团队需要一个持续使用的 Web 管理平台（测试管理、定时任务、执行历史），可以部署完整的前后端服务。我们支持三种部署方式：
| 方式 | 适用场景 | 参考文档 |
|---|---|---|
| 本地开发 | 个人开发调试 | deploy/README_zh-CN.md |
| Docker Compose | 单机部署 / 团队试用 | deploy/README_zh-CN.md |
| Kubernetes | 生产集群 | deploy/k8s/README.md |
💡 扩展内部逻辑： WebQA Agent 支持根据团队基础设施扩展内部逻辑（如接入内部的 SSO 单点登录、OSS 对象存储、内部大模型等），您可以自由进行定制和二次开发。deploy/README_zh-CN.md
注意： 当前 Web 管理平台仅提供中文界面。
- 交互与可视化：实时展示推理过程
- Gen模式能力扩展：更多评估维度集成
- Tool Agent上下文接入，更全面更精确的执行
- natbot: 通过GPT-3驱动浏览器
- Midscene.js：Web、Android、自动化和测试的AI Operator
- browser-use：用于浏览器控制的AI Agent
该项目采用 Apache 2.0 开源许可证