Unit Testing - sunpeak

Overview

Unit tests are for sunpeak app framework projects (created with sunpeak new). If you’re using sunpeak as a standalone testing framework for an existing MCP server, use E2E tests instead, which test your server over the wire via the MCP protocol.

Unit tests run your component and hook logic in isolation using Vitest with happy-dom. They’re fast, don’t require the inspector or a browser, and test tool handlers, React components, and data transformations directly.

pnpm
npm
yarn

pnpm test                    # Run unit + e2e tests
pnpm test:unit               # Unit tests only

npm run test                    # Run unit + e2e tests
npm run test:unit               # Unit tests only

yarn test                    # Run unit + e2e tests
yarn test:unit               # Unit tests only

Setup

Unit tests live in tests/unit/ (or any *.test.ts / *.spec.ts file matched by your Vitest config). For sunpeak framework projects, Vitest is pre-configured with happy-dom. For standalone usage, add Vitest to your project:

pnpm
npm
yarn

pnpm add -D vitest @vitest/coverage-v8

npm install -D vitest @vitest/coverage-v8

yarn add -D vitest @vitest/coverage-v8

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'happy-dom',
    include: ['tests/unit/**/*.{test,spec}.{ts,tsx}'],
  },
});

Writing Unit Tests

Test component rendering, hook logic, and data transformations without the full inspector stack.

Testing Components

import { render, screen } from '@testing-library/react';
import { test, expect } from 'vitest';
import { ReviewResource } from '../../src/resources/review/review';

test('renders review title', () => {
  // Mock the useToolData hook at the module level or via a provider
  render(<ReviewResource />);
  expect(screen.getByRole('heading')).toBeDefined();
});

Testing Data Transformations

import { test, expect } from 'vitest';
import { formatAlbumData } from '../../src/resources/albums/utils';

test('formats album data correctly', () => {
  const raw = { title: 'Summer Slice', count: 12 };
  const result = formatAlbumData(raw);
  expect(result.displayTitle).toBe('Summer Slice (12 photos)');
});

Testing Tool Handlers

Tool handlers are plain async functions, so you can test them directly:

import { test, expect } from 'vitest';
import handler from '../../src/tools/show-albums';

test('returns album data', async () => {
  const result = await handler({ category: 'travel' }, {} as any);
  expect(result.structuredContent).toBeDefined();
  expect(result.structuredContent.albums).toBeInstanceOf(Array);
});

When to Use Unit Tests vs E2E Tests

Use unit tests for	Use E2E tests for
Data transformations and utilities	Visual rendering across hosts and themes
Tool handler logic	Iframe communication and sandbox behavior
Component logic in isolation	Full tool call flow (call → render → assert)
Fast feedback during development	Cross-host compatibility (ChatGPT vs Claude)

Unit tests and E2E tests are complementary. Unit tests catch logic bugs fast. E2E tests catch rendering and integration issues across the full inspector stack.

Additional Quality Tools

Linting (ESLint)

pnpm
npm
yarn

pnpm add -D eslint @typescript-eslint/eslint-plugin

npm install -D eslint @typescript-eslint/eslint-plugin

yarn add -D eslint @typescript-eslint/eslint-plugin

Add "lint": "eslint . --ext .ts,.tsx" to package.json scripts.

Type Checking

TypeScript is already installed. Add to package.json scripts:

"typecheck": "tsc --noEmit"

Formatting (Prettier)

pnpm
npm
yarn

pnpm add -D prettier

npm install -D prettier

yarn add -D prettier

Add "format": "prettier --write ." to package.json scripts.

Learn More

Vitest Docs

Learn more about Vitest for unit testing.

E2E Testing

Full-stack testing with the inspector and Playwright.

​Overview

​Setup

​Writing Unit Tests

​Testing Components

​Testing Data Transformations

​Testing Tool Handlers

​When to Use Unit Tests vs E2E Tests

​Additional Quality Tools

​Learn More

Vitest Docs

E2E Testing

Overview

Setup

Writing Unit Tests

Testing Components

Testing Data Transformations

Testing Tool Handlers

When to Use Unit Tests vs E2E Tests

Additional Quality Tools

Learn More