Fixtures

test.use({ server, baseUrl?, port?, project?, entryPath?, transport?, publicMode?, env?, startupTimeout?, logLevel? });

test("name", async ({ mcp, server, auth }) => { /* … */ });

Reference

test.use(options)

Say which server the tests use, at the top of the file for all of them, or inside a test.describe for the tests in that block:

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

test.use({ server: "./src/main.ts", env: { CRM_URL: "http://localhost:50910" } });

test("search_tickets is listed", async ({ mcp }) => {
  expect(await mcp.tools.list()).toContainTool("search_tickets");
});

The server must listen on the port in process.env.PORT, which the library sets for it:

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  http: { port: Number(process.env.PORT ?? 3000) },
})
export default class Server {}

See more examples below.

Options

How calls combine

• A call applies to its block. test.use() at the top of the file configures every test in it. Inside a test.describe, it configures that block's tests, on top of the file's options: the last value of each option wins, and env entries are added. Calling it again in the same place merges the new options in.
• Each configuration has its own server, and the block that configured it stops it. Two blocks with different options start two servers, and a block's server stops when the block ends. A block with no test.use() of its own uses the server of the block around it. See Two configurations of a server.

Before 1.8.7, every test.use() in a file merged into one configuration, the last call won for every test, and a test.use() inside a test.describe stopped the server after that block.

Lifetimes

So everything a tool keeps in memory carries over from one test to the next, and everything you set on a client (mocks, interceptors, an elicitation handler, collected notifications) doesn't. When a test fails, the library prints the server's last 50 log entries under [TestFixture] === Server Logs (test failed) ===.

mcp

A new McpTestClient for each test, already connected. It speaks MCP 2025-06-18: it sends initialize, then uses the session the server gives it.

• Credentials. Without publicMode, the client first asks the server's /oauth/token for an anonymous token (grant_type: "anonymous"), and sends it as Authorization: Bearer … if it gets one. A public server gives one, so there this.auth.user.sub is an anon: id. With publicMode: true, the client sends no Authorization header.
• On a server that needs a token, connecting fails with 401. The fixture prints a warning, [TestFixture] MCP client could not connect anonymously — the server requires authentication, with the reason, and gives the test a client that never initialized: mcp.isConnected() is true, but every request fails with -32600, Session not initialized — send `initialize` first. Tests for such a server sign mcp in with await mcp.authenticate(token), or use server.createClient({ token }). A 401 or 403 is tried once, so a refused connection doesn't wait. (Before 1.8.7 it was tried three times, half a second apart.)
• mcp.authenticate(token) signs the client in. It opens a new session as the token's user, and keeps the token, so mcp.reconnect() uses it too. When the server refuses the token, it rejects, as createClient() does, and the client keeps its old session and identity. See Testing authentication. Before 1.8.7 it changed only the header: the session still belonged to the old token, the next request failed with HTTP 404: Not Found (invalid session id), and reconnect() dropped the token.

Besides the methods for tools, resources and prompts, each client keeps a record of its own, for debugging:

server

With only baseUrl, there's no process: info has no pid, getLogs() is always empty, and restart() only waits for the URL to answer, then reconnects the clients.

server.createClient(options?)

It resolves to a connected McpTestClient, the same kind as mcp, and rejects when the server refuses to initialize, with a message like Failed to initialize MCP connection to http://localhost:51000/ after 1 attempt: HTTP 401: Unauthorized - {"error":"Unauthorized"}. The library disconnects the client when the test ends.

server.createClientBuilder()

Returns a builder for the server's URL, with test.use()'s entryPath and publicMode. Each method returns the builder; build() returns an unconnected client, and buildAndConnect() a connected one.

auth

Makes signed JWTs for your tests. With no JWT_SECRET in test.use({ env }), it signs with an RSA key of its own, which your server doesn't know; with one, it signs the way a public, local or remote server does, so that server accepts them. Testing authentication covers each auth mode.

Hooks

test.beforeEach(fn) and test.afterEach(fn) with a function that takes a parameter run as part of each test, and receive its fixtures: the same mcp, server and auth the test gets. beforeEach runs after the client connects and before the test; afterEach runs after the test, even when it failed, and before the clients are disconnected. Hooks in an outer test.describe run before an inner block's beforeEach, and after its afterEach.

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

test.use({ server: "./src/main.ts" });

test.beforeEach(async ({ mcp }) => {
  await mcp.tools.call("reset_desk");
});

test("closes a ticket", async ({ mcp }) => {
  expect(await mcp.tools.call("close_ticket", { id: "T-1" })).toBeSuccessful();
});

A hook function without a parameter, and every test.beforeAll and test.afterAll, is Jest's own, and gets no fixtures: use them for what isn't the server, like a mock API or a mock identity provider. beforeAll runs before the server starts, so a mock you start there is up when the server connects to it, and a URL it puts in test.use()'s env object reaches the server.

Before 1.9.0 every hook was Jest's, so a hook that took a parameter waited for a done callback until the test timed out. Jest's done style no longer works for test.beforeEach and test.afterEach.

Caveats

• test.beforeAll and test.afterAll with a parameter wait for done. Jest treats a hook whose function takes an argument as a callback hook, so test.beforeAll(async ({ mcp }) => …) never finishes, and fails after the test timeout, 60 seconds under frontmcp test. See Troubleshooting.
• test.each and test.describe.each pass each row's values to the function: see Running a test for each input.
• Tests run one at a time within a file, in the order they're written, and each file starts its own servers.
• Files can run in parallel. Without --runInBand, Jest runs files in parallel workers, and each file's servers get different ports. --runInBand runs one file at a time, which is the quieter choice for tests that each start a server.

Usage

Sharing the server between tests

Each test gets a new client, but the server is the same one, so what one test changes, the next one sees. The Playground runs its tests the same way: one server per run, a new mcp for each test.

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

test("opens the first ticket", async ({ mcp }) => {
  const result = await mcp.tools.call("open_ticket", { title: "Cannot log in" });
  expect(result.json()).toEqual({ id: "T-1", title: "Cannot log in" });
});

test("the next test sees the same server", async ({ mcp }) => {
  // T-1 was opened by the test above, on another client.
  const result = await mcp.tools.call("open_ticket", { title: "Invoice total is wrong" });
  expect(result.json()).toEqual({ id: "T-2", title: "Invoice total is wrong" });
});

test("a test that doesn't depend on the others", async ({ mcp }) => {
  const before = (await mcp.tools.call("list_tickets")).json().tickets.length;
  await mcp.tools.call("open_ticket", { title: "Login link expired" });
  const after = (await mcp.tools.call("list_tickets")).json().tickets.length;
  expect(after).toBe(before + 1);
});

The second test passes only because the first one ran before it. The third checks the change it made, so it passes whatever ran before. Under frontmcp test, the same file, named e2e/tickets.e2e.spec.ts, needs test.use({ server: "./src/main.ts" }) at the top; the Playground accepts test.use() and ignores it.

Two configurations of a server

test.use() in a test.describe gives that block its own options, and its own server. Here the two blocks start a server each, with a different DESK_NAME, and each server stops when its block ends:

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

test.describe("north", () => {
  test.use({ server: "./src/main.ts", env: { DESK_NAME: "north" } });

  test("north desk", async ({ mcp }) => {
    expect((await mcp.tools.call("desk_name")).json()).toMatchObject({ name: "north" });
  });
});

test.describe("south", () => {
  test.use({ server: "./src/main.ts", env: { DESK_NAME: "south" } });

  test("south desk", async ({ mcp }) => {
    expect((await mcp.tools.call("desk_name")).json()).toMatchObject({ name: "south" });
  });
});

Options you set at the top of the file apply to every block, so a file whose blocks differ in one option can set server once at the top and only env in each block. Before 1.8.7, both blocks above started a server with DESK_NAME=south, and tests needing two configurations of a server went in two files.

Calling as several clients

server.createClient() connects another client to the same server, with its own session, token or client name. The library disconnects it when the test ends, so make it in the test that uses it.

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

test.use({ server: "./src/main.ts" });

test("each client has its own session", async ({ mcp, server }) => {
  const cli = await server.createClient({ clientInfo: { name: "desk-cli", version: "2.0.0" } });
  expect(cli.sessionId).not.toBe(mcp.sessionId);
  expect(cli.transport_info.lastRequestHeaders["User-Agent"]).toBe("desk-cli/2.0.0");
  expect(await cli.tools.call("search_tickets", { query: "log" })).toBeSuccessful();
});

For clients that call as a signed-in user, see Testing authentication.

Restarting the server

server.restart() starts a fresh process on the same port, with nothing in memory, and reconnects mcp and every client made with server.createClient(), each with a new session:

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

test.use({ server: "./src/main.ts" });

test("a restart forgets what the server kept in memory", async ({ mcp, server }) => {
  await mcp.tools.call("search_tickets", { query: "log" });
  expect((await mcp.tools.call("server_calls")).json()).toEqual({ calls: 1 });

  const { pid } = server.info;
  await server.restart();
  expect(server.info.pid).not.toBe(pid);
  expect((await mcp.tools.call("server_calls")).json()).toEqual({ calls: 0 });
});

Before 1.8.7 the clients kept the old session, so the next call failed with HTTP 401: Unauthorized (a server with no JWT_SECRET, whose anonymous tokens died with the process) or HTTP 404: Not Found (invalid session id), both code -32000, until the test called await mcp.reconnect().

Reading the server's logs

server.getLogs() is what the server printed. Clear it first to look at one call:

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

test.use({ server: "./src/main.ts" });

test("the call reaches the tool", async ({ mcp, server }) => {
  server.clearLogs();
  await mcp.tools.call("search_tickets", { query: "log" });
  const logs = server.getLogs().join("");
  expect(logs).toContain("tools/call: search_tickets");
});

Join the chunks before searching: a line can arrive split across two.

Running a test for each input

test.each(table)(name, fn) registers a test for each row. fn receives the fixtures, then the row's values; the name takes Jest's %s, %i and %j:

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

test.use({ server: "./src/main.ts" });

test.each(["log", "LOG", "Log"])('search_tickets ignores case: "%s"', async ({ mcp }, query) => {
  const result = await mcp.tools.call("search_tickets", { query });
  expect(result.json().tickets.map((t: { id: string }) => t.id)).toEqual(["T-1", "T-2"]);
});

test.each([
  ["log", ["T-1", "T-2"]],
  ["invoice", ["T-3"]],
])("search_tickets finds %s", async ({ mcp }, query, ids) => {
  const result = await mcp.tools.call("search_tickets", { query });
  expect(result.json().tickets.map((t: { id: string }) => t.id)).toEqual(ids);
});

A row that is an array is spread into arguments; any other value is one argument. test.describe.each(table)(name, body) passes each row to body, and a tagged template works for both. Before 1.8.7 there was no test.each, and test.describe.each called its function with no arguments, so tests looped over the values instead.

Testing a server that's already running

With baseUrl and no server, the library starts nothing and connects to the URL, such as a staging server or one you start yourself:

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

test.use({ baseUrl: process.env.DESK_URL ?? "http://localhost:3000" });

test("search_tickets is listed", async ({ mcp }) => {
  expect(await mcp.tools.list()).toContainTool("search_tickets");
});

Mocking HTTP starts a server in the test's own process this way, so httpMock can see its requests.

Troubleshooting

"Exceeded timeout of 60000 ms for a hook while waiting for done() to be called"

A test.beforeAll or test.afterAll function takes a parameter, like test.beforeAll(async ({ mcp }) => …). Those hooks are Jest's, get no fixtures, and Jest takes the parameter for a done callback that never comes. Work that needs the server goes in test.beforeEach, which gets the fixtures:

// 🚩 Waits for done() until it times out
test.beforeAll(async ({ mcp }) => {
  await mcp.tools.call("reset_desk");
});

// ✅ Runs before each test, with its fixtures
test.beforeEach(async ({ mcp }) => {
  await mcp.tools.call("reset_desk");
});

Before 1.9.0, test.beforeEach and test.afterEach timed out the same way.

[TestFixture] MCP client could not connect anonymously, then Session not initialized — send `initialize` first

The server requires a token, so the mcp fixture couldn't connect. Sign it in with await mcp.authenticate(token), or connect a client of your own with a token: await server.createClient({ token: await auth.createToken({ sub: "agent-1" }) }). Testing authentication shows which token each auth mode accepts.

"Server did not become ready within 30000ms"

The server started but never answered on its port. Check that it listens on process.env.PORT, run the command from the error yourself, or set logLevel: "debug" to see what it prints. A server that's slow to start needs a larger startupTimeout.

Not connected to MCP server. Call connect() first. from a client of your own

The client came from server.createClient() in an earlier test, and the library disconnected it when that test ended. Make the client inside the test that uses it.

A test passes alone but fails with the others

The tests share one server, so an earlier test can leave data behind. Make each test set up what it needs, or check the change it made: see Sharing the server between tests.