Documentation inconsistency: Client fixture pattern vs inline client creation

[healthkowshik]

Noticed conflicting guidance between official documentation and blog post regarding recommended pattern for testing MCP tools.

Official Documentation

Ref: https://gofastmcp.com/patterns/testing

The docs recommend an async fixture that yields the client:

  from my_project.main import mcp                                                                                                                                                                               
                                                                                                                                                                                                                
  @pytest.fixture                                                                                                                                                                                               
  async def main_mcp_client():                                                                                                                                                                                  
      async with Client(transport=mcp) as mcp_client:                                                                                                                                                           
          yield mcp_client                                                                                                                                                                                      
                                                                                                                                                                                                                
  async def test_add_tool(main_mcp_client: Client[FastMCPTransport]):                                                                                                                                           
      result = await main_mcp_client.call_tool("add", {"a": 1, "b": 2})                                                                                                                                         
      assert result[0].text == "3"

Blog Post

Ref: https://www.jlowin.dev/blog/stop-vibe-testing-mcp-servers

The blog recommends creating the client inline within each test:

  from my_project.main import mcp                                                                                                                                                                               
                                                                                                                                                                                                                
  async def test_add_tool():                                                                                                                                                                                    
      async with Client(mcp) as client:                                                                                                                                                                         
          result = await client.call_tool("add", {"a": 1, "b": 2})                                                                                                                                              
          assert result[0].text == "3"

The blog includes a "Nerd note" that explicitly warns against the pattern shown in the official docs:

Questions

1. Which pattern is currently recommended?
2. Should the documentation be updated to align with one approach?

Thanks for the clarification!

[FBegiello]

I'm not sure about the official approach, but I'd follow the second pattern, possibly a variant using a reusable factory like this

import pytest
from contextlib import asynccontextmanager
from fastmcp import Client

@pytest.fixture
def client_factory(mcp_server):
    @asynccontextmanager
    async def _make():
        async with Client(mcp_server) as client:
            yield client
    return _make

async def test_add_tool(client_factory):
    async with client_factory() as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        assert result[0].text == "3"

As per pytest-asyncio test and the fixture run in different asyncio event loops and each pytest scope has its own event loop - so the issue presented in the blogpost seems to be accurate.