Tests

Test the behavior a user relies on through the smallest boundary that exercises it. Most FastMCP tests can use a real server and client in memory. HTTP and subprocess helpers cover behavior that depends on those transports.

Run tests

Install the repository dependencies before running tests:

uv sync
uv run pytest -n auto

During development, run the owning test module or select a behavior by name:

uv run pytest tests/client/client/test_client.py -n 0
uv run pytest tests/server -k list_tools -n 0

Use -n 0 for a single process when debugging. The full suite uses pytest-xdist for parallel execution. To run the same marker selection as the unit CI job:

uv run pytest -n auto -m "not integration and not client_process and not subprocess_heavy and not conformance"

The default timeout is five seconds, and asyncio_mode = "auto" enables async tests without @pytest.mark.asyncio. These settings and the registered markers live in pyproject.toml.

Test organization and markers

Extend the module that owns the behavior, using nearby tests and fixtures as the starting point. The test tree generally mirrors the library: authentication tests are under tests/server/auth/, client tests under tests/client/, and resource tests under tests/resources/.

Marker	Use
`integration`	Tests needing integration resources or longer execution; CI gives this group a longer timeout.
`client_process`	Tests spawning client processes through stdio.
`subprocess_heavy`	Tests starting a fresh Python interpreter that imports FastMCP.
`conformance`	MCP conformance tests requiring Node.js and npx.

The pytest CI action runs client_process and subprocess_heavy serially and excludes them from parallel unit tests. A minimal stdlib subprocess does not need subprocess_heavy merely because it is a subprocess. Use the marker when the fresh interpreter imports FastMCP. A marker selects a CI group; it does not itself change the local timeout. To reproduce the integration group’s timeout locally:

uv run pytest -m integration --timeout=30 -n 0

Write a regression that proves the contract

First establish the promised behavior from the public API, docs, protocol, and relevant maintainer decisions. A reproducible result is not automatically a bug. Once the contract is clear, run the regression on the unchanged base and confirm that it fails for the intended reason, then run it with the fix. An import error or broken fixture is not evidence of the reported defect. Assert values and types that distinguish the correct result from the bug. For example, Python equality treats True and 1 as equal, so a JSON type-preservation test needs a type assertion too. Avoid assertions that only check whether some result exists when the result’s contents are the contract. Keep each test focused on one behavior, with as many assertions as that behavior needs. Parameterize variations of the same contract; separate unrelated cases. Include omitted defaults and explicit overrides when both enter the changed branch. Use function-scoped setup and temporary paths so tests work independently and in parallel. Prefer events or waits for the exact condition being asserted to arbitrary sleeps. When diagnosing a failure, separate an assertion failure from a worker crash or infrastructure error; reproduce a supposedly pre-existing failure on the unchanged base before calling it unrelated.

Test through an in-memory client

Client(server) exercises real FastMCP dispatch and protocol behavior without opening a socket. This complete test checks how arguments and results travel through the client:

from fastmcp import Client, FastMCP


async def test_add_returns_sum() -> None:
    server = FastMCP("Calculator")

    @server.tool
    def add(a: int, b: int) -> int:
        return a + b

    async with Client(server) as client:
        result = await client.call_tool("add", {"a": 2, "b": 3})

    assert result.data == 5
    assert type(result.data) is int

Save examples as a test module in the repository and run them with uv run pytest path/to/test_example.py -n 0. Use the existing fixture patterns for the subsystem instead of mocking the FastMCP method under test.

Failure behavior

Assert the exception users receive, including a meaningful message when that is part of the behavior:

import pytest

from fastmcp import Client, FastMCP
from fastmcp.exceptions import ToolError


async def test_division_by_zero_is_reported() -> None:
    server = FastMCP("Calculator")

    @server.tool
    def divide(a: float, b: float) -> float:
        if b == 0:
            raise ValueError("Cannot divide by zero")
        return a / b

    async with Client(server) as client:
        with pytest.raises(ToolError, match="Cannot divide by zero"):
            await client.call_tool("divide", {"a": 10, "b": 0})

Reusable fixtures

Build the server in a fixture and manage the client context in the test. This keeps connection ownership and cleanup visible:

import pytest

from fastmcp import Client, FastMCP


@pytest.fixture
def weather_server() -> FastMCP:
    server = FastMCP("Weather")

    @server.tool
    def temperature(city: str) -> int:
        return {"NYC": 72, "LA": 85}[city]

    return server


@pytest.mark.parametrize(("city", "expected"), [("NYC", 72), ("LA", 85)])
async def test_temperature(weather_server: FastMCP, city: str, expected: int) -> None:
    async with Client(weather_server) as client:
        result = await client.call_tool("temperature", {"city": city})

    assert result.data == expected

Schema snapshots

Use the repository’s inline-snapshot conventions for complex structures. Inspect each generated expectation against the contract before accepting it. This example checks the schema returned through the protocol:

from inline_snapshot import snapshot

from fastmcp import Client, FastMCP


async def test_tool_input_schema() -> None:
    server = FastMCP("Calculator")

    @server.tool
    def double(value: int) -> int:
        return value * 2

    async with Client(server) as client:
        tools = await client.list_tools()

    assert tools[0].input_schema == snapshot(
        {
            "type": "object",
            "properties": {"value": {"type": "integer"}},
            "required": ["value"],
            "additionalProperties": False,
        }
    )

The repository disables snapshot updates by default. For an intentional change, run the relevant module with --inline-snapshot=fix and review the diff. Use --inline-snapshot=create when populating a new empty snapshot.

Test HTTP behavior without a socket

Use asgi_client when the subject is HTTP routing, headers, authentication, or streaming. It builds the real application and starts its lifespan, then sends requests directly through ASGI in the same process:

from fastmcp import FastMCP
from fastmcp.utilities.tests import asgi_client


async def test_greet_over_http() -> None:
    server = FastMCP("Greeting")

    @server.tool
    def greet(name: str) -> str:
        return f"Hello, {name}!"

    async with asgi_client(server) as client:
        result = await client.call_tool("greet", {"name": "World"})

    assert result.data == "Hello, World!"

Pass headers= or auth= to configure requests, path= for a custom MCP route, or transport="sse" to exercise the SSE application. Other client options, such as timeout=, go to Client.

Multiple clients and raw requests

Use asgi_server when a test needs several clients or raw HTTP responses. Each client() call creates its own client. http_client() returns an httpx2.AsyncClient bound to the same application; an ordinary network client cannot reach this in-process server.

from fastmcp import FastMCP
from fastmcp.utilities.tests import asgi_server


async def test_two_clients_share_the_application() -> None:
    server = FastMCP("Empty")

    async with asgi_server(server) as running:
        async with running.client() as first, running.client() as second:
            assert await first.list_tools() == []
            assert await second.list_tools() == []

        async with running.http_client() as http:
            response = await http.get("/missing")
            assert response.status_code == 404

A test specifically about legacy MCP sessions or ping should pass mode="legacy" to the client. The modern protocol era is sessionless; see protocol negotiation. For custom client transports, running.transport() returns a transport wired to the same application.

Test external and process boundaries

Mock external services at their boundary, while keeping the FastMCP path real. For outgoing HTTP requests, use httpx2.MockTransport and assert the method, URL, headers, or body that matter. Do not mock the framework function whose behavior the test is meant to verify. Use run_server_async when the network itself is the subject: a socket, TLS, or a client outside the in-process application. It starts uvicorn in the current process and cleans it up on exit:

from fastmcp import Client, FastMCP
from fastmcp.utilities.tests import run_server_async


async def test_server_accepts_network_requests() -> None:
    server = FastMCP("Empty")

    async with run_server_async(server) as url:
        async with Client(url) as client:
            assert await client.list_tools() == []

Use run_server_in_process only when process isolation is part of the test. Follow nearby subprocess fixtures for startup, transport selection, and cleanup. Stdio lifecycle tests can use tests/client/minimal_stdio_server.py when a minimal MCP responder suffices; use a real FastMCP subprocess when its behavior is what you need to test.

Check documentation examples

Run the documentation checks from the repository root:

just docs-broken-links
uv run pytest tests/docs -n 0

The docs tests parse Python fences and resolve FastMCP imports. They do not execute every example or detect every missing non-import name, so run changed examples yourself. Use just docs to preview rendering. Without just, run npx --yes mint@latest broken-links or npx --yes mint@latest dev from docs/. See the Contributing Guide for the full checks required before committing.

Get Started

Servers

Apps

Clients

Integrations

More

Run tests

Test organization and markers

Write a regression that proves the contract

Test through an in-memory client

Failure behavior

Reusable fixtures

Schema snapshots

Test HTTP behavior without a socket

Multiple clients and raw requests

Test external and process boundaries

Check documentation examples

​Run tests

​Test organization and markers

​Write a regression that proves the contract

​Test through an in-memory client

​Failure behavior

​Reusable fixtures

​Schema snapshots

​Test HTTP behavior without a socket

​Multiple clients and raw requests

​Test external and process boundaries

​Check documentation examples

Run tests

Test organization and markers

Write a regression that proves the contract

Test through an in-memory client

Failure behavior

Reusable fixtures

Schema snapshots

Test HTTP behavior without a socket

Multiple clients and raw requests

Test external and process boundaries

Check documentation examples