MCP Apps Testing

mcp应用程序测试

](https://www.npmjs.com/package/mcp-apps-testing) ](https://www.npmjs.com/package/mcp-apps-testing)  ](https://nodejs.org)  

mcp-apps测试是一个用于mcp应用程序外部UI（ext应用程序）的测试框架。它提供了用于测试MCP应用程序UI渲染、iframe沙盒行为和postMessage协议通信的工具。该框架包括用于单元测试的模拟主机环境、用于E2E浏览器测试的符合规范的参考实现，以及用于生产环境测试的真实VS Code集成。

关于主机支持的说明：该框架提供 模拟主机配置文件 （VSCode，类似克劳德，通用）用于通过以下方式进行单元测试 MockMCPHost。这些不是与真正的Claude Desktop或其他IDE的连接。对于真实环境测试，请使用 VSCodeHost （Playwright Electron提供的真实VS代码）或 ReferenceHost （符合规范的浏览器实现）。

Hello World App

目录

• 为什么要测试mcp应用程序？
• 快速开始

- 安装

• 主要特点
• 建筑
• 例子
• 文档
• 命令
• 出版
• 贡献
• 许可证

为什么要测试mcp应用程序？

构建MCP应用程序？您需要测试的不仅仅是协议，还需要验证UI渲染、沙盒行为和主机通信。 该框架提供了三种测试方法：使用模拟的单元测试、使用参考实现的基于浏览器的E2E测试和真实的VS代码集成测试。

零配置单元测试

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：具有自动重试和智能默认值的人类可读测试代码

快速开始

安装

安装该包及其对等依赖关系：

npm install mcp-apps-testing @playwright/test --save-dev
npx playwright install chromium

写你的第一个测试

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应用程序：

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交互：

// Mock responses
host.getInterceptor().mockResponse('tools/call', yourHandler);

// Record and assert
const requests = host.getInterceptor().getRecordedRequests();
expect(requests[0].method).toBe('initialize');

一起测试UI+协议

在同一测试中验证视觉渲染和协议行为：

// 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' } });

建筑

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工具调用

Test Results

文档

• 入门指南 -详细的设置和第一步
• API 参考 -完整的API文件
• VS代码E2E测试 -在真实的VS代码中测试MCP ext应用程序
• 示例应用程序 -MCP应用示例

命令

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操作界面手动触发：

1. 首选 行动 → 发布 → 运行工作流
2. 选择版本凹凸类型：

- patch -错误修复（0.1.1→0.1.2） - minor -新功能（0.1.1→0.2.0） - major -重大变化（0.1.1→1.0.0）

1. 工作流会自动执行以下操作：

- 运行所有测试和linting - 将版本插入 package.json - 创建git标签 - 将更改和标签推送到GitHub - 创建GitHub版本 - 使用具有出处的OIDC可信发布发布发布到npm

传统发布（Publish.yml）

保持向后兼容性。当手动创建GitHub版本时，发布到npm。

手动出版（如需要）

要手动发布，请执行以下操作：

npm run build
npm test
npm publish

这 prepublishOnly 该脚本确保在发布之前创建干净的构建。

贡献

该框架专为专业MCP UI应用程序测试而设计。贡献应保持模块化架构，并专注于核心测试能力。

许可证

麻省理工学院

______________________________________________________________________

内置： TypeScript•剧作家

了解更多： 模型上下文协议 • 剧作家