mcp应用程序测试
mcp-apps测试是一个用于mcp应用程序外部UI(ext应用程序)的测试框架。它提供了用于测试MCP应用程序UI渲染、iframe沙盒行为和postMessage协议通信的工具。该框架包括用于单元测试的模拟主机环境、用于E2E浏览器测试的符合规范的参考实现,以及用于生产环境测试的真实VS Code集成。
> 关于主机支持的说明:该框架提供 模拟主机配置文件 (VSCode,类似克劳德,通用)用于通过以下方式进行单元测试 MockMCPHost。这些不是与真正的Claude Desktop或其他IDE的连接。对于真实环境测试,请使用 VSCodeHost (Playwright Electron提供的真实VS代码)或 ReferenceHost (符合规范的浏览器实现)。
目录
- 为什么要测试mcp应用程序?
- 快速开始
- 安装
- 主要特点
- 建筑
- 例子
- 文档
- 命令
- 出版
- 贡献
- 许可证
为什么要测试mcp应用程序?
构建MCP应用程序?您需要测试的不仅仅是协议,还需要验证UI渲染、沙盒行为和主机通信。 该框架提供了三种测试方法:使用模拟的单元测试、使用参考实现的基于浏览器的E2E测试和真实的VS代码集成测试。
零配置单元测试```typescript
const host = new MockMCPHost({ hostProfile: 'VSCode' });
await host.callTool('greet', { name: 'World' });
**是什么让它独一无二**
- **模拟主机配置文件**:使用模拟主机配置文件(VSCode、克劳德式、通用)进行单元测试,提供不同的功能和主题
- **完全控制**:对每条JSON-RPC消息进行模拟、拦截和断言
- **参考实现**:使用符合规范的MCP ext应用程序主机(ReferenceHost)进行基于浏览器的E2E测试
- **真实VS代码E2E**:使用Playwright Electron(VSCodeHost)在真实的VS Code实例中通过Copilot Chat测试MCP工具
- **流利的API**:具有自动重试和智能默认值的人类可读测试代码
## 快速开始
### 安装
安装该包及其对等依赖关系:```bash
npm install mcp-apps-testing @playwright/test --save-dev
npx playwright install chromium
写你的第一个测试```typescript
import { test, expect } from '@playwright/test';
import { MockMCPHost } from 'mcp-apps-testing';
test('MCP app responds to tool calls', async () => {
const host = new MockMCPHost({ hostProfile: 'VSCode' });
// Mock the tool response
host.getInterceptor().mockResponse('tools/call', (req) => ({
jsonrpc: '2.0',
id: req.id,
result: { content: [{ type: 'text', text: 'Hello, World!' }] }
}));
// Call the tool with fluent API
const response = await host.callTool('greet', { name: 'World' });
expect(response.result.content[0].text).toBe('Hello, World!');
await host.cleanup();
});
**运行测试**: `npm test`
## 主要特点
### 用于单元测试的模拟主机配置文件
使用提供不同功能和主题的模拟主机环境测试您的MCP应用程序:```typescript
new MockMCPHost({ hostProfile: 'VSCode' }) // Simulates VS Code-like environment
new MockMCPHost({ hostProfile: 'Claude' }) // Simulates Claude-like environment
new MockMCPHost({ hostProfile: 'Generic' }) // Generic MCP host simulation
注:这些是 单元测试的模拟剖面,而不是与真实主机的连接。对于真实的VS代码测试,请使用 VSCodeHost.
完成消息控制
模拟、拦截并记录每次JSON-RPC交互:```typescript
// Mock responses
host.getInterceptor().mockResponse('tools/call', yourHandler);
// Record and assert
const requests = host.getInterceptor().getRecordedRequests();
expect(requests[0].method).toBe('initialize');
### 一起测试UI+协议
在同一测试中验证视觉渲染和协议行为:```typescript
// Test UI rendering in browser with ReferenceHost
const host = await ReferenceHost.launch(page, 'your-mcp-app.html');
const frame = host.getAppFrame();
await expect(frame.locator('h1')).toBeVisible();
// Test protocol interaction
await host.sendMessage({ jsonrpc: '2.0', id: 1, result: { greeting: 'Hello' } });
建筑```mermaid
graph TD
App[Your MCP Application
HTML + JavaScript]
PW[Playwright
• Browser Automation
• UI Testing
• Screenshots]
App -->|JSON-RPC 2.0| TI[TransportInterceptor
Mock & Record Messages
Request/Response Interception]
TI -->|Used by| Mock[MockMCPHost
Simulated Host for Unit Testing
Auto-respond to Protocol Messages
Fluent DSL Methods]
PW -->|Controls| Mock
Mock -->|Uses| Profiles[Host Profiles
• VSCode simulation
• Claude-like simulation
• Generic simulation]
App -->|postMessage| Ref[ReferenceHost
Spec-Compliant Browser Host
Real iframe + postMessage
E2E Testing]
PW -->|Controls| Ref
App -->|Real MCP Protocol| VSC[VSCodeHost
Real VS Code Instance
100% Production Environment
Copilot Chat Integration]
PW -->|Electron| VSC
Mock --> Results[Test Results & Assertions
Message Recording • Protocol Logging • Traces]
Ref --> Results
VSC --> Results
style App fill:#e0e7ff,stroke:#6366f1,color:#1e293b
style TI fill:#6366f1,stroke:#4338ca,color:#fff
style Mock fill:#8b5cf6,stroke:#7c3aed,color:#fff
style Ref fill:#8b5cf6,stroke:#7c3aed,color:#fff
style VSC fill:#10b981,stroke:#059669,color:#fff
style Profiles fill:#e0e7ff,stroke:#6366f1,color:#1e293b
style PW fill:#e0e7ff,stroke:#6366f1,color:#1e293b
style Results fill:#e0e7ff,stroke:#6366f1,color:#1e293b
**核心组件**
- **模拟MCPHost**:用于单元测试的模拟MCP主机,可自动响应常见协议消息。使用主机配置文件(VSCode、类似Claude、Generic)测试不同的功能和主题。
- **运输拦截器**:模拟和记录JSON-RPC消息以进行测试和断言
- **主机配置文件**:具有单元测试功能和主题的预配置模拟环境(VSCode、克劳德式、通用)
- **引用主机**:符合规范的基于浏览器的MCP-ext应用程序主机,用于E2E测试。在具有iframe沙盒的真实浏览器中实现postMessage协议。
- **VSCodeHost**:通过Playwright Electron进行Real VS Code E2E测试。启动VS Code,与Copilot Chat交互,并在100%生产环境中测试MCP工具。
## 例子
看 示例/ 完整工作示例目录:
- **世界规格**:通过主题切换和工具调用进行完整的UI测试
- **基本技术规范**:使用消息模拟进行以协议为中心的测试
- **vscode-e2e.spec.ts**:VS Code E2E测试——通过Copilot聊天进行完整的MCP工具调用
## 文档
- 入门指南 -详细的设置和第一步
- API 参考 -完整的API文件
- VS代码E2E测试 -在真实的VS代码中测试MCP ext应用程序
- 示例应用程序 -MCP应用示例
## 命令```bash
npm test # Run all tests
npm run test:ui # Run with Playwright UI
npm run build # Build the framework
npm run dev # Development mode with watch
出版
此包通过GitHub Actions自动发布到npm,并具有完全的CI/CD自动化功能。
CI/CD工作流程
持续集成(ci.yml)
自动运行于:
- 将请求拉到
main - 推到
main分支
在Node.js版本18、20和22上测试该包:
- Lints TypeScript代码
- 构建包
- 使用Playwright运行所有测试
- 将测试结果作为工件上传
自动发布(Release.yml)
通过GitHub操作界面手动触发:
- 首选 行动 → 发布 → 运行工作流
- 选择版本凹凸类型:
-patch-错误修复(0.1.1→0.1.2)
-minor-新功能(0.1.1→0.2.0)
-major-重大变化(0.1.1→1.0.0) - 工作流会自动执行以下操作:
- 运行所有测试和linting
- 将版本插入package.json
- 创建git标签
- 将更改和标签推送到GitHub
- 创建GitHub版本
- 使用具有出处的OIDC可信发布发布发布到npm
传统发布(Publish.yml)
保持向后兼容性。当手动创建GitHub版本时,发布到npm。
手动出版(如需要)
要手动发布,请执行以下操作:bash
npm run build
npm test
npm publish
这 prepublishOnly 该脚本确保在发布之前创建干净的构建。
贡献
该框架专为专业MCP UI应用程序测试而设计。贡献应保持模块化架构,并专注于核心测试能力。
许可证
麻省理工学院
内置: TypeScript•剧作家
了解更多: 模型上下文协议 • 剧作家
