--- title: tests sidebarTitle: tests --- # `fastmcp.utilities.tests` ## Functions ### `temporary_settings` ```python temporary_settings(**kwargs: Any) ``` Temporarily override FastMCP setting values. **Args:** - `**kwargs`: The settings to override, including nested settings. ### `run_server_in_process` ```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` ```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` ```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` ```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` 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` ```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` ```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` ```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` 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` ```python redirect_handler(self, authorization_url: str) -> None ``` Make HTTP request to authorization URL and store response for callback handler. #### `callback_handler` ```python callback_handler(self) -> AuthorizationCodeResult ``` Parse stored response and return the authorization code result.