playwright-network-chaos-mcp

playwright-network-chaos-mcp 🐸💥

一个 MCP 服务，为 AI Agent 提供对 Playwright 浏览器会话的动态网络混沌控制。

你的测试运行在完美的网络上，但用户并非如此。这个 MCP 服务让 AI Agent 能够模拟 API 故障、注入延迟、在请求进行过程中中断连接，并屏蔽第三方资源，然后验证应用是否能妥善处理这些情况。

---

🤔 问题所在

CI 环境的网络连接完美无缺。API 在几毫秒内响应。CDN 从不宕机。因此测试总能通过——然而在生产环境中，支付服务返回 503、网络在结账过程中中断，或 Google Analytics 卡住 8 秒并冻结页面时，应用却会出故障。

编写 Playwright 测试的 AI Agent 无法引入或分析网络不稳定的情况。它们无法询问：

• 🙈 支付 API 故障时，结账页面会显示错误状态吗？
• 🙈 仪表盘 API 响应缓慢时，会显示骨架屏加载器吗？
• 🙈 屏蔽所有跟踪脚本后，应用还能正常运行吗？
• 🙈 订单提交后、响应到达前网络中断，会发生什么？

playwright-network-chaos-mcp 解决了这个问题。

---

🛠️ 工具

simulate_api_failure

拦截与指定模式匹配的请求，并强制返回错误状态码。检查应用是否显示备用 UI。

{
  "url": "https://your-app.com/checkout",
  "intercept_pattern": "**/api/payment**",
  "status_code": 503,
  "fallback_selector": ".error-boundary",
  "wait_ms": 2000
}

{
  "intercepted_count": 2,
  "fallback_found": true,
  "fallback_selector": ".error-boundary",
  "page_state": {
    "page_errors": [],
    "console_errors": ["Failed to load resource: 503"]
  }
}

---

inject_latency

为匹配的请求添加人为延迟。检查应用等待期间是否显示加载状态。

{
  "url": "https://your-app.com/dashboard",
  "intercept_pattern": "**/api/**",
  "latency_ms": 3000,
  "jitter_ms": 500,
  "loading_selector": ".skeleton-loader"
}

{
  "intercepted_count": 4,
  "intercepted_requests": [
    { "url": "https://api.your-app.com/users", "method": "GET", "delay_ms": 3241 }
  ],
  "loading_state_found": true,
  "load_time_ms": 3890
}

---

block_resources

中止指向指定 URL 模式的请求——用于测试第三方服务故障（分析服务、CDN、跟踪像素）。

{
  "url": "https://your-app.com",
  "block_patterns": ["**/analytics**", "*.doubleclick.net/**", "**/hotjar**"],
  "core_content_selector": ".main-content",
  "wait_ms": 2000
}

{
  "blocked_count": 7,
  "blocked_urls": ["https://www.google-analytics.com/analytics.js", "..."],
  "core_content_found": true,
  "page_state": { "page_errors": [], "console_errors": [] }
}

---

simulate_network_drop

延迟一段时间后中止正在进行的请求——模拟请求与响应之间的连接中断。

{
  "url": "https://your-app.com/checkout",
  "intercept_pattern": "**/api/order**",
  "drop_after_ms": 800,
  "fallback_selector": ".network-error-toast",
  "wait_ms": 3000
}

{
  "intercepted_count": 1,
  "fallback_found": true,
  "fallback_selector": ".network-error-toast",
  "page_state": { "page_errors": ["TypeError: Failed to fetch"] }
}

---

trigger_system_network_error

使用操作系统级错误代码中止请求——模拟 DNS 故障、防火墙拦截和连接重置。

{
  "url": "https://your-app.com/dashboard",
  "intercept_pattern": "**/api/**",
  "error_code": "addressunreachable",
  "fallback_selector": ".network-error"
}

{
  "error_code": "addressunreachable",
  "intercepted_count": 3,
  "fallback_found": true,
  "page_state": { "page_errors": [], "console_errors": ["net::ERR_ADDRESS_UNREACHABLE"] }
}

---

simulate_stateful_failure

让前 N 个请求失败，然后使后续请求成功——用于测试重试逻辑和恢复流程。

{
  "url": "https://your-app.com/dashboard",
  "intercept_pattern": "**/api/data**",
  "http_status": 503,
  "failure_count": 2,
  "success_payload": "{\"data\":[]}",
  "fallback_selector": ".retry-button"
}

{
  "failure_count": 2,
  "actual_failed": 2,
  "actual_succeeded": 1,
  "intercepted_requests": [
    { "url": "...", "method": "GET", "status": 503, "attempt": 1, "outcome": "failed" },
    { "url": "...", "method": "GET", "status": 200, "attempt": 3, "outcome": "passed" }
  ],
  "fallback_found": true
}

---

inject_response_corruption

在协议层提供格式错误的响应——例如未闭合的 JSON、错误的 Content-Length 或截断的负载。

{
  "url": "https://your-app.com/checkout",
  "intercept_pattern": "**/api/order**",
  "corruption_type": "malformed_json",
  "fallback_selector": ".parse-error"
}

{
  "corruption_type": "malformed_json",
  "intercepted_count": 1,
  "fallback_found": false,
  "page_state": { "page_errors": ["SyntaxError: Unexpected token u in JSON"] }
}

---

assert_chaos_handled

注入混沌 HTTP 状态，并返回结构化的通过／失败判定——仅当备用 UI 出现且没有未处理的 JS 异常时，chaos_survived 才为 true。

{
  "url": "https://your-app.com/checkout",
  "intercept_pattern": "**/api/**",
  "http_status": 500,
  "expected_fallback_selector": ".error-boundary"
}

{
  "http_status": 500,
  "unhandled_exceptions": [],
  "console_errors": ["Failed to load resource: 500"],
  "fallback_ui_detected": true,
  "chaos_survived": true
}

---

🚀 安装

npx playwright-network-chaos-mcp

或者全局安装：

npm install -g playwright-network-chaos-mcp
npx playwright install chromium

Claude Desktop 配置

{
  "mcpServers": {
    "playwright-network-chaos-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-network-chaos-mcp"]
    }
  }
}

---

💡 Agent 提示词示例

"检查支付 API 返回 503 时，结账页面是否会显示恰当的错误状态"

"在仪表盘上模拟 3 秒的 API 延迟，并验证是否显示骨架屏加载器"

"屏蔽所有分析和跟踪脚本，并确认主要内容仍能加载"

"在订单提交请求进行过程中中断连接，并检查用户是否会看到错误消息"

"为 API 模拟 DNS 故障，并检查是否会渲染错误边界"

"让前 3 个请求失败，然后恢复成功——应用会自动重试并恢复吗？"

"注入格式错误的 JSON，并断言应用不会崩溃——返回混沌判定"

---

🔗 相关项目

• playwright-trace-decoder-mcp — 根据 Playwright 跟踪记录分析 CI 失败的根本原因
• flakiness-knowledge-graph-mcp — 不稳定测试模式的知识图谱
• ast-impact-mapper-mcp — 通过 TypeScript AST 查找代码变更影响的测试
• zod-contract-mock-forge-mcp — 根据 Zod schema 确定性地生成模拟数据
• playwright-spatial-layout-mcp — 对网页布局进行几何空间感知

---

📄 许可证

MIT © vola-trebla