让 Playwright 测试管理更优雅的利器

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

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

---

📌 目录

• 前言
• 项目介绍
• 核心亮点
• [Web UI](#Web UI "#Web-UI")
• 快速上手
• 实战演示
• [编程 API](#编程 API "#%E7%BC%96%E7%A8%8B-api")
• 对比优势
• 性能特性
• 总结

---

前言

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

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

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

---

项目介绍

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

npm install -g yuantest-playwright

---

核心亮点

🎯 智能测试编排

• 自动发现测试文件 - 智能扫描测试目录，支持多种文件格式
• 智能分片策略 - 基于历史执行时间优化分片分配，实现负载均衡，提升 30-50% 执行效率
• 并行执行优化 - 自动计算最优并行度，最大化测试效率

🔍 Flaky 测试管理（杀手级功能！）

这是 yuantest-playwright 最具竞争力的功能之一：

• 自动检测 - 基于历史数据自动识别不稳定测试，无需人工干预
• 智能隔离 - 一键隔离 Flaky 测试，避免影响 CI/CD 流程
• 统计分析 - 提供详细的 Flaky 测试统计和趋势，帮助团队了解测试健康度
• 自定义阈值 - 灵活配置 Flaky 检测标准，适应不同团队需求

# 查看 Flaky 统计
yuantest flaky

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

📊 实时报告与可视化

• WebSocket 实时推送 - 实时查看测试进度和结果，无需等待测试完成
• Web Dashboard - 现代化可视化界面，直观展示测试数据
• HTML 报告 - 自动生成详细的测试报告，方便分享和存档
• 历史趋势分析 - 追踪测试通过率和执行时间趋势，量化测试质量

🛠️ 失败分析与调试

• 自动分类失败原因 - 智能识别超时、断言失败、元素未找到等常见问题
• 修复建议 - 提供针对性的失败修复建议，加速问题解决
• Trace 管理 - 自动收集和管理 Playwright Trace 文件，方便回溯
• 产物管理 - 统一管理测试截图、视频等产物

🏷️ 高级功能

• 注解支持 - 支持 @slow, @flaky, @skip 等测试注解
• 标签管理 - 灵活的测试标签系统，方便分类管理
• 视觉测试 - 集成像素对比的视觉回归测试
• 配置热加载 - 支持配置文件动态加载

---

Web UI

• 执行器

• 报告器

• 详细错误展示

• 分析器

快速上手

安装

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

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

运行测试

# 基本用法
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/

场景三：多浏览器测试

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

# 在所有浏览器上运行测试
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,
  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 检测	✅ 自动检测与隔离	❌ 无
可视化 Dashboard	✅ 现代化 Web UI	❌ 仅 HTML 报告
失败分析	✅ 自动分类+建议	❌ 仅日志
实时进度	✅ WebSocket 推送	❌ 仅命令行输出
历史趋势	✅ 完整趋势分析	❌ 无
测试注解	✅ 支持	❌ 无
REST API	✅ 提供	❌ 无

---

性能特性

• 智能分片 - 基于历史执行时间优化分片，提升 30-50% 执行效率
• 并行执行 - 支持多 Worker 并行，充分利用多核 CPU
• 增量测试 - 支持仅运行变更相关的测试
• 缓存优化 - 智能缓存测试发现结果，减少重复计算
• 内存优化 - 流式处理大型测试结果，降低内存占用

---

环境要求

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

---

相关链接

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

---

总结

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

• ✅ 提升 Playwright 测试效率
• ✅ 解决 Flaky 测试困扰
• ✅ 提供可视化管理界面
• ✅ 深度集成 CI/CD 流程

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

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

---

Happy Testing! 🎉

---

作者：YuanDiv

来源：掘金

链接：juejin.cn/editor/draf...

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。