tests: close the docs test modules' branch-coverage gaps

CI requires 100% branch coverage over tests/ as well as src/, and the
new docs test modules left four statements and a handful of branch arcs
uncovered.

The statements were real gaps, each closed by making the test stronger
rather than weaker:

- test_deploy: the shared-key-different-name test now also lands the
  retry back on the instance that minted the token and asserts it
  completes. That is the half of the story the page tells, and it is
  exactly what the sibling default-key test already proved.
- test_troubleshooting: two decorated functions whose bodies can never
  run (one's decoration is what raises; the other is the duplicate that
  gets dropped) now have docstring-only bodies, and the
  connection-fails case enters the client explicitly with __aenter__()
  (the shape tests/client/test_client.py already uses) instead of an
  `async with` whose body is unreachable by design.

The rest were not real: every remaining flagged line executes (zero
missed statements); coverage.py misattributes arcs around nested
`async with` bodies on newer Pythons, worst on 3.14, which is exactly
the case AGENTS.md documents for `# pragma: no branch` (branch arcs
only; ~180 existing uses across src/ and tests/). Six of those, one of
them on a straight-line test that raises nothing at all.

./scripts/test (the CI-equivalent gate) now reports 100.00% and
strict-no-cover passes.

Author: maxisbey

tests/docs_src/test_deploy.py

@@ -160,8 +160,12 @@ async def refund(amount: int, ctx: Context) -> str | InputRequiredResult:
             token = await _first_round(on_one, 120)
             with pytest.raises(MCPError) as exc:
                 await _retry(on_two, 120, token)
+            # Same keys AND the same name: back on the instance that minted it, the retry completes.
+            second = await _retry(on_one, 120, token)
 
     _assert_frozen_rejection(exc)
+    assert isinstance(second, CallToolResult)
+    assert second.content == [TextContent(type="text", text="refunded $120")]
 
 
 # -- change notifications across replicas ----------------------------------------------

tests/docs_src/test_legacy_clients.py

@@ -105,7 +105,7 @@ async def test_stateless_http_kills_the_legacy_back_channel_and_only_the_legacy_
         legacy_target = streamable_http_client(URL, http_client=http)
         async with Client(legacy_target, mode="legacy", elicitation_callback=tutorial001.answer) as legacy:
             assert legacy.protocol_version == "2025-11-25"
-            with pytest.raises(MCPError) as exc_info:
+            with pytest.raises(MCPError) as exc_info:  # pragma: no branch
                 await legacy.call_tool("reserve", {"title": "Dune"})
     assert exc_info.value.error.code == INVALID_REQUEST
     assert exc_info.value.error.message == (

tests/docs_src/test_troubleshooting.py

@@ -98,9 +98,8 @@ async def test_the_tool_decorator_without_parentheses_raises_at_import_time() ->
     with pytest.raises(TypeError, match=r"Use @tool\(\) instead of @tool"):
 
         @undecorated
-        def forecast(city: str) -> str:
-            """Today's forecast for one city."""
-            return f"{city}: Rain."
+        def forecast(city: str) -> None:
+            """Today's forecast for one city. Never called: the decoration itself is what raises."""
 
 
 async def test_a_duplicate_tool_name_keeps_the_first_and_drops_the_second() -> None:
@@ -116,9 +115,8 @@ async def test_a_duplicate_registration_logs_tool_already_exists(caplog: pytest.
     with caplog.at_level(logging.WARNING, logger="mcp.server.mcpserver.tools.tool_manager"):
 
         @tutorial002.mcp.tool(name="forecast")
-        def forecast_weekly(city: str) -> str:
-            """The week ahead for one city."""
-            return f"{city}: Rain all week."
+        def forecast_weekly(city: str) -> None:
+            """The week ahead for one city. Never called: it is the duplicate that gets dropped."""
 
     assert "Tool already exists: forecast" in caplog.messages
 
@@ -140,9 +138,9 @@ async def test_the_default_streamable_http_app_answers_a_real_hostname_with_421(
         assert "Invalid Host header: mcp.example.com" in caplog.messages
         # What the python `Client` raises instead: the generic stand-in, wrapped by the task group.
         async with httpx.AsyncClient(transport=transport) as http_client:
-            with pytest.raises(Exception) as exc_info:
-                async with Client(streamable_http_client("http://mcp.example.com/mcp", http_client=http_client)):
-                    pass  # never reached: the handshake itself is what fails
+            client = Client(streamable_http_client("http://mcp.example.com/mcp", http_client=http_client))
+            with pytest.raises(Exception) as exc_info:  # pragma: no branch
+                await client.__aenter__()  # the connection attempt itself is what fails
     assert not isinstance(exc_info.value, MCPError)
     assert exc_info.group_contains(MCPError, match="^Server returned an error response$")
 
@@ -152,7 +150,8 @@ async def test_an_allowlisted_hostname_connects_and_calls_a_tool() -> None:
     transport = httpx.ASGITransport(app=tutorial004.app)
     async with tutorial004.mcp.session_manager.run():
         async with httpx.AsyncClient(transport=transport) as http_client:
-            async with Client(streamable_http_client("http://mcp.example.com/mcp", http_client=http_client)) as c:
+            allowed = streamable_http_client("http://mcp.example.com/mcp", http_client=http_client)
+            async with Client(allowed) as c:  # pragma: no branch
                 assert c.protocol_version == "2026-07-28"
                 result = await c.call_tool("forecast", {"city": "London"})
     assert result.structured_content == {"result": "London: Rain."}
@@ -247,8 +246,9 @@ async def test_ctx_elicit_over_stateless_http_has_no_back_channel() -> None:
     transport = httpx.ASGITransport(app=tutorial008.app)
     async with tutorial008.mcp.session_manager.run():
         async with httpx.AsyncClient(transport=transport) as http_client:
-            async with Client(streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http_client)) as c:
-                with pytest.raises(MCPError) as exc_info:
+            stateless = streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http_client)
+            async with Client(stateless) as c:  # pragma: no branch
+                with pytest.raises(MCPError) as exc_info:  # pragma: no branch
                     await c.call_tool("book_table", {"date": "Friday"})
     assert exc_info.value.error == ErrorData(
         code=INVALID_REQUEST,
@@ -263,7 +263,7 @@ async def test_a_request_state_the_server_did_not_mint_is_rejected(caplog: pytes
     """The wire message is deliberately frozen; the real reason goes only to the server log."""
     async with Client(tutorial001.mcp) as client:
         with caplog.at_level(logging.WARNING, logger="mcp.server.request_state"):
-            with pytest.raises(MCPError) as exc_info:
+            with pytest.raises(MCPError) as exc_info:  # pragma: no branch
                 await client.call_tool("forecast", {"city": "London"}, request_state="round-1-from-worker-a")
     assert exc_info.value.error == ErrorData(
         code=INVALID_PARAMS, message="Invalid or expired requestState", data={"reason": "invalid_request_state"}