🚀 yuantest-playwright：让 Playwright 测试管理更优雅的利器✅ 智能编排 —— 方差感知

一款强大的 Playwright 测试编排器、执行器和报告器，提供 CLI 命令行工具和 Web Dashboard 可视化界面

📌 目录

前言
项目介绍
核心架构
智能测试编排
Flaky 测试全链路治理
AI 智能失败诊断
实时报告与可视化
视觉回归测试
注解与标签系统
Web UI
快速上手
实战演示
编程 API
对比优势
总结

前言

在 E2E 测试的道路上，你是否遇到过这些痛点？

🔥 测试套件越来越大，执行时间越来越长，CI 等待时间令人抓狂
😵 Flaky 测试像幽灵一样，时好时坏，难以捉摸，严重影响团队效率
📊 测试报告分散，缺乏统一的历史趋势分析，无法量化测试质量
🐛 测试失败后，定位问题耗时耗力，缺乏有效的失败分析工具
🔄 CI/CD 流程中，测试编排效率低下，资源利用率不高

如果你有以上任何困扰，那么 yuantest-playwright 可能正是你需要的解决方案！

项目介绍

yuantest-playwright 是一个强大的 Playwright 测试编排器、执行器和报告器，提供 CLI 命令行工具和 Web Dashboard 可视化界面，帮助团队更高效地管理和分析 E2E 测试。

它的核心理念是 "零学习曲线、零迁移成本、纯 Playwright 生态"——所有 CLI 参数与 Playwright CLI 完全一致，不依赖任何 Playwright 内部 API，用户可随时无缝切换回原生 Playwright。

npm install -g yuantest-playwright

核心架构

在深入每个功能之前，先了解 yuantest-playwright 的整体架构设计：

flowchart TB
    subgraph 用户层
        CLI[CLI 命令行]
        DASH[Web Dashboard]
        API[REST API]
    end

    subgraph 核心引擎
        ORC[编排器<br/>智能分片 · 负载均衡]
        EXE[执行器<br/>Playwright CLI 集成]
        RPT[报告器<br/>HTML · JSON · 实时推送]
    end

    subgraph 智能分析
        FLAKY[Flaky 管理器<br/>分类 · 根因 · 隔离 · 预测]
        DIAG[AI 诊断引擎<br/>LLM 推理 · 知识库 · 聚类]
        VIS[视觉测试<br/>像素对比 · 基线管理]
    end

    subgraph 辅助系统
        ANN[注解系统<br/>@skip @slow @flaky]
        TAG[标签系统<br/>三重过滤]
        TRACE[Trace 管理<br/>截图 · 视频 · 产物]
    end

    subgraph 基础设施
        WS[WebSocket 实时推送]
        STORE[存储抽象层<br/>内存 · 文件系统]
        CACHE[LRU/TTL 缓存]
        I18N[国际化 中/英]
    end

    CLI --> ORC
    DASH --> API
    API --> EXE

    ORC --> EXE
    EXE --> RPT
    EXE --> FLAKY
    RPT --> WS
    WS --> DASH

    FLAKY --> DIAG
    EXE --> VIS
    EXE --> TRACE
    ORC --> ANN
    ORC --> TAG

    FLAKY --> STORE
    DIAG --> CACHE
    RPT --> STORE

    style ORC fill:#4ecdc4,color:#fff
    style EXE fill:#45b7d1,color:#fff
    style FLAKY fill:#e74c3c,color:#fff
    style DIAG fill:#9b59b6,color:#fff
    style WS fill:#f39c12,color:#fff

整个系统围绕 编排 → 执行 → 分析 → 反馈 的闭环设计，每个模块各司其职又紧密协作。

智能测试编排

当测试套件从几十个增长到数百甚至上千个时，如何高效地分配执行资源就成了关键问题。yuantest-playwright 的编排器提供了业界领先的 方差感知智能分片 算法。

传统分片 vs 智能分片

传统分片通常采用简单的轮询（Round-Robin）分配，看似每个分片分到相同数量的测试，但实际上：

传统轮询分片：
  分片1: [测试A(2s), 测试B(3s), 测试C(2s)] = 7s  ✅
  分片2: [测试D(30s), 测试E(25s), 测试F(20s)] = 75s  ❌ 等待时间爆炸！

智能分片：
  分片1: [测试D(30s), 测试A(2s), 测试B(3s)] = 35s
  分片2: [测试E(25s), 测试F(20s), 测试C(2s)] = 47s
  → 最大分片耗时从 75s 降到 47s，效率提升 37%！

三阶段智能分片算法

flowchart TD
    A[测试文件列表] --> B[估算执行时间]
    B --> C{运行次数 ≥ 3?}

    C -- 是 --> D[EMA 指数移动平均<br/>α = 0.3<br/>置信度由 CV 决定]
    C -- 1~2次 --> E[简单平均 +<br/>同类推断加权]
    C -- 0次 --> F{同目录有历史?}
    F -- 是 --> G[同类测试中位数推断<br/>置信度 0.3]
    F -- 否 --> H[默认超时时间<br/>置信度 0.1]

    D --> I[第一阶段:<br/>高风险测试优先分散]
    E --> I
    G --> I
    H --> I

    I --> J[风险评分 = CV×0.6 + 1-置信度×0.4<br/>风险 > 0.4 → 高风险]
    J --> K[高风险测试分配到<br/>方差累计最小的分片<br/>多样性惩罚避免集中]

    K --> L[第二阶段:<br/>稳定测试 LPT 贪心分配]
    L --> M[按预估时间降序<br/>选择有效负载最小的分片<br/>effectiveLoad = load + 0.5×√variance]

    M --> N[第三阶段:<br/>两两交换重平衡]
    N --> O[最多 10 轮迭代<br/>最大/最小负载差 > 1% 时触发<br/>交换或移动测试减少最大负载]

    O --> P[输出分片方案]

    style D fill:#2ecc71,color:#fff
    style J fill:#e74c3c,color:#fff
    style L fill:#3498db,color:#fff
    style N fill:#f39c12,color:#fff

反馈闭环校准

分片不是一次性的——系统会持续学习和校准。每次分片执行完成后，对比预测耗时与实际耗时，自动调整校准因子：

校准因子 = 旧因子 × (1 - 0.2) + 实际/预测 × 0.2

校准因子被限制在 [0.5, 2.0] 范围内，所有估算值最终都会乘以该校准因子，确保预测越来越准。

Flaky 测试全链路治理

这是 yuantest-playwright 最具竞争力的杀手级功能。不同于其他工具仅提供简单的重试或跳过，yuantest-playwright 构建了一套从检测到修复验证的 全链路治理体系。

治理全景图

flowchart LR
    A[测试执行] --> B[结果记录]
    B --> C[智能分类<br/>Wilson 置信区间]
    C --> D[根因分析<br/>7 种根因]
    D --> E[分级隔离<br/>根因感知重试]
    E --> F[执行器集成<br/>自动过滤]

    C --> G[关联分析<br/>Jaccard 共现聚类]
    C --> H[趋势追踪<br/>CUSUM 变点检测]
    C --> I[健康评分<br/>A-F 等级]
    H --> J[预测性检测<br/>多信号融合]

    D --> K[因果依赖图<br/>根因定位]

    F --> L[自动释放/降级]
    L --> A

    G --> M[Dashboard 可视化]
    I --> M
    J --> M
    K --> M

    style C fill:#4ecdc4,color:#fff
    style D fill:#e74c3c,color:#fff
    style E fill:#f39c12,color:#fff
    style J fill:#9b59b6,color:#fff

智能分类器：6 种精准分类

传统做法只看"是否有时通过有时失败"，但实际情况远比这复杂。yuantest-playwright 基于 Wilson 置信区间 和 时间衰减加权失败率，将测试细分为 6 种类型：

flowchart TD
    A[测试结果输入] --> B{运行次数 ≥ 5?}
    B -- 否 --> C[insufficient_data<br/>数据不足]
    B -- 是 --> D{连续失败 ≥ 5 次?}
    D -- 是 --> E[broken<br/>已损坏]
    D -- 否 --> F{近期失败率 ≥ 60%<br/>且历史失败率 ≤ 20%?}
    F -- 是 --> G[regression<br/>回归]
    F -- 否 --> H{加权失败率 ≥ 0.3?}
    H -- 是 --> I[flaky<br/>不稳定]
    H -- 否 --> J{加权失败率 ≥ 0.1?}
    J -- 是 --> K[monitor<br/>需关注]
    J -- 否 --> L[stable<br/>稳定]

    style C fill:#95a5a6,color:#fff
    style E fill:#e74c3c,color:#fff
    style G fill:#e67e22,color:#fff
    style I fill:#f39c12,color:#fff
    style K fill:#3498db,color:#fff
    style L fill:#2ecc71,color:#fff

分类	含义	判定条件
flaky	不稳定测试	加权失败率 ≥ 0.3，Wilson 下界超过阈值
broken	已损坏测试	连续失败 ≥ 5 次
regression	回归测试	前期稳定（历史失败率 ≤ 20%），近期持续失败（近期失败率 ≥ 60%）
monitor	需关注测试	加权失败率在 0.1 ~ 0.3 之间
stable	稳定测试	加权失败率 < 0.05
insufficient_data	数据不足	运行次数 < 5 次

为什么用 Wilson 置信区间？ 小样本下简单失败率会产生误导——跑了 2 次失败 1 次，50% 失败率看似严重，但 Wilson 区间会告诉你：置信度不够，不要过早下结论。

为什么用时间衰减加权？ 一个测试 3 个月前经常失败、最近一直通过，和最近才开始频繁失败，是完全不同的情况。时间衰减确保最近的测试结果权重最高：weight = exp(-decayRate × ageInDays)。

根因分析器：7 种根因自动检测

识别出 Flaky Test 只是第一步，更重要的是回答"为什么 Flaky"：

根因类型	检测方法	典型建议
timing	超时关键词 + 持续时间变异系数(CV>0.5)	增加等待时间，使用显式等待替代固定 sleep
data_race	不同分片间通过率差异 ≥ 30%	增加同步机制，避免共享可变状态
environment	失败时间聚集 + 特定 CI 节点失败率 ≥ 50%	改善环境隔离，使用容器化
external_service	网络/5xx 错误关键词	增加 Mock/Stub，实现服务降级策略
test_order	前置测试在 ≥ 50% 失败中出现	确保测试独立性，重置共享状态
resource_leak	内存关键词 + 持续时间递增趋势	添加资源清理逻辑，检查内存泄漏
assertion_flaky	断言关键词（排除时序错误为主的情况）	放宽断言精度，使用模糊匹配

分级隔离策略：不是一刀切的跳过

传统做法遇到 Flaky Test 要么跳过、要么重试，但不同根因需要截然不同的处理策略。yuantest-playwright 提供了 4 级隔离 + 根因感知重试：

隔离级别：

级别	行为	适用场景
none	正常执行	稳定测试
monitor	继续执行，增加观察	轻度不稳定
soft_quarantine	允许重试，不计入主流程	中度不稳定
hard_quarantine	完全跳过不执行	严重不稳定

根因感知重试（核心创新点）——不同根因需要不同的重试策略：

根因类型	最大重试	延迟倍数	仅通过时重试
timing	3	×2	❌
external_service	3	×3	❌
data_race	2	×1	✅
environment	3	×2	❌
resource_leak	1	×5	✅
test_order	0	-	-
assertion_flaky	1	×1	✅

💡 "仅通过时重试" 是什么意思？当测试首次通过时，再重跑一次验证是否真的稳定。如果重跑也通过，才认为测试真正通过。这专门针对数据竞争等间歇性问题设计。

隔离预算管理：最大隔离比例 20%，最小可隔离数 3 个，预算不足时自动降级为 monitor 模式。

自动释放机制：软隔离连续通过 3 次释放，硬隔离连续通过 5 次释放，30 天后自动降级而非直接释放。

关联分析：发现系统性问题

多个 Flaky Test 同时出现，可能并非独立事件，而是同一根因的不同表现。yuantest-playwright 使用 Jaccard 共现系数 + 并查集（Union-Find）聚类 来发现这种关联：

flowchart LR
    A[多个 Flaky Test] --> B[计算两两<br/>Jaccard 共现系数]
    B --> C{共现系数 ≥ 0.6?}
    C -- 是 --> D[合并到同一关联组]
    C -- 否 --> E[独立处理]
    D --> F[并查集聚类]
    F --> G[输出关联组]

    G --> H[same_error_pattern<br/>相同错误模式]
    G --> I[same_file<br/>同一文件]
    G --> J[same_run<br/>同次运行]
    G --> K[same_time_window<br/>同一时间窗口]

    style G fill:#9b59b6,color:#fff

趋势分析与健康评分

能力	方法	价值
趋势方向检测	线性回归 + R² 判断	判断 Flaky 是在改善还是恶化
变点检测	CUSUM 算法	精确定位失败率突变的时间点
季节模式检测	按小时/天/周分析	发现周期性波动
代码变更关联	变点与提交时间关联	快速定位引入 Flaky 的代码变更
7 天预测	线性回归 + 季节调整	预判 Flaky 走势

四维健康评分体系：

健康评分 = 稳定性(35%) + 趋势(25%) + 可恢复性(20%) + 可预测性(20%)

等级	分数范围	含义
A	≥ 0.9	优秀
B	≥ 0.75	良好
C	≥ 0.6	一般
D	≥ 0.4	较差
F	< 0.4	危险

预测性检测：在失败发生前预警

通过 多信号融合，在测试真正失败之前就能预警：

flowchart TD
    A[测试历史数据] --> B[持续时间异常<br/>Z-Score > 2.0]
    A --> C[失败模式信号<br/>近期 vs 历史差异 > 10%]
    A --> D[环境偏移信号<br/>持续时间分布偏移 > 30%]
    A --> E[资源压力信号<br/>持续时间递增趋势]

    B --> F[信号加权融合]
    C --> F
    D --> F
    E --> F

    F --> G[输出预测结果]
    G --> H[是否将失败]
    G --> I[失败概率]
    G --> J[置信度]
    G --> K[建议操作]

    style F fill:#e74c3c,color:#fff
    style G fill:#9b59b6,color:#fff

因果依赖图：找到"幕后黑手"

当多个测试同时 Flaky 时，谁是因、谁是果？因果依赖图通过 入度分析 识别根因节点——入度低、出度高的节点更可能是根因：

flowchart LR
    subgraph 因果依赖图示例
        A[共享数据库] -->|same_environment| B[测试 A]
        A -->|same_environment| C[测试 B]
        A -->|same_environment| D[测试 C]
        E[外部支付 API] -->|same_environment| C
        E -->|same_environment| F[测试 D]
    end

    style A fill:#e74c3c,color:#fff
    style E fill:#e74c3c,color:#fff

上图中"共享数据库"和"外部支付 API"就是根因节点，通过 BFS 遍历计算影响范围，输出风险等级（critical / high / medium / low）。

# 查看 Flaky 统计
yuantest flaky

# 隔离所有 Flaky 测试
yuantest flaky --quarantine-all

AI 智能失败诊断

测试失败了，但错误信息晦涩难懂？yuantest-playwright 内置了 AI 智能诊断引擎，让 LLM 帮你分析失败原因、给出修复建议。

诊断流程全景

flowchart TD
    A[测试失败] --> B[上下文富集<br/>6 维信息收集]
    B --> C[知识库模式匹配<br/>18 种 Playwright 错误模式]
    C --> D[构建增强 Prompt<br/>注入 Few-Shot 示例]
    D --> E[Agent 多轮推理<br/>最多 5 轮工具调用]
    E --> F[置信度校准<br/>多维度加分]
    F --> G[输出诊断结果]

    B --> B1[源代码上下文<br/>失败行 ±20 行]
    B --> B2[截图分析<br/>base64 编码]
    B --> B3[控制台日志]
    B --> B4[堆栈跟踪]
    B --> B5[环境信息<br/>浏览器/OS/Node]
    B --> B6[历史数据<br/>最近 5 次运行]

    E --> E1[read_source_file<br/>读取源码]
    E --> E2[search_codebase<br/>搜索代码模式]
    E --> E3[query_test_history<br/>查询测试历史]
    E --> E4[read_screenshot<br/>读取失败截图]

    style B fill:#4ecdc4,color:#fff
    style E fill:#9b59b6,color:#fff
    style F fill:#f39c12,color:#fff

18 种 Playwright 错误模式知识库

系统内置了 6 大类 18 种 Playwright 常见错误模式，每种都配有中英文根因模板、修复建议和官方文档链接：

类别	错误模式	示例
TimeoutError (6种)	元素等待超时、导航超时、API 响应超时、并发竞争超时、内存溢出、并发冲突	`Timeout.waiting for.selector`
SelectorError (4种)	元素不存在、选择器歧义、iframe 内选择器、Headless 环境差异	`strict mode violation`
AssertionError (5种)	文本不匹配、可见性断言、属性断言、数据验证、状态不一致	`Expected.text.received`
NetworkError (5种)	请求失败、CORS 跨域、DNS 解析失败、环境配置错误、依赖缺失	`net::ERR_`
FrameError (2种)	Frame 已分离、跨 Frame 安全限制	`frame.*detached`
AuthError (2种)	Token 过期、未登录重定向	`401.*Unauthorized`

💡 知识库支持运行时注册自定义错误模式，你可以针对自己项目的特定错误类型扩展知识库。

Agent 多轮推理

不同于简单的"把错误信息丢给 LLM"，yuantest-playwright 实现了 Agent 循环——LLM 可以主动调用工具来获取更多信息：

flowchart TD
    A[构建初始消息<br/>system + user + 截图] --> B[调用 LLM]
    B --> C{返回 tool_calls?}

    C -- 否, 有内容 --> D[直接返回<br/>mode=single]
    C -- 否, 无内容 --> E[降级单次调用<br/>mode=single]
    C -- 是 --> F[执行工具调用]

    F --> F1[read_source_file<br/>读取源码文件]
    F --> F2[search_codebase<br/>搜索代码模式]
    F --> F3[query_test_history<br/>查询历史记录]
    F --> F4[read_screenshot<br/>读取失败截图]

    F1 --> G[记录 ReasoningStep]
    F2 --> G
    F3 --> G
    F4 --> G

    G --> H[追加工具结果到消息]
    H --> I{达到 5 轮?}
    I -- 否 --> B
    I -- 是 --> J[不带 tools 最终调用<br/>mode=agent]

    style B fill:#9b59b6,color:#fff
    style F fill:#e74c3c,color:#fff
    style G fill:#f39c12,color:#fff

安全机制：工具调用有严格的路径限制（只允许 process.cwd() 下）、敏感文件过滤（.env、.key 等）、目录过滤（node_modules、.git 等），确保不会泄露敏感信息。

SSE 流式诊断

不想等待完整诊断结果？系统支持 SSE 流式输出，诊断过程实时可见：

event: start
data: {"testTitle": "登录流程测试"}

event: chunk
data: {"content": "分析错误信息..."}

event: chunk
data: {"content": "根因：页面加载超时..."}

event: complete
data: {"diagnosis": {...完整诊断结果}}

批量聚类诊断

当一次运行中多个测试同时失败时，系统会先通过 Jaccard 相似度 聚类相似失败，然后对每个聚类的代表测试执行 AI 诊断，避免重复分析，大幅节省 LLM 调用成本。

置信度校准

LLM 给出的置信度不一定可靠，系统通过多维度加分进行校准：

校准置信度 = LLM置信度 × 0.6 + 模式匹配加分(0.2) + 截图加分(0.1) + 源码加分(0.1) + 日志加分(0.05) + 历史加分(0.1)

当校准置信度 < 0.5 时，自动追加低置信度警告，提醒开发者谨慎参考。

实时报告与可视化

WebSocket 实时推送

测试执行过程中，进度和结果通过 WebSocket 实时推送到 Dashboard，无需等待测试完成：

flowchart LR
    A[Executor<br/>执行测试] --> B[ProgressReporter<br/>自定义 Reporter]
    B -->|stderr<br/>__PW_PROGRESS__| C[handleProgressData<br/>解析 JSON]
    C --> D[EventEmitter<br/>事件分发]
    D --> E[RealtimeReporter<br/>WebSocket 服务端]
    E -->|批量推送<br/>10条/批 或 100ms| F[Dashboard UI<br/>实时更新]

    style A fill:#4ecdc4,color:#fff
    style E fill:#f39c12,color:#fff
    style F fill:#3498db,color:#fff

批量推送优化：测试结果先放入缓冲区，满 10 条或 100ms 后批量推送，减少 WebSocket 消息频率，提高性能。

自动重连：客户端使用指数退避策略（1s ~ 30s，最多 10 次），确保网络波动时自动恢复连接。

多维度报告

HTML 报告 - 自动生成详细的测试报告，方便分享和存档
JSON 报告 - 结构化数据，便于程序化处理
Blob 报告 - 支持重跑场景下的报告合并
历史趋势分析 - 追踪测试通过率和执行时间趋势，量化测试质量

视觉回归测试

yuantest-playwright 集成了基于 像素级对比 的视觉回归测试，使用 pixelmatch + pngjs 实现：

flowchart TD
    A[捕获当前截图] --> B{基线截图存在?}
    B -- 否 --> C[状态: new<br/>保存为基线]
    B -- 是 --> D[像素级对比<br/>pixelmatch]

    D --> E[计算差异比率<br/>diffRatio = diffPixels / totalPixels]
    E --> F{diffRatio ≤ threshold?}
    F -- 是 --> G[状态: identical<br/>匹配成功]
    F -- 否 --> H{diffPixels ≤ maxDiffPixels?}
    H -- 是 --> G
    H -- 否 --> I{diffRatio > maxDiffPixelRatio?}
    I -- 是 --> J[状态: regression<br/>严重回归]
    I -- 否 --> K[状态: different<br/>有差异]

    D --> L[生成差异图<br/>diff/browser/testId.png]

    style G fill:#2ecc71,color:#fff
    style J fill:#e74c3c,color:#fff
    style K fill:#f39c12,color:#fff

双层阈值机制：

比率阈值 threshold：差异比率低于此值判定为匹配（默认 0.1）
绝对像素阈值 maxDiffPixels：差异像素绝对数量在允许范围内仍判定为匹配（默认 100）

基线管理：支持一键更新基线、批量更新基线，以及 updateSnapshots 模式自动接受新快照。

注解与标签系统

注解系统

支持 8 种 Playwright 原生注解，两种检测方式：

注解类型	代码模式	注释模式
`skip`	`test.skip()`	`@skip reason`
`only`	`test.only()`	-
`fail`	`test.fail()`	-
`slow`	`test.slow()`	`@slow`
`fixme`	`test.fixme()`	`@fixme TODO: ...`
`todo`	`test.todo()`	-
`serial`	`describe.serial()`	-
`parallel`	`describe.parallel()`	-

支持自定义注解，可配置 action: 'skip' | 'fail' | 'slow' | 'mark'。

标签系统

双语法标签：

// 显式标签语法
@tag('login')
@tag('critical')

// 快捷标签语法（13 种预定义）
@smoke @regression @critical @p0 @p1 @p2
@sanity @e2e @unit @integration @slow @fast @flaky

三重过滤机制：

过滤方式	逻辑	示例
`include`	并集——包含任意标签即保留	`--include smoke,critical`
`exclude`	排除——包含任意标签即排除	`--exclude flaky,slow`
`require`	交集——必须同时包含所有标签	`--require e2e,critical`

Web UI

执行器
报告器

详细错误展示

分析器

快速上手

安装

# 全局安装（推荐）
npm install -g yuantest-playwright

# 或作为项目依赖
npm install --save-dev yuantest-playwright

运行测试

# 基本用法——与 Playwright CLI 完全一致的参数
yuantest run --test-dir ./tests

# 使用 4 个分片并行执行
yuantest run --test-dir ./tests --shards 4

# 指定多个浏览器
yuantest run --test-dir ./tests --browsers chromium,firefox

# 设置超时和重试
yuantest run --test-dir ./tests --timeout 60000 --retries 2

启动 Web Dashboard

# 默认端口 5274
yuantest ui

# 自定义端口
yuantest ui --port 8080

然后在浏览器打开 http://localhost:5274 查看可视化界面。

实战演示

场景一：大型测试套件优化

当你的测试套件越来越大时，执行时间会成为瓶颈：

# 使用智能分片加速大型测试套件
yuantest run --test-dir ./e2e --shards 8 --workers 4

# 隔离 Flaky 测试避免阻塞 CI
yuantest flaky --quarantine-all
yuantest run --test-dir ./e2e

场景二：CI/CD 集成

轻松集成到你的 CI/CD 流程中：

# GitHub Actions 示例
name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run E2E tests
        run: |
          npm install -g yuantest-playwright
          yuantest run --test-dir ./e2e --shards 4 --output ./reports

      - name: Upload reports
        uses: actions/upload-artifact@v3
        with:
          name: test-reports
          path: reports/

场景三：AI 诊断失败测试

测试失败后，一键获取 AI 诊断：

# 通过 Dashboard 可视化界面点击"AI 诊断"按钮
# 或通过 REST API 调用
curl -X POST http://localhost:5274/api/v1/diagnosis \
  -H "Content-Type: application/json" \
  -d '{
    "title": "登录流程测试",
    "error": "Timeout waiting for selector .login-btn",
    "filePath": "e2e/login.spec.ts",
    "lineNumber": 42
  }'

# 流式诊断（SSE）
curl -X POST http://localhost:5274/api/v1/diagnosis/stream \
  -H "Content-Type: application/json" \
  -d '{...}'

场景四：多浏览器测试

一键在多个浏览器上运行测试：

# 在所有浏览器上运行测试
yuantest run --test-dir ./e2e --browsers chromium,firefox,webkit

# 仅在特定浏览器上运行
yuantest run --test-dir ./e2e --browsers chromium

编程 API

如果你需要在代码中集成，yuantest-playwright 提供了完整的编程 API：

import {
  Orchestrator,
  Executor,
  Reporter,
  FlakyTestManager,
  DiagnosisService,
  DashboardServer,
} from 'yuantest-playwright';

async function main() {
  // 1. 编排测试
  const orchestrator = new Orchestrator({
    projectName: 'my-app',
    testDir: './e2e',
    outputDir: './reports',
    shards: 4,
    browsers: ['chromium', 'firefox'],
  });
  await orchestrator.initialize();
  const plan = await orchestrator.orchestrate();

  // 2. 执行测试
  const executor = new Executor(orchestrator.getConfig());

  executor.on('test_result', (result) => {
    console.log(`[${result.status}] ${result.title} (${result.duration}ms)`);
  });

  executor.on('run_progress', (progress) => {
    console.log(`Progress: ${progress.passed}/${progress.totalTests} passed`);
  });

  executor.on('run_completed', async (result) => {
    // 3. 生成报告
    const reporter = new Reporter('./reports');
    const reportPath = await reporter.generateReport(result);
    console.log(`Report: ${reportPath}`);

    // 4. 分析失败
    const analysis = await reporter.analyzeFailures(result);
    console.log(`Failures: ${analysis.length}`);
  });

  const result = await executor.execute();
  console.log(`Final: ${result.passed}/${result.totalTests} passed`);

  // 5. 启动 Dashboard
  const server = new DashboardServer(5274, './reports', './test-data');
  await server.start();
}

main();

对比优势

特性	yuantest-playwright	原生 Playwright
智能分片	✅ 方差感知 + 反馈校准	❌ 手动配置
Flaky 检测	✅ Wilson 区间 + 6 种分类	❌ 无
Flaky 隔离	✅ 4 级隔离 + 根因感知重试	❌ 无
根因分析	✅ 7 种根因自动检测	❌ 无
关联分析	✅ Jaccard 共现聚类	❌ 无
趋势追踪	✅ CUSUM 变点 + 季节模式	❌ 无
健康评分	✅ 四维 A-F 评分	❌ 无
失败预测	✅ 多信号融合	❌ 无
因果图	✅ 依赖图 + 影响分析	❌ 无
AI 诊断	✅ Agent 多轮推理 + 18 种知识库	❌ 无
可视化 Dashboard	✅ 现代化 Web UI	❌ 仅 HTML 报告
实时进度	✅ WebSocket 推送	❌ 仅命令行输出
视觉测试	✅ 像素级对比 + 差异图	❌ 仅截图
注解系统	✅ 8 种注解 + 自定义	❌ 无
标签系统	✅ 三重过滤	❌ 仅 --grep
REST API	✅ 20+ 端点	❌ 无
国际化	✅ 中/英双语	❌ 无

环境要求

Node.js >= 16.0.0
npm >= 7.0.0
Playwright >= 1.40.0

类型	链接
📖 文档	yuantest-playwright.readthedocs.io
📦 npm 包	npmjs.com/package/yua…
🐙 GitHub	github.com/yuandiv/yua…
📖 API 文档	yuandiv.github.io/yuantest-pl…
🐛 问题反馈	GitHub Issues

总结

如果你正在寻找一个能够：

✅ 智能编排 —— 方差感知分片 + 反馈校准，提升 30-50% 执行效率
✅ 根治 Flaky —— 从检测、分类、根因、隔离到预测的全链路治理
✅ AI 诊断 —— Agent 多轮推理 + 18 种知识库，秒级定位失败原因
✅ 实时可视化 —— WebSocket 推送 + 现代化 Dashboard
✅ 深度集成 CI/CD —— 零侵入设计，随时可切换回原生 Playwright

的工具，不妨试试 yuantest-playwright！

如果这个项目对你有帮助，欢迎给个 ⭐️ Star 支持一下！

🚀 yuantest-playwright：让 Playwright 测试管理更优雅的利器