fastmcp/docs/python-sdk/fastmcp-utilities-tests.mdx

---
title: tests
sidebarTitle: tests
---

# `fastmcp.utilities.tests`

## Functions

### `temporary_settings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
temporary_settings(**kwargs: Any)
```


Temporarily override FastMCP setting values.

**Args:**
- `**kwargs`: The settings to override, including nested settings.


### `run_server_in_process` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_server_in_process(server_fn: Callable[..., None], *args: Any, **kwargs: Any) -> Generator[str, None, None]
```


Context manager that runs a FastMCP server in a separate process and
returns the server URL. When the context manager is exited, the server process is killed.

**Args:**
- `server_fn`: The function that runs a FastMCP server. FastMCP servers are
not pickleable, so we need a function that creates and runs one.
- `*args`: Arguments to pass to the server function.
- `provide_host_and_port`: Whether to provide the host and port to the server function as kwargs.
- `host`: Host to bind the server to (default\: "127.0.0.1").
- `port`: Port to bind the server to (default\: find available port).
- `**kwargs`: Keyword arguments to pass to the server function.

**Returns:**
- The server URL.


### `run_server_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_server_async(server: FastMCP, port: int | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http', path: str = '/mcp', host: str = '127.0.0.1') -> AsyncGenerator[str, None]
```


Start a FastMCP server on a real port as an asyncio task.

This runs a real uvicorn server in the current process, bound to a real TCP port,
and yields its URL. Use it when the behaviour under test is genuinely about the
network — real sockets, TLS, or a server that must be reachable by something other
than an in-process client. Otherwise prefer `asgi_client` or `asgi_server`, which
exercise the same HTTP stack without binding a port.

**Args:**
- `server`: FastMCP server instance
- `port`: Port to bind to (default\: find available port)
- `transport`: Transport type ("http", "streamable-http", or "sse")
- `path`: URL path for the server (default\: "/mcp")
- `host`: Host to bind to (default\: "127.0.0.1")


### `asgi_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asgi_server(server: FastMCP, transport: Literal['http', 'streamable-http', 'sse'] = 'http', path: str | None = None, **http_app_kwargs: Any) -> AsyncGenerator[ASGIServer, None]
```


Serve a FastMCP server's HTTP app in-process, with no socket and no uvicorn.

This is the fastest way to test a FastMCP server over HTTP. The server's real
Starlette app is built with `http_app()` and its lifespan is started, then every
request is dispatched directly into the app on the current event loop. That skips
port binding, uvicorn startup and connection setup entirely, while still exercising
the full HTTP stack: middleware, authentication, session management and SSE
streaming all run exactly as they do in production.

Use this as a fixture when several tests share one server but each needs its own
client. For a single test, `asgi_client` hands you a connected client in one step.

**Args:**
- `server`: FastMCP server instance.
- `transport`: Transport type ("http", "streamable-http", or "sse").
- `path`: URL path for the server (defaults to "/mcp", or "/sse" for SSE).
- `**http_app_kwargs`: Additional arguments forwarded to `server.http_app()`.


### `asgi_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
asgi_client(server: FastMCP, transport: Literal['http', 'streamable-http', 'sse'] = 'http', path: str | None = None, **client_kwargs: Any) -> AsyncGenerator[Client, None]
```


Serve a FastMCP server over HTTP in-process and yield a connected `Client`.

This is the shortest path to testing a server over a real HTTP stack. The server's
Starlette app is built and started, and requests are dispatched straight into it on
the current event loop — no port, no uvicorn, no subprocess — but middleware,
authentication, session management and SSE streaming all behave as in production.

Reach for `asgi_server` instead when a fixture must serve several tests that each
build their own client, or when a test needs raw HTTP access to the app.

**Args:**
- `server`: FastMCP server instance.
- `transport`: Transport type ("http", "streamable-http", or "sse").
- `path`: URL path for the server (defaults to "/mcp", or "/sse" for SSE).
- `headers`: HTTP headers to send with every request.
- `auth`: Client authentication, as accepted by the HTTP transports.
- `**client_kwargs`: Additional arguments forwarded to `Client`.


## Classes

### `ASGIServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A FastMCP server's real HTTP app, reachable in-process with no sockets.

Yielded by `asgi_server`. The `url` looks like an ordinary server URL and the app
behind it is the genuine article — auth middleware, session manager, SSE framing and
redirects all run — but every request is dispatched straight into the ASGI
application on the current event loop.

Because nothing is listening on the network, a plain `httpx2.AsyncClient()` cannot
reach this server. Use `client()` for a FastMCP client, `http_client()` for raw HTTP
assertions, and `transport()` when you need to build the client transport yourself.


**Methods:**

#### `http_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
http_client(self, headers: dict[str, str] | None = None, timeout: httpx2.Timeout | None = None, auth: httpx2.Auth | None = None, **kwargs: Any) -> httpx2.AsyncClient
```

An `httpx2.AsyncClient` bound to the in-process app, for raw HTTP assertions.

Relative URLs resolve against the server's base URL, and absolute URLs on the
same origin work too, so `client.get(f"{server.url}/health")` reads the same as
it would against a real server.

The signature matches `McpHttpClientFactory`, so this method can also be handed
to anything that takes an `httpx_client_factory`.


#### `transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
transport(self, **kwargs: Any) -> StreamableHttpTransport | SSETransport
```

A FastMCP client transport wired to the in-process app.

Accepts the same keyword arguments as the underlying transport (`headers`,
`auth`, ...); `httpx_client_factory` is supplied automatically.


#### `client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L313" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
client(self, **client_kwargs: Any) -> Client
```

An unconnected FastMCP `Client` pointed at the in-process app.

`headers` and `auth` configure the underlying HTTP transport; every other
keyword argument is passed to `Client` (`timeout`, `elicitation_handler`, ...).
Use it as a context manager, exactly like any other client.

**Args:**
- `headers`: HTTP headers to send with every request.
- `auth`: Client authentication, as accepted by the HTTP transports.
- `**client_kwargs`: Additional arguments forwarded to `Client`.


### `HeadlessOAuth` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L464" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


OAuth provider that bypasses browser interaction for testing.

This simulates the complete OAuth flow programmatically by making HTTP requests
instead of opening a browser and running a callback server. Useful for automated testing.


**Methods:**

#### `redirect_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L477" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
redirect_handler(self, authorization_url: str) -> None
```

Make HTTP request to authorization URL and store response for callback handler.


#### `callback_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/tests.py#L483" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
callback_handler(self) -> AuthorizationCodeResult
```

Parse stored response and return the authorization code result.