@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.