MCP App Testing Framework

Why MCP Apps Need Their Own Testing Framework

MCP Apps run inside AI hosts like ChatGPT and Claude, not in a browser you control. You can't open DevTools. You can't write a Cypress test against chatgpt.com. Every code change means deploying, opening the host, starting a conversation, triggering the tool, and checking the result manually. Across two hosts, two themes, and three display modes, that's 24 combinations per change.

sunpeak replicates those host runtimes locally. Your tests call tools, render resources in simulated ChatGPT and Claude, and assert against the result with Playwright. Same display modes, themes, safe areas, and conversation chrome as the real hosts.

The testing framework works with any MCP server. Run sunpeak test init to scaffold tests into an existing project, or sunpeak test in a sunpeak project where everything is preconfigured.

Three Levels of MCP App Testing

Test CLI

How It Works

import { test, expect } from 'sunpeak/test';

test('albums render in light mode', async ({ mcp }) => {
  const result = await mcp.callTool('show-albums', {}, { theme: 'light' });
  const app = result.app();
  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
});

test('albums render in fullscreen', async ({ mcp }) => {
  const result = await mcp.callTool('show-albums', {}, { displayMode: 'fullscreen' });
  const app = result.app();
  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
  // Compare against saved baseline (only runs with --visual flag)
  await mcp.screenshot('albums-fullscreen');
});

What You Can Test

• Multi-Host Rendering

  Tests run against both ChatGPT and Claude runtimes automatically via Playwright projects. One test file covers both hosts.

• Themes & Display Modes

  Test light/dark themes and inline/fullscreen/pip display modes. Use setTheme() and setDisplayMode() or pass options to callTool().

• Visual Regression

  Capture screenshots with mcp.screenshot() and compare against baselines. Configure thresholds and max diff pixel ratios in defineConfig().

• Backend Tool Mocking

  Simulation files can mock callServerTool responses with simple or conditional matching. Test interactive flows without a real backend.

• MCP-Specific Assertions

  Custom matchers: toHaveTextContent(), toHaveStructuredContent(), toBeError() alongside standard Playwright locators.

• Any MCP Server, Any Language

  Use sunpeak test init with any MCP server. Configure the server via HTTP URL or startup command. Python, Go, TypeScript, anything.

Who It's For