YC-Browser-Analysis

专业级前端HTML页面调试和分析MCP工具，支持VS Code扩展和独立MCP服务器两种部署模式。集成 Microsoft Playwright MCP 功能，提供全面的 Web 测试和自动化能力。

✨ 功能特性

🔧 核心功能

全面的浏览器权限处理 - 支持13种浏览器权限类型（地理位置、通知、摄像头、麦克风等）
智能错误检测 - JavaScript错误、CSS问题、网络请求失败等自动识别
性能分析 - 页面加载性能、资源优化建议、响应时间监控
UI布局分析 - 元素重叠、点击目标太小、布局偏移等问题检测
无障碍访问检测 - WCAG合规性检查、色彩对比度分析
响应式设计验证 - 多设备尺寸兼容性测试

🚀 Playwright MCP 集成功能 (新增)

交互式测试会话 - 启动和管理 Playwright 测试会话，支持实时交互
跨浏览器自动化 - 支持 Chrome、Firefox、Safari 的自动化测试
元素交互测试 - 自动化点击、表单填写、导航等用户操作
可视化测试 - 自动截图、录制用户操作、生成测试报告
性能监控 - 页面性能指标监控，Core Web Vitals 检测
网络请求分析 - HTTP 请求/响应监控，API 测试功能
脚本执行 - 在浏览器环境中执行自定义 JavaScript 代码
测试录制与回放 - 录制用户操作并生成可重复执行的测试脚本

🌐 多浏览器支持

Chromium - Chrome、Edge、Brave等
Firefox - Mozilla Firefox
WebKit - Safari（macOS）

🛠️ 部署模式

VS Code扩展 - 集成开发环境内直接使用
MCP服务器 - 独立服务，支持多客户端连接
命令行工具 - 批量分析和CI/CD集成

🚀 快速开始

系统要求

Node.js 18+
TypeScript 5.0+
Playwright 1.40.0+ (用于 Playwright MCP 功能)
Microsoft Playwright MCP 服务器 (可选，用于增强测试功能)
支持的操作系统：Windows、macOS、Linux

安装

方式一：VS Code扩展安装

从VS Code插件市场搜索 "YC-Browser-Analysis"
点击安装并重启VS Code
按 Ctrl+Shift+P 打开命令面板
输入 "YC Browser Analysis" 查看可用命令

方式二：独立MCP服务器

# 克隆项目
git clone https://github.com/your-org/yc-browser-analysis.git
cd yc-browser-analysis

# 安装依赖
npm install

# 构建项目
npm run build

# 启动MCP服务器
npm run start:mcp

方式三：Playwright MCP 服务器 (可选增强功能)

如需使用完整的 Playwright MCP 功能，可单独启动 Microsoft Playwright MCP 服务器：

# 安装 Microsoft Playwright MCP (可选)
npm install -g @microsoft/playwright-mcp

# 启动 Playwright MCP 服务器
playwright-mcp --port 3001

# 或者使用 Docker 运行
docker run -p 3001:3001 microsoft/playwright-mcp

方式四：开发环境

# 克隆项目
git clone https://github.com/your-org/yc-browser-analysis.git
cd yc-browser-analysis

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 运行测试
npm test

# 代码覆盖率测试
npm run test:coverage

📖 使用指南

VS Code扩展使用

基础分析

打开HTML文件
右键选择 "分析当前页面"
查看分析结果面板

权限测试

使用命令 YC Browser Analysis: 测试浏览器权限
选择要测试的权限类型
查看权限请求和处理结果

性能分析

// 在VS Code中打开包含此代码的HTML文件
// 扩展会自动检测性能问题
setTimeout(() => {
    // 模拟耗时操作
    for(let i = 0; i < 1000000; i++) {
        console.log(i);
    }
}, 1000);

Playwright MCP 交互式测试 (新增)

启动测试会话
- 使用命令 YC Browser Analysis: Start Interactive Test Session
- 输入要测试的 URL
- 选择浏览器类型和配置选项
录制用户操作
- 使用命令 YC Browser Analysis: Start Recording Actions
- 在打开的浏览器中进行操作
- 系统自动记录所有交互
生成测试报告
- 使用命令 YC Browser Analysis: Generate Test Report
- 查看详细的性能和兼容性报告
- 导出测试结果

示例测试场景：

// 自动执行的测试脚本示例（系统自动生成）
await page.goto('https://example.com');
await page.click('#login-button');
await page.fill('#username', 'testuser');
await page.fill('#password', 'password123');
await page.click('#submit');
await expect(page.locator('#welcome')).toBeVisible();

MCP服务器使用

启动服务器

npm run start:mcp
# 服务器将在 http://localhost:3000 启动

API调用示例

# 分析单个页面
curl -X POST http://localhost:3000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "includePerformance": true,
      "includeAccessibility": true
    }
  }'

# 批量分析
curl -X POST http://localhost:3000/analyze/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example1.com",
      "https://example2.com"
    ],
    "options": {
      "browser": "chromium",
      "viewport": {"width": 1920, "height": 1080}
    }
  }'

# Playwright MCP 交互式测试 (新增)
# 启动测试会话
curl -X POST http://localhost:3000/playwright/start-session \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "browser": "chromium",
      "enableErrorTracking": true,
      "recordVideo": true
    }
  }'

# 执行用户操作
curl -X POST http://localhost:3000/playwright/perform-action \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-123",
    "action": "click",
    "params": {
      "selector": "#login-button"
    }
  }'

# 获取测试结果
curl -X GET http://localhost:3000/playwright/session/session-123/results

命令行工具

# 分析单个页面
npx yc-browser-analysis analyze https://example.com

# 分析本地HTML文件
npx yc-browser-analysis analyze ./test.html --local

# 生成报告
npx yc-browser-analysis analyze https://example.com --format json --output report.json

# 批量分析
npx yc-browser-analysis analyze --config analysis-config.json

🔧 配置

VS Code扩展配置

在VS Code设置中配置：

{
  "ycBrowserAnalysis.defaultBrowser": "chromium",
  "ycBrowserAnalysis.headless": true,
  "ycBrowserAnalysis.timeout": 30000,
  "ycBrowserAnalysis.viewport": {
    "width": 1920,
    "height": 1080
  },
  "ycBrowserAnalysis.analysis": {
    "includePerformance": true,
    "includeAccessibility": true,
    "includeResponsive": true
  },
  "ycBrowserAnalysis.playwrightMcp": {
    "serverUrl": "ws://localhost:3001",
    "timeout": 30000,
    "retryAttempts": 3,
    "browserType": "chromium",
    "headless": false,
    "viewport": {
      "width": 1280,
      "height": 720
    }
  }
}

MCP服务器配置

创建 config/mcp-config.json：

{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "browser": {
    "defaultType": "chromium",
    "headless": true,
    "timeout": 30000,
    "poolSize": 3
  },
  "analysis": {
    "defaultOptions": {
      "includeJavaScript": true,
      "includeCSS": true,
      "includePerformance": true,
      "includeAccessibility": true,
      "includeResponsive": true
    }
  },
  "permissions": {
    "autoHandle": {
      "geolocation": "allow",
      "notifications": "deny",
      "camera": "ask",
      "microphone": "ask"
    }
  },
  "playwrightMcp": {
    "enabled": true,
    "serverUrl": "ws://localhost:3001",
    "connection": {
      "timeout": 30000,
      "retryAttempts": 3,
      "enableAutoReconnect": true
    },
    "defaultOptions": {
      "browser": "chromium",
      "headless": false,
      "enableErrorTracking": true,
      "recordVideo": false,
      "enableScreenshots": true
    },
    "sessions": {
      "maxConcurrent": 5,
      "timeoutMinutes": 30,
      "autoCleanup": true
    }
  }
}

📊 分析结果

分析报告结构

interface AnalysisResult {
  pageId: string;
  timestamp: Date;
  summary: {
    totalIssues: number;
    errorCount: number;
    warningCount: number;
    infoCount: number;
    performanceScore?: number;
    accessibilityScore?: number;
  };
  categories: {
    javascript: {
      errors: JSError[];
      score: number;
    };
    css: {
      issues: CSSIssue[];
      score: number;
    };
    performance: {
      issues: PerformanceIssue[];
      score: number;
    };
    accessibility: {
      issues: AccessibilityIssue[];
      score: number;
    };
  };
  recommendations: Recommendation[];
}

性能指标

指标	说明	正常范围
首次内容绘制 (FCP)	页面开始渲染时间	< 1.8秒
最大内容绘制 (LCP)	主要内容完成渲染	< 2.5秒
首次输入延迟 (FID)	用户交互响应时间	< 100毫秒
累积布局偏移 (CLS)	页面布局稳定性	< 0.1

🔍 故障排除

常见问题

1. 浏览器启动失败

Error: Failed to launch browser

解决方案：

确保系统已安装对应浏览器
检查浏览器权限设置
尝试以管理员权限运行

2. 权限测试失败

Error: Permission request timeout

解决方案：

检查浏览器权限策略
确保页面通过HTTPS访问（部分权限要求）
更新浏览器到最新版本

3. 分析结果不准确

可能原因：

页面动态内容加载未完成
网络延迟影响
浏览器兼容性问题

解决方案：

增加等待时间：waitFor: 5000
使用特定的等待条件：waitUntil: 'networkidle'
切换浏览器类型进行对比测试

4. Playwright MCP 连接失败 (新增)

Error: Failed to connect to Playwright MCP server

解决方案：

确保 Playwright MCP 服务器已启动：playwright-mcp --port 3001
检查服务器 URL 配置："serverUrl": "ws://localhost:3001"
验证网络连接和防火墙设置
检查服务器日志：DEBUG=playwright-mcp:* playwright-mcp --port 3001

5. 测试会话超时

Error: Test session timeout after 30 seconds

解决方案：

增加会话超时时间："timeout": 60000
检查测试页面响应速度
优化测试步骤，减少不必要的等待
使用更快的浏览器类型（如 chromium）

6. 录制功能不工作

可能原因：

浏览器权限限制
Playwright MCP 服务器配置问题
存储空间不足

解决方案：

启用录制功能："recordVideo": true
检查存储权限和空间
使用非无头模式："headless": false
更新 Playwright 到最新版本

调试模式

启用详细日志：

# 环境变量
DEBUG=yc-browser-analysis:* npm run start:mcp

# 或在代码中
process.env.DEBUG = 'yc-browser-analysis:*';

VS Code扩展调试：

按 F1 打开命令面板
输入 "Developer: Toggle Developer Tools"
查看控制台日志

🧪 测试

运行测试套件

# 运行所有测试
npm test

# 运行特定测试文件
npm test -- --testPathPattern=BrowserManager

# 生成覆盖率报告
npm run test:coverage

# 运行E2E测试
npm run test:e2e

# 运行 Playwright MCP 集成测试 (新增)
npm test -- --testPathPattern=PlaywrightMCP

# 测试 Playwright MCP 连接
npm run test:playwright-mcp-connection

测试页面

项目包含专门的测试页面：

test-pages/permission-test.html - 浏览器权限测试
test-pages/css-issues-test.html - CSS问题测试
test-pages/playwright-mcp-test.html - Playwright MCP 功能测试 (新增)
test-pages/interactive-test.html - 交互式测试场景 (新增)

本地启动测试服务器：

npm run test:server
# 访问 http://localhost:8080/test-pages/

# 启动 Playwright MCP 测试服务器 (新增)
npm run test:playwright-server
# Playwright MCP 服务器将在 ws://localhost:3001 启动

🤝 贡献指南

开发环境设置

Fork 项目仓库
创建功能分支：git checkout -b feature/amazing-feature
安装依赖：npm install
运行开发模式：npm run dev

代码规范

使用 TypeScript 严格模式
遵循 ESLint 配置
保持 80% 以上测试覆盖率
所有 public API 必须有 JSDoc 文档

提交规范

feat: 添加新的分析功能
fix: 修复权限检测bug
docs: 更新API文档
test: 添加单元测试
refactor: 重构核心模块

Pull Request

确保所有测试通过
更新相关文档
添加变更日志
请求代码审查

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙋 支持

📧 邮件支持：support@yc-tools.com
💬 GitHub Issues：问题反馈
📚 文档站点：完整文档
💡 功能建议：功能请求

🔗 相关链接

Playwright 文档
Microsoft Playwright MCP - Playwright MCP 服务器
VS Code 扩展开发
MCP 协议规范
Web 无障碍指南
Playwright MCP 教程 - 官方 MCP 集成指南
浏览器自动化最佳实践

YC Browser Analysis

YICHAO

YC-Browser-Analysis

✨ 功能特性

🔧 核心功能

🚀 Playwright MCP 集成功能 (新增)

🌐 多浏览器支持

🛠️ 部署模式

🚀 快速开始

系统要求

安装

方式一：VS Code扩展安装

方式二：独立MCP服务器

方式三：Playwright MCP 服务器 (可选增强功能)

方式四：开发环境

📖 使用指南

VS Code扩展使用

基础分析

权限测试

性能分析

Playwright MCP 交互式测试 (新增)

MCP服务器使用

启动服务器

API调用示例

命令行工具

🔧 配置

VS Code扩展配置

MCP服务器配置

📊 分析结果

分析报告结构

性能指标

🔍 故障排除

常见问题

1. 浏览器启动失败

2. 权限测试失败

3. 分析结果不准确

4. Playwright MCP 连接失败 (新增)

5. 测试会话超时

6. 录制功能不工作

调试模式

🧪 测试

运行测试套件

测试页面

🤝 贡献指南

开发环境设置

代码规范

提交规范

Pull Request

📄 许可证

🙋 支持

🔗 相关链接