Test Fixtures

@frontmcp/testing uses a fixture-based testing approach inspired by Playwright. Fixtures are pre-configured objects automatically injected into your test functions, eliminating boilerplate setup code.

Available Fixtures

Fixture	Type	Description
`mcp`	`McpTestClient`	Auto-connected MCP client for making requests
`auth`	`AuthFixture`	Token factory for authentication testing
`server`	`ServerFixture`	Server control and multi-client creation

test('example using all fixtures', async ({ mcp, auth, server }) => {
  // All fixtures are ready to use
});

Configuring Fixtures

Use test.use() to configure fixtures. Called at the top of a file it applies to the whole file; called inside a test.describe() it applies to that block only.

import { test, expect } from '@frontmcp/testing';

test.use({
  server: './src/main.ts',     // Server entry file
  port: 3003,                   // Port number
  transport: 'streamable-http', // Transport type
  auth: { mode: 'public' },    // Auth configuration
  logLevel: 'debug',            // Log level
  env: { API_KEY: 'test' },    // Environment variables
  startupTimeout: 30000,        // Startup timeout (ms)
  entryPath: '/mcp',            // Where the server mounts MCP (default: '/')
});

test('my test', async ({ mcp }) => {
  // ...
});

Configuration Options

Option	Type	Default	Description
`server`	`string`	—	Path to server entry file (required)
`port`	`number`	Auto	Port to run server on
`transport`	`'sse' \| 'streamable-http'`	`'streamable-http'`	Transport protocol
`auth`	`object`	—	Auth configuration
`logLevel`	`'debug' \| 'info' \| 'warn' \| 'error'`	`'warn'`	Server log level
`env`	`Record<string, string>`	—	Environment variables
`startupTimeout`	`number`	`30000`	Server startup timeout in ms
`baseUrl`	`string`	—	Connect to an existing server. May also be combined with `server` to override the booted server’s URL.
`entryPath`	`string`	`'/'`	Where the server mounts MCP (`http.entryPath`)

Servers that serve MCP somewhere other than `/`

A server configured with http: { entryPath: '/mcp' } serves MCP at /mcp, and the test client follows it:

test.use({
  server: './src/main.ts',
  entryPath: '/mcp',
});

You usually do not need to set this. When the client’s first request 404s and the server reports where it does serve MCP — the web-fetch host answers {"error":"Not Found","entryPaths":["/mcp"]} — the client reconnects there on its own. If it still cannot connect, the error names the paths the server reported instead of a bare HTTP 404. entryPath applies to the MCP endpoint only. OAuth and discovery endpoints stay at the server root, which is where the server mounts them.

Scoping `test.use()` to a `describe`

test.use() is scoped to the describe block it is called in. Options from nested blocks are merged over the outer ones (env is merged key by key), and every distinct configuration gets its own server, which the block that configured it also stops. A block without its own test.use() shares its parent’s server.

test.use({ server: './src/main.ts', port: 0, env: { SHARED: 'file' } });

test.describe('block A', () => {
  test.use({ env: { FEATURE: 'A' } }); // own server, env = { SHARED: 'file', FEATURE: 'A' }

  test('sees feature A', async ({ mcp }) => {});
});

test.describe('block B', () => {
  test.use({ env: { FEATURE: 'B' } }); // never sees block A's env

  test('sees feature B', async ({ mcp }) => {});
});

auth: { mode, type } is passed to the server process as FRONTMCP_TEST_AUTH_MODE and FRONTMCP_TEST_AUTH_TYPE, which the server entry file can read. auth.mode: 'public' also keeps the mcp client anonymous.

Parameterised tests

test.each and test.describe.each pass the row values to the callback. For test.each the fixtures come first, then the row values:

test.each([
  ['read', 1],
  ['write', 2],
])('scope %s', async ({ mcp }, scope, level) => {
  expect(mcp.isConnected()).toBe(true);
});

Conditional skipping

test.skip(condition, reason) skips every test registered after it in the enclosing block — the Playwright idiom, and the natural way to gate a suite on credentials:

const hasCredentials = Boolean(process.env.TWILIO_ACCOUNT_SID);

test.describe('against the live Twilio API', () => {
  test.skip(!hasCredentials, 'credentials not set');

  test('looks up a carrier', async ({ mcp }) => {
    // ...
  });
});

Put the call at the top of the block you want to gate. A nested test.describe inherits an outer skip. The (name, fn) form still skips a single named test.

MCP Client Fixture

The mcp fixture is your primary interface for testing MCP servers.

Tools API

test('testing tools', async ({ mcp }) => {
  // List all tools
  const tools = await mcp.tools.list();
  expect(tools).toContainTool('create-note');

  // Call a tool
  const result = await mcp.tools.call('create-note', {
    title: 'Test Note',
    content: 'Hello world',
  });
  expect(result).toBeSuccessful();

  // Access result content
  const data = result.json();
  expect(data.id).toBeDefined();
});

Resources API

test('testing resources', async ({ mcp }) => {
  // List static resources
  const resources = await mcp.resources.list();
  expect(resources).toContainResource('notes://all');

  // List resource templates
  const templates = await mcp.resources.listTemplates();
  expect(templates).toContainResourceTemplate('notes://note/{id}');

  // Read a resource
  const content = await mcp.resources.read('notes://note/123');
  expect(content).toHaveMimeType('application/json');
  expect(content.json().id).toBe('123');
});

Prompts API

test('testing prompts', async ({ mcp }) => {
  // List prompts
  const prompts = await mcp.prompts.list();
  expect(prompts).toContainPrompt('summarize-notes');

  // Get a prompt
  const result = await mcp.prompts.get('summarize-notes', {
    tag: 'work',
    format: 'detailed',
  });

  expect(result.messages).toHaveLength(1);
  expect(result.messages[0].role).toBe('user');
});

Session & Server Info

test('session info', async ({ mcp }) => {
  // Session
  expect(mcp.isConnected()).toBe(true);
  expect(mcp.sessionId).toBeDefined();

  // Server info
  expect(mcp.serverInfo.name).toBe('my-server');
  expect(mcp.protocolVersion).toBe('2025-06-18');

  // Capabilities
  expect(mcp.hasCapability('tools')).toBe(true);
  expect(mcp.capabilities.resources?.subscribe).toBe(false);
});

Raw Protocol Access

test('raw protocol', async ({ mcp }) => {
  // Send any JSON-RPC request
  const response = await mcp.raw.request({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
    params: {},
  });
  expect(response.result.tools).toBeDefined();

  // Send notification
  await mcp.raw.notify({
    jsonrpc: '2.0',
    method: 'notifications/initialized',
  });

  // Test parse errors
  const errorResponse = await mcp.raw.sendRaw('invalid json');
  expect(errorResponse).toHaveErrorCode(-32700);
});

Logging & Debugging

test('logs and traces', async ({ mcp }) => {
  await mcp.tools.call('create-note', { title: 'Test' });

  // Access captured logs
  const logs = mcp.logs.all();
  const errors = mcp.logs.filter('error');
  const matches = mcp.logs.search('note');

  // Access request traces
  const traces = mcp.trace.all();
  const lastTrace = mcp.trace.last();
  expect(lastTrace.durationMs).toBeLessThan(1000);

  // Clear for next test
  mcp.logs.clear();
  mcp.trace.clear();
});

Auth Fixture

The auth fixture creates JWT tokens for testing authentication flows.

Creating Tokens

test('token creation', async ({ mcp, auth }) => {
  // Create a token with custom claims
  const token = await auth.createToken({
    sub: 'user-123',
    scopes: ['read', 'write'],
    email: 'user@example.com',
    name: 'John Doe',
    claims: { tenantId: 'tenant-1' },
    expiresIn: 3600, // 1 hour
  });

  // Authenticate the MCP client
  await mcp.authenticate(token);

  // Now requests include the token
  const tools = await mcp.tools.list();
});

Pre-built Test Users

test('using test users', async ({ auth }) => {
  // Pre-defined users with common permission sets
  const adminToken = await auth.createToken(auth.users.admin);
  const userToken = await auth.createToken(auth.users.user);
  const readOnlyToken = await auth.createToken(auth.users.readOnly);
});

Testing Edge Cases

test('expired token', async ({ mcp, auth }) => {
  const expiredToken = await auth.createExpiredToken({ sub: 'user-123' });

  await expect(mcp.authenticate(expiredToken))
    .rejects.toThrow('expired');
});

test('invalid signature', async ({ mcp, auth }) => {
  const invalidToken = auth.createInvalidToken({ sub: 'user-123' });

  await expect(mcp.authenticate(invalidToken))
    .rejects.toThrow('invalid signature');
});

JWKS Access

test('JWKS integration', async ({ auth }) => {
  // Get public keys for verification
  const jwks = await auth.getJwks();
  expect(jwks.keys).toHaveLength(1);

  // Get issuer and audience
  const issuer = auth.getIssuer();
  const audience = auth.getAudience();
});

Server Fixture

The server fixture provides server control and multi-client support.

Server Information

test('server info', async ({ server }) => {
  expect(server.info.baseUrl).toContain('localhost');
  expect(server.info.port).toBe(3003);
  expect(server.info.pid).toBeGreaterThan(0); // pid of the process that listens on the port
});

Creating Additional Clients

test('multi-client testing', async ({ server, auth }) => {
  // Create clients with different configurations
  const sseClient = await server.createClient({
    transport: 'sse',
  });

  const authenticatedClient = await server.createClient({
    token: await auth.createToken({ sub: 'user-1' }),
  });

  // Use both clients
  const tools1 = await sseClient.tools.list();
  const tools2 = await authenticatedClient.tools.list();

  // Clean up
  await sseClient.disconnect();
  await authenticatedClient.disconnect();
});

Server Logs

test('server logs', async ({ server, mcp }) => {
  await mcp.tools.call('create-note', { title: 'Test' });

  // Server-side logs (stdout/stderr of the server process).
  // `mcp.logs` is different: it holds the log notifications the client received.
  const logs = server.getLogs();
  expect(logs.some(log => log.includes('create-note'))).toBe(true);

  // Clear logs
  server.clearLogs();
});

Restart Server

test('server restart', async ({ server, mcp }) => {
  // Restart the server
  await server.restart();

  // `mcp` and every client created with server.createClient() reconnect automatically
  const tools = await mcp.tools.list();
  expect(tools.length).toBeGreaterThan(0);
});

Fixture Lifecycle

Understanding when fixtures are created and destroyed:

┌────────────────────────────────────────────────────────────────────────────┐
│  1. FILE LOAD                                                              │
│     - test.use() stores configuration                                      │
│     - afterAll cleanup hook is registered                                  │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  2. FIRST TEST STARTS                                                      │
│     - Server is started (shared across all tests in file)                  │
│     - Token factory is created (shared)                                    │
│     - Health check polling until server is ready                           │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  3. EACH TEST                                                              │
│     a. New McpTestClient is created and connected                          │
│     b. Fixtures (mcp, auth, server) are injected into test                 │
│     c. Test runs                                                           │
│     d. Client disconnects (server stays running)                           │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  4. AFTER ALL TESTS                                                        │
│     - Server is stopped                                                    │
│     - All resources are cleaned up                                         │
└────────────────────────────────────────────────────────────────────────────┘

The server is shared across all tests in a file for performance. Starting a server is expensive (100-500ms), so sharing it dramatically improves test speed.

Best Practices

Do:

Use test.use() once at the top of each test file
Clear logs and traces between tests if needed
Disconnect additional clients created via server.createClient()
Use port: 0 for automatic port selection in CI. Ports are reserved with a lock that also covers other Jest workers, so parallel files do not collide

Don’t:

Modify shared server state without cleanup
Create many clients without disconnecting them
Rely on test execution order
Use hardcoded ports in parallel test runs

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Available Fixtures

Configuring Fixtures

Configuration Options

Servers that serve MCP somewhere other than `/`

Scoping `test.use()` to a `describe`

Parameterised tests

Conditional skipping

MCP Client Fixture

Tools API

Resources API

Prompts API

Session & Server Info

Raw Protocol Access

Logging & Debugging

Auth Fixture

Creating Tokens

Pre-built Test Users

Testing Edge Cases

JWKS Access

Server Fixture

Server Information

Creating Additional Clients

Server Logs

Restart Server

Fixture Lifecycle

Best Practices

​Available Fixtures

​Configuring Fixtures

​Configuration Options

​Servers that serve MCP somewhere other than /

​Scoping test.use() to a describe

​Parameterised tests

​Conditional skipping

​MCP Client Fixture

​Tools API

​Resources API

​Prompts API

​Session & Server Info

​Raw Protocol Access

​Logging & Debugging

​Auth Fixture

​Creating Tokens

​Pre-built Test Users

​Testing Edge Cases

​JWKS Access

​Server Fixture

​Server Information

​Creating Additional Clients

​Server Logs

​Restart Server

​Fixture Lifecycle

​Best Practices

Available Fixtures

Configuring Fixtures

Configuration Options

Servers that serve MCP somewhere other than `/`

Scoping `test.use()` to a `describe`

Parameterised tests

Conditional skipping

MCP Client Fixture

Tools API

Resources API

Prompts API

Session & Server Info

Raw Protocol Access

Logging & Debugging

Auth Fixture

Creating Tokens

Pre-built Test Users

Testing Edge Cases

JWKS Access

Server Fixture

Server Information

Creating Additional Clients

Server Logs

Restart Server

Fixture Lifecycle

Best Practices