内容
# playwright-network-chaos-mcp 🐸💥
[](https://www.npmjs.com/package/playwright-network-chaos-mcp)
[](https://www.npmjs.com/package/playwright-network-chaos-mcp)
[](https://github.com/vola-trebla/playwright-network-chaos-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
一个 MCP 服务器，为 Playwright 浏览器会话提供**动态网络混乱控制**。
您的测试在完美的网络环境中运行，但用户的网络环境并非如此。该 MCP 允许 AI 代理模拟 API 中断、注入延迟、丢弃连接，并阻塞第三方资源 — 然后断言应用程序是否能优雅地处理这些情况。
---
## 🤔 问题
CI 环境具有无瑕的连接性。API 请求在毫秒内响应。CDN 永远不会宕机。因此，您的测试通过了 — 但当支付服务返回 503 错误、网络在结账过程中中断或 Google Analytics 挂起 8 秒并冻结页面时，生产环境却崩溃了。
编写 Playwright 测试的 AI 代理无法引入或推理网络不稳定性。它们无法提出以下问题：
- 🙈 _当支付 API 失败时，结账页面是否显示错误状态？_
- 🙈 _当仪表盘 API 速度变慢时，骨架加载器是否出现？_
- 🙈 _如果所有跟踪脚本都被阻止，应用程序是否仍然有效？_
- 🙈 _如果在订单提交后但在响应到达之前网络中断，会发生什么？_
`playwright-network-chaos-mcp` 解决了这个问题。
---
## 🛠️ 工具
### `模拟 API 失败`
拦截匹配模式的请求，并强制它们返回错误状态码。检查应用程序是否显示备用 UI。
```json
{
"url": "https://your-app.com/checkout",
"intercept_pattern": "**/api/payment**",
"status_code": 503,
"fallback_selector": ".error-boundary",
"wait_ms": 2000
}
```
```json
{
"intercepted_count": 2,
"fallback_found": true,
"fallback_selector": ".error-boundary",
"page_state": {
"page_errors": [],
"console_errors": ["Failed to load resource: 503"]
}
}
```
---
### `注入延迟`
为匹配的请求添加人工延迟。检查应用程序在等待时是否显示加载状态。
```json
{
"url": "https://your-app.com/dashboard",
"intercept_pattern": "**/api/**",
"latency_ms": 3000,
"jitter_ms": 500,
"loading_selector": ".skeleton-loader"
}
```
```json
{
"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
}
```
---
### `阻塞资源`
中止对指定 URL 模式的请求 — 用于测试第三方服务中断（分析、CDN、跟踪像素）。
```json
{
"url": "https://your-app.com",
"block_patterns": ["**/analytics**", "*.doubleclick.net/**", "**/hotjar**"],
"core_content_selector": ".main-content",
"wait_ms": 2000
}
```
```json
{
"blocked_count": 7,
"blocked_urls": ["https://www.google-analytics.com/analytics.js", "..."],
"core_content_found": true,
"page_state": { "page_errors": [], "console_errors": [] }
}
```
---
### `模拟网络中断`
在延迟后中止正在进行的请求 — 模拟请求和响应之间的连接丢失。
```json
{
"url": "https://your-app.com/checkout",
"intercept_pattern": "**/api/order**",
"drop_after_ms": 800,
"fallback_selector": ".network-error-toast",
"wait_ms": 3000
}
```
```json
{
"intercepted_count": 1,
"fallback_found": true,
"fallback_selector": ".network-error-toast",
"page_state": { "page_errors": ["TypeError: Failed to fetch"] }
}
```
---
### `触发系统网络错误`
使用 OS 级错误码中止请求 — 模拟 DNS 故障、防火墙阻止和连接重置。
```json
{
"url": "https://your-app.com/dashboard",
"intercept_pattern": "**/api/**",
"error_code": "addressunreachable",
"fallback_selector": ".network-error"
}
```
```json
{
"error_code": "addressunreachable",
"intercepted_count": 3,
"fallback_found": true,
"page_state": { "page_errors": [], "console_errors": ["net::ERR_ADDRESS_UNREACHABLE"] }
}
```
---
### `模拟有状态失败`
使前 N 个请求失败，然后让后续请求成功 — 测试重试逻辑和恢复流程。
```json
{
"url": "https://your-app.com/dashboard",
"intercept_pattern": "**/api/data**",
"http_status": 503,
"failure_count": 2,
"success_payload": "{\"data\":[]}",
"fallback_selector": ".retry-button"
}
```
```json
{
"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
}
```
---
### `注入响应损坏`
在协议级别提供损坏的响应 — 未终止的 JSON、内容长度谎言或截断的有效载荷。
```json
{
"url": "https://your-app.com/checkout",
"intercept_pattern": "**/api/order**",
"corruption_type": "malformed_json",
"fallback_selector": ".parse-error"
}
```
```json
{
"corruption_type": "malformed_json",
"intercepted_count": 1,
"fallback_found": false,
"page_state": { "page_errors": ["SyntaxError: Unexpected token u in JSON"] }
}
```
---
### `断言混乱已处理`
注入混乱的 HTTP 状态并返回结构化的通过/失败判决 — 仅当备用 UI 出现且没有未处理的 JavaScript 异常时，`chaos_survived` 才为 true。
```json
{
"url": "https://your-app.com/checkout",
"intercept_pattern": "**/api/**",
"http_status": 500,
"expected_fallback_selector": ".error-boundary"
}
```
```json
{
"http_status": 500,
"unhandled_exceptions": [],
"console_errors": ["Failed to load resource: 500"],
"fallback_ui_detected": true,
"chaos_survived": true
}
```
---
## 🚀 安装
```bash
npx playwright-network-chaos-mcp
```
或全局安装：
```bash
npm install -g playwright-network-chaos-mcp
npx playwright install chromium
```
### Claude Desktop 配置
```json
{
"mcpServers": {
"playwright-network-chaos-mcp": {
"command": "npx",
"args": ["-y", "playwright-network-chaos-mcp"]
}
}
}
```
---
## 💡 示例代理提示
> _"检查结账页面在支付 API 返回 503 时是否显示正确的错误状态"_
> _"模拟仪表盘上的 3 秒 API 延迟，并验证骨架加载器是否出现"_
> _"阻止所有分析和跟踪脚本，并确认主内容仍然加载"_
> _"在订单提交请求进行中时丢弃该请求，并检查用户是否看到错误消息"_
> _"模拟 API 的 DNS 故障，并检查错误边界是否渲染"_
> _"使前 3 个请求失败，然后成功 — 应用程序是否自动重试并恢复？"_
> _"注入损坏的 JSON 并断言应用程序不会崩溃 — 返回混乱判决"_
---
## 🔗 相关项目
- [playwright-trace-decoder-mcp](https://github.com/vola-trebla/playwright-trace-decoder-mcp) — 从 Playwright 跟踪中进行 CI 失败的根本原因分析
- [flakiness-knowledge-graph-mcp](https://github.com/vola-trebla/flakiness-knowledge-graph-mcp) — flaky 测试模式的知识图谱
- [ast-impact-mapper-mcp](https://github.com/vola-trebla/ast-impact-mapper-mcp) — 通过 TypeScript AST 从代码更改中查找受影响的测试
- [zod-contract-mock-forge-mcp](https://github.com/vola-trebla/zod-contract-mock-forge-mcp) — 从 Zod 模式生成确定性模拟
- [playwright-spatial-layout-mcp](https://github.com/vola-trebla/playwright-spatial-layout-mcp) — 网页布局的几何空间感知
---
## 📄 许可证
MIT © [vola-trebla](https://github.com/vola-trebla)
