AI导哈

MCP应用测试框架

mcp-apps-testing是一个用于测试MCP Apps外部UI的框架，提供单元测试、端到端浏览器测试和真实VS Code集成测试的工具。

  • by aviveldan
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 aviveldan/mcp-apps-testing

使用说明

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应用程序？您需要测试的不仅仅是协议，还需要验证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<br/>HTML + JavaScript]
    PW[Playwright<br/>• Browser Automation<br/>• UI Testing<br/>• Screenshots]
    
    App -->|JSON-RPC 2.0| TI[TransportInterceptor<br/>Mock & Record Messages<br/>Request/Response Interception]
    
    TI -->|Used by| Mock[MockMCPHost<br/>Simulated Host for Unit Testing<br/>Auto-respond to Protocol Messages<br/>Fluent DSL Methods]
    
    PW -->|Controls| Mock
    Mock -->|Uses| Profiles[Host Profiles<br/>• VSCode simulation<br/>• Claude-like simulation<br/>• Generic simulation]
    
    App -->|postMessage| Ref[ReferenceHost<br/>Spec-Compliant Browser Host<br/>Real iframe + postMessage<br/>E2E Testing]
    
    PW -->|Controls| Ref
    
    App -->|Real MCP Protocol| VSC[VSCodeHost<br/>Real VS Code Instance<br/>100% Production Environment<br/>Copilot Chat Integration]
    
    PW -->|Electron| VSC
    
    Mock --> Results[Test Results & Assertions<br/>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工具调用

文档

命令

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）
  3. 工作流会自动执行以下操作：
    • 运行所有测试和linting
    • 将版本插入 package.json
    • 创建git标签
    • 将更改和标签推送到GitHub
    • 创建GitHub版本
    • 使用具有出处的OIDC可信发布发布发布到npm

传统发布（Publish.yml）

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

手动出版（如需要）

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

npm run build
npm test
npm publish

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

贡献

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

许可证

麻省理工学院

内置： TypeScript•剧作家

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

相关 MCP