@frontmcp/testing

@frontmcp/testing

E2E testing framework for FrontMCP servers.

Install

npm install -D @frontmcp/testing

Peer dependencies: @frontmcp/sdk, jest, @jest/globals. Optional: @playwright/test (for browser OAuth flow testing).

Quick Start

import { test, expect } from '@frontmcp/testing';
import MyServer from './src/main';

test.use({ server: MyServer });

test('server exposes tools', async ({ mcp }) => {
  const tools = await mcp.tools.list();
  expect(tools).toContainTool('my-tool');
});

test('tool execution works', async ({ mcp }) => {
  const result = await mcp.tools.call('my-tool', { input: 'test' });
  expect(result).toBeSuccessful();
});

npx frontmcp test

The library handles server startup, MCP client connection, test execution, and cleanup.

Fixtures

Fixture	Description
mcp	Auto-connected MCP client — tools, resources, prompts, raw protocol, notifications, logs
server	Server control — createClient(), restart(), onHook(), getLogs()
auth	Token factory — createToken(), createExpiredToken(), createInvalidToken(), pre-built test users

Custom Matchers

Tools — toContainTool, toBeSuccessful, toBeError, toHaveTextContent, toHaveImageContent, toHaveResourceContent

Resources — toContainResource, toContainResourceTemplate, toHaveMimeType

Prompts — toContainPrompt, toHaveMessages, toHaveRole, toContainText

Protocol — toBeValidJsonRpc, toHaveResult, toHaveError, toHaveErrorCode

Tool UI — toHaveRenderedHtml, toContainHtmlElement, toContainBoundValue, toBeXssSafe, toHaveWidgetMetadata, toHaveCssClass, toNotContainRawContent, toHaveProperHtmlStructure

Configuration

test.use({
  server: MyServer,
  port: 3003, // default: auto
  transport: 'streamable-http', // or 'sse'
  auth: { mode: 'public' },
  logLevel: 'debug',
  env: { API_KEY: 'test' },
});

Docs

Topic	Link
Getting started	Testing Overview
Testing tools	Tools
Testing Tool UI	Tool UI
Testing resources	Resources
Testing prompts	Prompts
Testing auth	Authentication
Testing transports	Transports
HTTP mocking	HTTP Mocking

Related Packages

• @frontmcp/sdk — core framework
• @frontmcp/ui — UI components tested with toHaveRenderedHtml and friends

License

Apache-2.0 — see LICENSE.