apps-testing
A professional framework for testing Model Context Protocol (MCP) UI applications with Playwright
Installation
npx mcp-apps-testingAsk AI about apps-testing
Powered by Claude · Grounded in docs
I know everything about apps-testing. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
mcp-apps-testing
mcp-apps-testing is a testing framework for MCP Apps external UI (ext-apps). It provides tools for testing MCP app UI rendering, iframe sandbox behavior, and postMessage protocol communication. The framework includes mock host environments for unit testing, a spec-compliant reference implementation for E2E browser testing, and real VS Code integration for testing in production environments.
Note on Host Support: This framework provides simulated host profiles (VSCode, Claude-like, Generic) for unit testing via
MockMCPHost. These are NOT connections to real Claude Desktop or other IDEs. For real environment testing, useVSCodeHost(real VS Code via Playwright Electron) orReferenceHost(spec-compliant browser implementation).

Table of Contents
- Why mcp-apps-testing?
- Quick Start
- Key Features
- Architecture
- Examples
- Documentation
- Commands
- Publishing
- Contributing
- License
Why mcp-apps-testing?
Building MCP applications? You need to test more than just the protocol—you need to verify UI rendering, sandboxing behavior, and host communication. This framework provides three testing approaches: unit testing with mocks, browser-based E2E testing with a reference implementation, and real VS Code integration testing.
Zero-Config Unit Testing
const host = new MockMCPHost({ hostProfile: 'VSCode' });
await host.callTool('greet', { name: 'World' });
What Makes It Unique
- Mock Host Profiles: Unit test with simulated host profiles (VSCode, Claude-like, Generic) that provide different capabilities and themes
- Full Control: Mock, intercept, and assert on every JSON-RPC message
- Reference Implementation: Browser-based E2E testing with a spec-compliant MCP ext-app host (ReferenceHost)
- Real VS Code E2E: Test MCP tools through Copilot Chat in a real VS Code instance with Playwright Electron (VSCodeHost)
- Fluent API: Human-readable test code with auto-retry and intelligent defaults
Quick Start
Installation
Install the package along with its peer dependency:
npm install mcp-apps-testing @playwright/test --save-dev
npx playwright install chromium
Write Your First Test
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();
});
Run tests: npm test
Key Features
Mock Host Profiles for Unit Testing
Test your MCP app with simulated host environments that provide different capabilities and themes:
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
Note: These are simulated profiles for unit testing, not connections to real hosts. For real VS Code testing, use VSCodeHost.
Complete Message Control
Mock, intercept, and record every JSON-RPC interaction:
// Mock responses
host.getInterceptor().mockResponse('tools/call', yourHandler);
// Record and assert
const requests = host.getInterceptor().getRecordedRequests();
expect(requests[0].method).toBe('initialize');
Test UI + Protocol Together
Validate both visual rendering AND protocol behavior in the same test:
// 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' } });
Architecture
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
Core Components
- MockMCPHost: Simulated MCP host for unit testing with auto-response to common protocol messages. Use host profiles (VSCode, Claude-like, Generic) to test with different capabilities and themes.
- TransportInterceptor: Mocks and records JSON-RPC messages for testing and assertions
- Host Profiles: Pre-configured simulated environments (VSCode, Claude-like, Generic) with capabilities and themes for unit testing
- ReferenceHost: Spec-compliant browser-based MCP ext-app host for E2E testing. Implements the postMessage protocol in a real browser with iframe sandboxing.
- VSCodeHost: Real VS Code E2E testing via Playwright Electron. Launch VS Code, interact with Copilot Chat, and test MCP tools in a 100% production environment.
Examples
See the examples/ directory for complete working examples:
- hello-world.spec.ts: Full UI testing with theme switching and tool calls
- basic-test.spec.ts: Protocol-focused testing with message mocking
- vscode-e2e.spec.ts: VS Code E2E testing — full MCP tool call through Copilot Chat
Documentation
- Getting Started Guide - Detailed setup and first steps
- API Reference - Complete API documentation
- VS Code E2E Testing - Test MCP ext-apps in real VS Code
- Example App - Sample MCP application
Commands
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
Publishing
This package is automatically published to npm via GitHub Actions with full CI/CD automation.
CI/CD Workflows
Continuous Integration (ci.yml)
Runs automatically on:
- Pull requests to
main - Pushes to
mainbranch
Tests the package on Node.js versions 18, 20, and 22:
- Lints TypeScript code
- Builds the package
- Runs all tests with Playwright
- Uploads test results as artifacts
Automated Release (release.yml)
Triggered manually via GitHub Actions UI:
- Go to Actions → Release → Run workflow
- Select version bump type:
patch- Bug fixes (0.1.1 → 0.1.2)minor- New features (0.1.1 → 0.2.0)major- Breaking changes (0.1.1 → 1.0.0)
- The workflow automatically:
- Runs all tests and linting
- Bumps the version in
package.json - Creates a git tag
- Pushes changes and tag to GitHub
- Creates a GitHub release
- Publishes to npm using OIDC Trusted Publishing with provenance
Legacy Publish (publish.yml)
Maintained for backwards compatibility. Publishes to npm when a GitHub release is manually created.
Manual Publishing (if needed)
To publish manually:
npm run build
npm test
npm publish
The prepublishOnly script ensures a clean build is created before publishing.
Contributing
This framework is designed for professional MCP UI application testing. Contributions should maintain the modular architecture and focus on core testing capabilities.
License
MIT
Built with: TypeScript • Playwright
Learn more: Model Context Protocol • Playwright
