Web UI 使用¶
YuanTest Playwright 提供了强大的 Web Dashboard，让测试管理更加直观高效。
启动 Dashboard¶
# 默认端口 5274
yuantest ui
# 自定义端口
yuantest ui --port 8080
# 指定报告和数据目录
yuantest ui --port 5274 --output ./test-reports --data ./test-data
# 不自动打开浏览器
yuantest ui --no-open
启动后访问 http://localhost:5274 查看可视化界面。
Dashboard 功能介绍¶
1. 概览页面¶
Dashboard 首页展示关键指标：
- 测试运行统计：总运行次数、通过率趋势
- Flaky 测试统计：不稳定测试数量和占比，按分类（Flaky/Broken/Regression/Monitor）分布
- 执行时间趋势：平均执行时间变化
- 最近运行记录：快速查看最近的测试结果
- 健康度评分：A/B/C/D/F 等级，4 维评分（稳定性/趋势/可恢复性/可预测性）
2. Test Runs（测试运行记录）¶
查看所有历史测试运行：
- 运行列表：显示每次运行的详细信息
- 筛选和搜索：按状态、时间筛选测试运行
- 运行详情：点击查看完整的测试结果
- 报告下载：下载 HTML 或 JSON 格式的报告
- 测试重跑：支持重跑单个测试或批量重跑
3. Flaky Tests（不稳定用例管理）¶
智能管理不稳定用例，提供 6 种分类标签：
| 分类 | 含义 |
|---|---|
| Flaky | 真正的间歇性失败 |
| Broken | 持续失败的真实 Bug |
| Regression | 新引入的回归 |
| Monitor | 需要关注，可能发展为 Flaky |
| Stable | 基本稳定 |
| Insufficient Data | 数据不足，无法判定 |
功能：
- 自动检测：基于加权失败率和 Wilson 置信区间自动识别 Flaky 测试
- 分类标签：每个 Flaky 测试显示分类（Broken/Flaky/Regression/Monitor）
- 加权失败率：展示时间衰减加权失败率，最近的运行权重更高
- 根因分析：7 种根因类型（timing/data_race/environment/external_service/test_order/resource_leak/assertion_flaky）
- 一键隔离：隔离不稳定的测试，支持 4 级隔离（none/monitor/soft_quarantine/hard_quarantine）
- 释放测试：将隔离的测试重新加入测试套件
- 趋势追踪：查看测试通过率趋势方向（improving/stable/degrading/volatile）
4. Failure Analysis（失败分析）¶
深度分析失败原因：
- 自动分类：智能识别超时、断言失败、元素未找到、网络错误、Frame 错误、认证错误等 7 类
- 失败统计：显示各类失败的数量和占比
- 修复建议：提供针对性的失败修复建议
- 历史趋势：追踪失败原因的变化趋势
- AI 诊断：一键触发 AI 智能分析
5. 实时进度¶
测试执行时实时监控：
- 进度条：显示测试执行进度
- 实时日志：查看测试输出日志
- 测试状态：实时更新通过、失败、跳过的测试数量
- 当前测试：显示正在执行的测试
- Flaky 检测推送：实时推送 Flaky 测试检测结果
6. Agent 代理面板¶
Agent 代理面板提供 AI 驱动的测试创建和修复能力：
- 测试规划 - 输入功能描述生成结构化测试计划
- 支持引用参考测试以保持代码风格一致
- 支持引用 PRD 文档以对齐需求
- 自动保存计划为 Markdown 文件
- 测试生成 - 将测试计划转换为 Playwright TypeScript 代码
- 使用现代定位器（getByRole、getByText 等）
- 生成独立可运行的测试场景
- 支持自定义输出目录
- 测试修复 - 分析并修复失败测试
- 多轮修复，逐步优化
- 生成带置信度评分和统一 Diff 的补丁
- 可选自动应用模式，即时修复
- 安全：补丁仅应用于项目根目录内的文件
- 修复历史 - 查看历史修复操作
- 追踪修复成功/失败率
- 显示补丁详情和应用状态
- 项目上下文 - 自动检测的项目信息
- 从 package.json 检测技术栈
- 解析 Playwright 配置（baseURL、超时、视口）
- 自动发现测试 Fixtures
Web UI 执行测试¶
通过界面执行测试¶
- 选择测试目录
- 在 Dashboard 左侧点击"设置"
- 输入测试目录路径
-
系统会自动扫描测试文件
-
选择测试文件
- 在测试列表中勾选要执行的测试
- 支持按文件、按描述块、按单个测试选择
-
支持搜索和筛选
-
配置执行参数
| 参数 | 说明 | 默认值 |
|---|---|---|
| 浏览器 | 选择 Chromium / Firefox / WebKit（多选） | chromium |
| 重试次数 | 设置失败重试次数 | 0 |
| 超时时间 | 设置测试超时时间（毫秒） | 30000 |
| Worker 数量 | 设置并行 Worker 数量 | 1 |
| 分片数量 | 设置测试分片数 | 1 |
| Base URL | 设置测试基础 URL |
- 执行测试
- 点击"运行测试"按钮
- 实时查看测试进度
-
查看控制台输出
-
查看测试报告
- 测试完成后自动跳转到报告页面
- 查看详细的测试结果
- 查看失败测试的错误信息和堆栈
- 查看 Trace、截图、视频等附件
AI 诊断功能¶
单次诊断¶
- 在测试详情页面点击"AI 诊断"按钮
- 系统自动收集上下文信息（源代码、截图、控制台日志、堆栈跟踪、环境信息、历史数据）
- 匹配 Playwright 知识库中的已知错误模式
- LLM 进行分析并返回诊断结果
- 查看诊断摘要、根因、修复建议、置信度
流式诊断¶
- 点击"AI 诊断（流式）"按钮
- 实时查看 AI 推理过程
- 支持 Agent 多轮推理模式（LLM 可主动读取源码、查询历史）
- 查看推理步骤和工具调用
诊断结果¶
诊断结果包含：
| 字段 | 说明 |
|---|---|
| 摘要 | 失败原因概述 |
| 根因 | 根本原因分析 |
| 修复建议 | 可操作的修复步骤 |
| 置信度 | 校准后的置信度（0-1） |
| 分类 | timeout/selector/assertion/network/frame/auth/unknown |
| 代码 Diff | 建议的代码修改（unified diff 格式） |
| 文档链接 | 关联的 Playwright 官方文档 |
| 推理步骤 | Agent 推理过程（仅 Agent 模式） |
| 关联失败 | 同根因的其他失败测试 |
批量聚类诊断¶
当同一次运行中有多个测试失败时：
- 系统自动识别相似错误模式
- 对代表性失败调用 LLM
- 其他失败引用同一诊断
- 标注"影响 N 个测试的共因失败"
错误模式管理¶
查看内置模式¶
系统内置 7 大类 30+ 个 Playwright 错误模式：
| 类别 | 典型模式 |
|---|---|
| TimeoutError | 元素未出现、导航超时、API 响应超时、内存溢出、并发冲突 |
| SelectorError | 元素不存在、选择器歧义、iframe 内选择器、Headless 环境差异 |
| AssertionError | 文本不匹配、可见性断言、属性断言、数据校验异常、状态不一致 |
| NetworkError | 请求失败、CORS、DNS 解析失败、环境配置错误、依赖缺失 |
| FrameError | Frame detached、跨 Frame 操作 |
| AuthError | Token 过期、未登录重定向 |
| 其他 | 竞态条件、环境配置差异、Headless 模式差异、并发执行冲突 |
添加自定义模式¶
- 在错误模式管理页面点击"添加模式"
- 填写模式名称、匹配正则、分类
- 保存后立即生效，后续诊断会匹配自定义模式
- 自定义模式标注
[custom]标记
LLM 配置¶
配置 API Key¶
- 在 Dashboard 设置页面找到"LLM 配置"
- 填写以下信息：
| 配置项 | 说明 | 示例 |
|---|---|---|
| API Key | LLM 服务的 API Key | sk-xxx |
| Base URL | LLM 服务地址 | https://api.openai.com/v1 |
| Model | 模型名称 | gpt-4 |
| Max Tokens | 最大输出 Token 数 | 4096 |
| Temperature | 生成温度 | 0.3 |
- 点击"保存"
兼容的 LLM 服务¶
支持所有 OpenAI API 兼容接口：
- OpenAI：GPT-4、GPT-3.5 等
- Ollama：本地部署的开源模型
- vLLM：高性能推理服务
- Azure OpenAI：微软 Azure 托管的 OpenAI 服务
测试连接¶
- 配置完成后点击"测试连接"
- 系统发送测试请求验证配置
- 显示连接状态（绿色/黄色/红色）
参数配置面板¶
参数配置面板分为两个独立对话框，分别从对应的卡片右上角设置图标按钮打开。
不稳定用例判定参数¶
点击"不稳定用例"卡片右上角的 ⚙ 设置图标按钮，打开不稳定用例判定参数对话框，可调整以下参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 最低运行次数 | 5 | 低于此数不判定 |
| Flaky 阈值 | 0.3 | 加权失败率 ≥ 此值判定为 Flaky |
| Monitor 阈值 | 0.1 | 加权失败率 ≥ 此值判定为 Monitor |
| Stable 阈值 | 0.05 | 加权失败率 < 此值判定为 Stable |
| 高风险阈值 | 0.5 | 加权失败率 ≥ 此值触发高优先级 |
| 连续失败阈值 | 5 | 连续失败次数 ≥ 此值判定为 Broken |
| 回归窗口 | 5 | 回归检测窗口大小 |
| 时间衰减率 | 0.1 | 指数衰减率 |
| 置信水平 | 0.95 | Wilson 置信区间置信水平 |
| 自动释放通过次数 | 3 | 软隔离自动释放所需连续通过次数 |
已隔离用例判定参数¶
点击"已隔离用例"卡片右上角的 ⚙ 设置图标按钮，打开已隔离用例判定参数对话框，可调整以下参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 软隔离阈值 | 0.15 | 加权失败率 ≥ 此值进入软隔离 |
| 硬隔离阈值 | 0.4 | 加权失败率 ≥ 此值进入硬隔离 |
| 隔离预算比例 | 0.2 | 最多隔离 20% 的测试 |
| 硬隔离释放通过次数 | 5 | 硬隔离自动释放所需连续通过次数 |
| 隔离过期天数 | 30 | 隔离自动过期天数 |
| 过期后降级 | true | 隔离过期后自动降级而非释放 |
重置为默认值¶
每个对话框中均有"重置为默认值"按钮，点击后将对应配置节从 user-preferences.json 中移除，恢复使用默认值。
测试历史查看¶
- 在测试详情页面点击"历史记录"
- 查看该测试的完整运行历史
- 包含每次运行的：状态、持续时间、错误信息、截图
- 显示稳定性统计：通过率、总运行次数、最近通过/失败时间
健康度仪表盘¶
Dashboard 提供测试健康度概览：
- 整体健康评分：A/B/C/D/F 等级
- 4 维评分：
- 稳定性（权重 35%）：基于加权失败率
- 趋势（权重 25%）：基于通过率趋势方向
- 可恢复性（权重 20%）：基于失败后恢复能力
- 可预测性（权重 20%）：基于预测模型准确度
- Flaky 测试分布：按分类统计
- 高风险测试列表：预测可能失败的测试
高级功能¶
Flaky 测试隔离¶
- 在 Flaky Tests 页面查看不稳定用例列表
- 点击测试旁边的"隔离"按钮
- 系统根据加权失败率自动选择隔离级别：
- Monitor：仅监控，不跳过
- Soft Quarantine：隔离但保留重试
- Hard Quarantine：完全跳过
- 被隔离的测试不会在后续运行中执行
- 可以在"已隔离用例"中查看和管理
失败分析¶
- 在 Test Runs 页面点击某次运行
- 切换到"失败分析"标签
- 查看失败原因分类和统计
- 查看每个失败测试的详细信息和建议
Trace 查看¶
- 在测试详情页面点击"Trace"按钮
- 自动打开 Playwright Trace Viewer
- 查看测试执行的完整时间线
- 查看每个步骤的截图和 DOM 快照
产物管理¶
- 截图：自动收集失败测试的截图
- 视频：自动收集失败测试的视频
- Trace：自动收集测试执行轨迹
- 统一存储：所有产物统一存储在
test-reports/目录
因果图¶
- 在 Dashboard 中查看因果图
- 展示测试之间的依赖关系和关联失败
- 识别根因节点（infrastructure/external_service/shared_state）
- 影响分析：查看修复某个测试会影响哪些其他测试
REST API¶
Dashboard 提供 RESTful API，方便与其他系统集成。完整的 API 文档请参考 DashboardServer API 参考。
常用端点：
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | /api/v1/health |
健康检查 |
| GET | /api/v1/stats |
整体统计 |
| GET | /api/v1/runs |
运行列表 |
| POST | /api/v1/runs |
启动测试运行 |
| GET | /api/v1/flaky |
Flaky 测试列表 |
| POST | /api/v1/diagnosis |
AI 诊断 |
| POST | /api/v1/diagnosis/stream |
AI 诊断（流式） |
| GET | /api/v1/preferences |
用户偏好 |
| POST | /api/v1/preferences |
保存偏好 |