π The fast, Pythonic way to build MCP servers and clients.
test: rewrite as integration tests with zero mocks
Guillaume FORTAINE1f84e5055ebc
diff --git a/tests/server/tasks/test_context_background_task.py b/tests/server/tasks/test_context_background_task.pyindex b778a63b2..0cdc9636a 100644--- a/tests/server/tasks/test_context_background_task.py+++ b/tests/server/tasks/test_context_background_task.py@@ -1,11 +1,23 @@-"""Tests for Context background task support (SEP-1686)."""+"""Tests for Context background task support (SEP-1686).++Tests Context API surface (unit) and background task elicitation (integration).+Integration tests use Client(mcp) with the real memory:// Docket backend β+no mocking of Redis, Docket, or session internals.+"""++import asyncioimport pytestfrom fastmcp import FastMCP+from fastmcp.client import Clientfrom fastmcp.server.context import Context-from fastmcp.server.elicitation import AcceptedElicitation-from fastmcp.server.tasks.elicitation import elicit_for_task, handle_task_input+from fastmcp.server.elicitation import AcceptedElicitation, DeclinedElicitation+from fastmcp.server.tasks.elicitation import handle_task_input++# =============================================================================+# Unit tests: Context API surface (no Redis/Docket needed)+# =============================================================================class TestContextBackgroundTaskSupport:@@ -54,7 +66,6 @@ class TestContextSessionProperty:mock_session = MockSession()ctx = Context(mcp, session=mock_session, task_id="test-task-123") # type: ignore[arg-type]- # In background task mode, should return the stored sessionassert ctx.session is mock_sessiondef test_session_uses_stored_session_during_on_initialize(self):@@ -65,23 +76,19 @@ class TestContextSessionProperty:_fastmcp_state_prefix = "test-session"mock_session = MockSession()- # Simulating on_initialize: has session but not a background taskctx = Context(mcp, session=mock_session) # type: ignore[arg-type]- # Should return the stored session as fallbackassert ctx.session is mock_sessionclass TestContextElicitBackgroundTask:"""Tests for Context.elicit() in background task mode."""- @pytest.mark.asyncioasync def test_elicit_raises_when_background_task_but_no_docket(self):"""elicit() should raise when in background task mode but Docket unavailable."""mcp = FastMCP("test")ctx = Context(mcp, task_id="test-task-123")- # Set up minimal session mockclass MockSession:_fastmcp_state_prefix = "test-session"@@ -91,6 +98,53 @@ class TestContextElicitBackgroundTask:await ctx.elicit("Need input", str)+class TestElicitFailFast:+ """Tests for elicit_for_task fail-fast on notification push failure."""++ async def test_elicit_returns_cancel_when_notification_push_fails(self):+ """elicit_for_task should return cancel immediately when push_notification fails.++ If the client can't receive the input_required notification, waiting+ for a response that will never come would block for up to 1 hour.+ Instead, we return cancel immediately (fail-fast).++ This test patches ONLY push_notification β all other components+ (Docket, Redis, session) are real via the memory:// backend.+ """+ from unittest.mock import patch++ from fastmcp.server.elicitation import CancelledElicitation++ mcp = FastMCP("failfast-test")+ elicit_started = asyncio.Event()+ captured: dict[str, object] = {}++ @mcp.tool(task=True)+ async def failfast_tool(ctx: Context) -> str:+ elicit_started.set()+ result = await ctx.elicit("This notification will fail", str)+ captured["result_type"] = type(result).__name__+ captured["is_cancelled"] = isinstance(result, CancelledElicitation)+ return "done"++ # Patch push_notification BEFORE starting client so it's active+ # when the tool runs in the Docket worker+ with patch(+ "fastmcp.server.tasks.notifications.push_notification",+ side_effect=ConnectionError("Redis queue unavailable"),+ ):+ async with Client(mcp) as client:+ task = await client.call_tool("failfast_tool", {}, task=True)+ await asyncio.wait_for(elicit_started.wait(), timeout=5.0)+ await task.wait(timeout=10.0)+ result = await task.result()+ assert result.data == "done"++ # The tool should have received CancelledElicitation (fail-fast)+ assert captured["is_cancelled"] is True+ assert captured["result_type"] == "CancelledElicitation"++class TestContextDocumentation:"""Tests to verify Context documentation and API surface."""@@ -110,753 +164,227 @@ class TestContextDocumentation:assert "background task" in Context.session.fget.__doc__.lower()-class TestBackgroundTaskElicitationE2E:- """End-to-end tests for background task elicitation (SEP-1686).-- These tests demonstrate the full flow:- 1. Client calls a tool with task=True (background execution)- 2. Tool uses ctx.elicit() to request user input- 3. Task status changes to "input_required"- 4. Client sends input via handle_task_input()- 5. Task resumes and completes with the elicited value-- This simulates what a client would see when interacting with- a background task that needs user input.- """-- async def test_elicit_for_task_stores_request_in_redis(self):- """Test that elicit_for_task stores the elicitation request in Redis.-- This tests the Redis coordination layer that enables client interaction.- When a background task calls elicit(), the request is stored in Redis- so clients can retrieve it and respond.- """- from unittest.mock import AsyncMock, MagicMock, patch-- from fastmcp.server.tasks.elicitation import (- elicit_for_task,- )-- # Create mocks- mock_redis = AsyncMock()- mock_redis.set = AsyncMock()- mock_redis.get = AsyncMock(return_value=None) # No response yet- mock_redis.delete = AsyncMock()-- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k-- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session-id"- mock_session.send_notification = AsyncMock()-- # Call elicit_for_task with a short timeout to avoid blocking- with patch("fastmcp.server.tasks.elicitation.ELICIT_TTL_SECONDS", 1):- with patch("fastmcp.server.tasks.elicitation.asyncio.sleep", AsyncMock()):- # Make it return after first poll- mock_redis.get = AsyncMock(- return_value=b'{"action": "accept", "content": {"value": 42}}'- )-- result = await elicit_for_task(- task_id="test-task-123",- session=mock_session,- message="Please provide a number",- schema={- "type": "object",- "properties": {"value": {"type": "integer"}},- },- fastmcp=mock_fastmcp,- )-- # Verify the result- assert result.action == "accept"- assert result.content == {"value": 42}-- # Verify Redis operations were called- assert mock_redis.set.call_count >= 2 # request + status-- async def test_handle_task_input_stores_response(self):- """Test that handle_task_input stores the response in Redis.-- This tests the client-side flow: when a client sends input via- tasks/sendInput, the response is stored in Redis for the waiting task.- """- from unittest.mock import AsyncMock, MagicMock-- # Create mocks- mock_redis = AsyncMock()- mock_redis.get = AsyncMock(return_value=b"waiting") # Status is waiting- mock_redis.set = AsyncMock()-- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k-- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- # Call handle_task_input- success = await handle_task_input(- task_id="test-task-123",- session_id="test-session-id",- action="accept",- content={"value": 42},- fastmcp=mock_fastmcp,- )-- # Verify success- assert success is True-- # Verify Redis operations- assert mock_redis.set.call_count == 2 # response + status update-- async def test_handle_task_input_rejects_when_not_waiting(self):- """Test that handle_task_input rejects input when task isn't waiting.-- This verifies proper state management - clients can only send input- when a task is actually waiting for it.- """- from unittest.mock import AsyncMock, MagicMock+# =============================================================================+# Integration tests: Client(mcp) + memory:// Docket backend+# =============================================================================- mock_redis = AsyncMock()- mock_redis.get = AsyncMock(return_value=None) # No waiting status- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k+class TestBackgroundTaskIntegration:+ """Integration tests for background task context using real Docket memory backend.- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- success = await handle_task_input(- task_id="test-task-123",- session_id="test-session-id",- action="accept",- content={"value": 42},- fastmcp=mock_fastmcp,- )-- # Should fail because no task is waiting- assert success is False-- async def test_elicit_for_task_sends_notification(self):- """Test that elicit_for_task sends input_required notification.-- Per SEP-1686, the server should send notifications/tasks/updated- with status="input_required" when a task needs input.- """- from unittest.mock import AsyncMock, MagicMock, patch-- mock_redis = AsyncMock()- mock_redis.set = AsyncMock()- mock_redis.get = AsyncMock(- return_value=b'{"action": "accept", "content": {"value": 1}}'- )- mock_redis.delete = AsyncMock()-- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k-- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session"- mock_session.send_notification = AsyncMock()-- with patch("fastmcp.server.tasks.elicitation.asyncio.sleep", AsyncMock()):- await elicit_for_task(- task_id="my-task-id",- session=mock_session,- message="Enter value",- schema={"type": "object"},- fastmcp=mock_fastmcp,- )-- # Verify notification was sent- mock_session.send_notification.assert_called_once()- notification = mock_session.send_notification.call_args[0][0]- assert notification.method == "notifications/tasks/updated"-- async def test_elicit_for_task_timeout_returns_cancel(self):- """Test that elicit_for_task returns cancel on timeout.-- If no response is received within the TTL, the elicitation- should be treated as cancelled.- """- from unittest.mock import AsyncMock, MagicMock, patch-- mock_redis = AsyncMock()- mock_redis.set = AsyncMock()- mock_redis.get = AsyncMock(return_value=None) # Never responds- mock_redis.delete = AsyncMock()-- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k-- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session"- mock_session.send_notification = AsyncMock()-- # Use very short TTL for test- with patch("fastmcp.server.tasks.elicitation.ELICIT_TTL_SECONDS", 0.1):- with patch(- "fastmcp.server.tasks.elicitation.asyncio.sleep",- AsyncMock(),- ):- result = await elicit_for_task(- task_id="timeout-task",- session=mock_session,- message="This will timeout",- schema={"type": "object"},- fastmcp=mock_fastmcp,- )-- # Should return cancel on timeout- assert result.action == "cancel"- assert result.content is None-- async def test_elicit_notification_includes_full_schema(self):- """Test that the notification includes the full JSON schema for complex types.-- This test demonstrates what the client sees when eliciting a Pydantic model.- The client receives a full JSON Schema that describes the expected input,- which they can use to:- - Render a dynamic form- - Validate user input before sending- - Show field descriptions to the user-- Example notification metadata for a UserInfo model:- ```json- {- "modelcontextprotocol.io/related-task": {- "taskId": "test-task",- "status": "input_required",- "statusMessage": "Please provide user info",- "elicitation": {- "requestId": "...",- "message": "Please provide user info",- "requestedSchema": {- "type": "object",- "properties": {- "name": {"type": "string", "title": "Name"},- "age": {"type": "integer", "title": "Age"}- },- "required": ["name", "age"],- "title": "UserInfo"- }- }- }- }- ```- """- from unittest.mock import AsyncMock, MagicMock, patch-- from pydantic import BaseModel-- class UserInfo(BaseModel):- """User information for registration."""-- name: str- age: int-- mock_redis = AsyncMock()- mock_redis.set = AsyncMock()- mock_redis.get = AsyncMock(- return_value=b'{"action": "accept", "content": {"name": "Alice", "age": 30}}'- )- mock_redis.delete = AsyncMock()-- mock_docket = MagicMock()- mock_docket.redis = MagicMock(return_value=AsyncMock())- mock_docket.redis.return_value.__aenter__ = AsyncMock(return_value=mock_redis)- mock_docket.redis.return_value.__aexit__ = AsyncMock()- mock_docket.key = lambda k: k-- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket-- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session"- mock_session.send_notification = AsyncMock()-- # Create task-aware context- ctx = Context(- mock_fastmcp,- session=mock_session,- task_id="schema-test-task",- )-- # Call elicit with a Pydantic model type- with patch("fastmcp.server.tasks.elicitation.asyncio.sleep", AsyncMock()):- result = await ctx.elicit("Please provide user info", UserInfo)-- # Verify the notification includes the full schema- mock_session.send_notification.assert_called_once()- notification = mock_session.send_notification.call_args[0][0]- meta = notification._meta- related_task = meta["modelcontextprotocol.io/related-task"]- schema = related_task["elicitation"]["requestedSchema"]-- # Verify schema structure matches UserInfo- assert schema["type"] == "object"- assert "properties" in schema- assert "name" in schema["properties"]- assert "age" in schema["properties"]- assert schema["properties"]["name"]["type"] == "string"- assert schema["properties"]["age"]["type"] == "integer"- assert "required" in schema- assert set(schema["required"]) == {"name", "age"}-- # Verify the result is properly parsed into the Pydantic model- assert result.action == "accept"- assert isinstance(result, AcceptedElicitation) # Type narrowing- assert isinstance(result.data, UserInfo)- assert result.data.name == "Alice"- assert result.data.age == 30---class TestBackgroundTaskContextWiring:- """Integration tests for Context wiring in Docket workers.-- These tests verify that when a background task runs in a Docket worker,- the Context dependency is properly created with task_id and session,- allowing ctx.elicit() to work transparently.-- Per Chris Guidry's review request: "Could we get at least one test showing- the end-to-end of it working, with a background task that's eliciting input?- This will help with what the client-side sees when this happens."-- The key test is `test_context_elicit_full_flow_with_mocked_redis` which shows:-- CLIENT RECEIVES:- notifications/tasks/updated with:- - taskId: the background task ID- - status: "input_required"- - statusMessage: the elicit prompt- - elicitation.requestedSchema: JSON schema for expected input-- CLIENT RESPONDS:- handle_task_input(task_id, session_id, action="accept", content={...})-- TOOL RECEIVES:- AcceptedElicitation(action="accept", data=<parsed value>)+ These tests use Client(mcp) with the memory:// broker β no mocking.+ The memory:// backend provides a fully functional in-memory Redis store+ that Docket uses automatically when running tests."""- async def test_context_is_created_with_task_id_in_worker(self):- """Test that Context is created with task_id when running in Docket worker.-- This verifies the wiring from _CurrentContext that creates a task-aware- Context when get_task_context() returns TaskContextInfo.- """- from unittest.mock import MagicMock, patch-- from fastmcp.server.dependencies import (- TaskContextInfo,- _current_server,- _CurrentContext,- _task_sessions,- )-- # Set up mock server- mock_server = MagicMock()- mock_server._docket = MagicMock()- server_token = _current_server.set(MagicMock(return_value=mock_server))-- # Set up mock session in registry- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session-id"- _task_sessions["test-session-id"] = MagicMock(return_value=mock_session)-- try:- # Mock get_task_context to return TaskContextInfo- task_info = TaskContextInfo(- task_id="test-task-123",- session_id="test-session-id",- )- with patch(- "fastmcp.server.dependencies.get_task_context",- return_value=task_info,- ):- # Create the dependency and enter it- dep = _CurrentContext()- ctx = await dep.__aenter__()-- # Verify context is task-aware- assert ctx.is_background_task is True- assert ctx.task_id == "test-task-123"- assert ctx.session is mock_session-- # Clean up- await dep.__aexit__(None, None, None)- finally:- _current_server.reset(server_token)- _task_sessions.pop("test-session-id", None)-- async def test_context_falls_back_to_foreground_mode(self):- """Test that Context uses foreground mode when not in worker context.-- When _current_context has a value (normal request handling),- _CurrentContext should return that context instead of creating a new one.- """- from unittest.mock import MagicMock-- from fastmcp.server.context import Context, _current_context- from fastmcp.server.dependencies import _CurrentContext-- mcp = MagicMock()- foreground_ctx = Context(mcp)-- # Set the foreground context- token = _current_context.set(foreground_ctx)- try:- dep = _CurrentContext()- ctx = await dep.__aenter__()-- # Should return the foreground context- assert ctx is foreground_ctx- assert ctx.is_background_task is False-- await dep.__aexit__(None, None, None)- finally:- _current_context.reset(token)-- async def test_session_registered_when_task_submitted(self):- """Test that session is registered when a task is submitted to Docket.-- This verifies that submit_to_docket calls register_task_session,- which enables the Context wiring in background workers.- """- import asyncio-- from fastmcp import FastMCP- from fastmcp.client import Client- from fastmcp.server.dependencies import get_task_session-- mcp = FastMCP("test-server")-- task_started = asyncio.Event()- session_id_captured = None+ async def test_report_progress_in_background_task(self):+ """report_progress() should complete without error in a background task."""+ mcp = FastMCP("progress-test")+ progress_reported = asyncio.Event()@mcp.tool(task=True)- async def capture_session_tool(ctx: Context) -> str:- """Tool that captures the session ID for verification."""- nonlocal session_id_captured- task_started.set()- # Access session to verify it works- session_id_captured = ctx.session_id+ async def progress_tool(ctx: Context) -> str:+ await ctx.report_progress(0, 100, "Starting...")+ await ctx.report_progress(50, 100, "Half done")+ await ctx.report_progress(100, 100, "Complete")+ progress_reported.set()return "done"async with Client(mcp) as client:- # Start the task- task = await client.call_tool("capture_session_tool", {}, task=True)- assert task is not None-- # Wait for the task to start- await asyncio.wait_for(task_started.wait(), timeout=5.0)-- # Verify the session was registered- assert session_id_captured is not None- # The session should be retrievable via get_task_session- # (it was registered when the task was submitted)- # Session may be available or None if cleaned up - key is registration happened- _ = get_task_session(session_id_captured)-- # Wait for task to complete+ task = await client.call_tool("progress_tool", {}, task=True)+ await asyncio.wait_for(progress_reported.wait(), timeout=5.0)await task.wait(timeout=5.0)result = await task.result()assert result.data == "done"- async def test_context_elicit_works_in_background_task(self):- """E2E test: verify Context is properly wired in background tasks.-- This test demonstrates that:- 1. Context.task_id is set correctly in background tasks- 2. Context.is_background_task returns True- 3. Context.session_id is available-- The wiring is what enables ctx.elicit() to work in background tasks.- """- import asyncio-- from fastmcp import FastMCP- from fastmcp.client import Client- from fastmcp.server.context import Context-- mcp = FastMCP("context-wiring-test")-- # Track what happens in the background task+ async def test_context_wiring_in_background_task(self):+ """Context should be properly wired with task_id and session_id."""+ mcp = FastMCP("wiring-test")task_completed = asyncio.Event()- captured_task_id: str | None = None- captured_session_id: str | None = None- captured_is_background: bool | None = None+ captured: dict[str, object] = {}@mcp.tool(task=True)- async def verify_context_tool(ctx: Context) -> str:- """Tool that verifies Context is wired correctly for background tasks."""- nonlocal captured_task_id, captured_session_id, captured_is_background-- # Capture context properties - this is the key verification- captured_task_id = ctx.task_id- captured_session_id = ctx.session_id- captured_is_background = ctx.is_background_task-+ async def verify_wiring(ctx: Context) -> str:+ captured["task_id"] = ctx.task_id+ captured["session_id"] = ctx.session_id+ captured["is_background"] = ctx.is_background_tasktask_completed.set()- return f"task_id={ctx.task_id}, is_background={ctx.is_background_task}"+ return "ok"async with Client(mcp) as client:- # Start the background task- task = await client.call_tool("verify_context_tool", {}, task=True)- assert task is not None- assert task.task_id is not None-- # Wait for the task to complete- await asyncio.wait_for(task_completed.wait(), timeout=10.0)-- # Verify Context was properly wired in the background task- assert captured_task_id is not None, "Context.task_id should be set"- assert captured_session_id is not None, "Context.session_id should be set"- assert captured_is_background is True, (- "Context.is_background_task should be True"- )-- # Wait for task result- await task.wait(timeout=10.0)+ task = await client.call_tool("verify_wiring", {}, task=True)+ await asyncio.wait_for(task_completed.wait(), timeout=5.0)+ await task.wait(timeout=5.0)result = await task.result()- assert "is_background=True" in result.data+ assert result.data == "ok"- async def test_context_elicit_full_flow_with_mocked_redis(self):- """E2E test with mocked Redis to show complete elicitation flow.+ assert captured["task_id"] is not None+ assert captured["session_id"] is not None+ assert captured["is_background"] is True- This test demonstrates what the client sees during background task- elicitation, with a mocked Redis layer to avoid requiring real Redis.+ async def test_elicit_accept_flow(self):+ """E2E: tool elicits input, client accepts, tool receives value.Flow:- 1. Tool calls ctx.elicit() in background task- 2. Elicitation stores request in Redis, sends input_required notification- 3. Simulated client sends response via handle_task_input()- 4. Tool receives response and completes-- This is the key test that fulfills Chris Guidry's request for an- "end-to-end test showing a background task that's eliciting input"- and demonstrates "what the client-side sees when this happens."+ 1. Tool calls ctx.elicit("name?", str) β blocks waiting for input+ 2. Client polls handle_task_input(action="accept", content={"value":"Bob"})+ 3. Tool resumes with AcceptedElicitation(data="Bob")"""- import asyncio- from unittest.mock import AsyncMock, MagicMock+ mcp = FastMCP("elicit-accept-test")+ elicit_started = asyncio.Event()+ captured: dict[str, str | None] = {"task_id": None, "session_id": None}- from fastmcp.server.context import Context- from fastmcp.server.tasks.elicitation import handle_task_input+ @mcp.tool(task=True)+ async def ask_name(ctx: Context) -> str:+ captured["task_id"] = ctx.task_id+ captured["session_id"] = ctx.session_id+ elicit_started.set()- # Shared Redis storage that both elicit and handle_task_input will use- redis_storage: dict[str, bytes] = {}+ result = await ctx.elicit("What is your name?", str)+ if isinstance(result, AcceptedElicitation):+ return f"Hello, {result.data}!"+ return "No name provided"- # Create a mock Redis that uses our shared storage- class MockRedis:- async def set(- self, key: str, value: str | bytes, ex: int | None = None- ) -> None:- redis_storage[key] = value.encode() if isinstance(value, str) else value+ async with Client(mcp) as client:+ task = await client.call_tool("ask_name", {}, task=True)+ await asyncio.wait_for(elicit_started.wait(), timeout=5.0)- async def get(self, key: str) -> bytes | None:- return redis_storage.get(key)+ assert captured["task_id"] is not None+ assert captured["session_id"] is not None- async def delete(self, *keys: str) -> None:- for key in keys:- redis_storage.pop(key, None)+ # Poll until the "waiting" status is stored in Redis+ success = False+ for _ in range(40):+ success = await handle_task_input(+ task_id=captured["task_id"],+ session_id=captured["session_id"],+ action="accept",+ content={"value": "Bob"},+ fastmcp=mcp,+ )+ if success:+ break+ await asyncio.sleep(0.05)- mock_redis = MockRedis()+ assert success is True, "handle_task_input should succeed within 2s"- # Create mock context manager for redis()- class MockRedisContext:- async def __aenter__(self):- return mock_redis+ await task.wait(timeout=10.0)+ result = await task.result()+ assert result.data == "Hello, Bob!"- async def __aexit__(self, *args):- pass+ async def test_elicit_decline_flow(self):+ """E2E: tool elicits input, client declines, tool gets DeclinedElicitation."""+ mcp = FastMCP("elicit-decline-test")+ elicit_started = asyncio.Event()+ captured: dict[str, str | None] = {"task_id": None, "session_id": None}- mock_docket = MagicMock()- mock_docket.redis = lambda: MockRedisContext()- mock_docket.key = lambda k: k+ @mcp.tool(task=True)+ async def optional_input(ctx: Context) -> str:+ captured["task_id"] = ctx.task_id+ captured["session_id"] = ctx.session_id+ elicit_started.set()- mock_fastmcp = MagicMock()- mock_fastmcp._docket = mock_docket+ result = await ctx.elicit("Want to provide a name?", str)+ if isinstance(result, DeclinedElicitation):+ return "User declined"+ if isinstance(result, AcceptedElicitation):+ return f"Got: {result.data}"+ return "Cancelled"- mock_session = MagicMock()- mock_session._fastmcp_state_prefix = "test-session-123"- mock_session.send_notification = AsyncMock()+ async with Client(mcp) as client:+ task = await client.call_tool("optional_input", {}, task=True)+ await asyncio.wait_for(elicit_started.wait(), timeout=5.0)- # Create task-aware context (as would be created in background worker)- ctx = Context(- mock_fastmcp,- session=mock_session,- task_id="test-task-456",- )+ assert captured["task_id"] is not None+ assert captured["session_id"] is not None- # Verify context is properly configured for background task- assert ctx.is_background_task is True- assert ctx.task_id == "test-task-456"-- # Start elicit in a background task (simulating the Docket worker)- async def run_elicit():- return await ctx.elicit("What is your name?", str)-- elicit_task = asyncio.create_task(run_elicit())-- # Wait for elicit to store request and start polling- # The elicit_for_task function stores the request and sends notification- await asyncio.sleep(0.2)-- # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ- # CLIENT PERSPECTIVE: What does the client see?- # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ-- # 1. CLIENT RECEIVES: notifications/tasks/updated notification- mock_session.send_notification.assert_called()- notification = mock_session.send_notification.call_args[0][0]- assert notification.method == "notifications/tasks/updated"-- # 2. CLIENT INSPECTS: The notification metadata tells the client:- # - Which task needs input (taskId)- # - What status the task is in (input_required)- # - What message to display (statusMessage)- # - The schema for the expected response (elicitation.requestedSchema)- meta = notification._meta- related_task = meta["modelcontextprotocol.io/related-task"]-- assert related_task["taskId"] == "test-task-456"- assert related_task["status"] == "input_required"- assert related_task["statusMessage"] == "What is your name?"- assert "elicitation" in related_task- assert related_task["elicitation"]["message"] == "What is your name?"- assert "requestedSchema" in related_task["elicitation"]-- # 3. CLIENT RESPONDS: Send input via handle_task_input- # This is what a real client would do when it receives input_required- success = await handle_task_input(- task_id="test-task-456",- session_id="test-session-123",- action="accept",- content={"value": "Alice"},- fastmcp=mock_fastmcp,- )- assert success is True, "Client should successfully send input"-- # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ- # TOOL PERSPECTIVE: What does the tool receive?- # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ-- # Wait for elicit to receive the response and return- result = await asyncio.wait_for(elicit_task, timeout=5.0)-- # Verify the result contains what the client sent- # AcceptedElicitation has 'action' and 'data' attributes- assert result.action == "accept"- assert result.data == "Alice" # The value from content["value"]-- async def test_context_elicit_with_real_docket_memory_backend(self):- """E2E test using Docket's real memory:// backend.-- This test uses the real Docket memory backend instead of mocking Redis,- as suggested by Chris Guidry during code review. The memory:// backend- provides a fully functional in-memory Redis-like store that Docket uses- automatically when running tests.+ success = False+ for _ in range(40):+ success = await handle_task_input(+ task_id=captured["task_id"],+ session_id=captured["session_id"],+ action="decline",+ content=None,+ fastmcp=mcp,+ )+ if success:+ break+ await asyncio.sleep(0.05)- Flow:- 1. Create FastMCP server with task-enabled tool that calls ctx.elicit()- 2. Start the task via Client (which initializes Docket with memory://)- 3. Background task blocks waiting for client input- 4. Simulate client sending input via handle_task_input()- 5. Task resumes and completes with the elicited value+ assert success is True- This demonstrates the complete elicitation flow with real infrastructure.- """- import asyncio+ await task.wait(timeout=10.0)+ result = await task.result()+ assert result.data == "User declined"- from fastmcp import FastMCP- from fastmcp.client import Client- from fastmcp.server.context import Context- from fastmcp.server.tasks.elicitation import handle_task_input+ async def test_elicit_with_pydantic_model(self):+ """E2E: tool elicits structured Pydantic input, data round-trips correctly."""+ from pydantic import BaseModel- mcp = FastMCP("elicit-memory-test")+ class UserInfo(BaseModel):+ name: str+ age: int- # Track task state using mutable container (avoids nonlocal)+ mcp = FastMCP("elicit-pydantic-test")elicit_started = asyncio.Event()captured: dict[str, str | None] = {"task_id": None, "session_id": None}@mcp.tool(task=True)- async def ask_for_name(ctx: Context) -> str:- """Tool that elicits user's name via background task."""- # Capture IDs for handle_task_input call+ async def get_user_info(ctx: Context) -> str:captured["task_id"] = ctx.task_idcaptured["session_id"] = ctx.session_idelicit_started.set()- # This will block until client sends input- result = await ctx.elicit("What is your name?", str)-+ result = await ctx.elicit("Provide user info", UserInfo)if isinstance(result, AcceptedElicitation):- return f"Hello, {result.data}!"- else:- return "Elicitation was declined or cancelled"+ assert isinstance(result.data, UserInfo)+ return f"{result.data.name} is {result.data.age}"+ return "No info"async with Client(mcp) as client:- # Start the background task- task = await client.call_tool("ask_for_name", {}, task=True)- assert task is not None- assert task.task_id is not None-- # Wait for task to reach elicit() call+ task = await client.call_tool("get_user_info", {}, task=True)await asyncio.wait_for(elicit_started.wait(), timeout=5.0)- # Poll until handle_task_input succeeds- # We need to wait for elicit_for_task to store the "waiting" status in Redis- # before we can send input. Using fixed-interval polling (not exponential- # backoff) because we're waiting for state, not recovering from errors.assert captured["task_id"] is not Noneassert captured["session_id"] is not None- max_attempts = 40- poll_interval_seconds = 0.05 # 50ms - fast for tests, 2s max totalsuccess = False- for _ in range(max_attempts):+ for _ in range(40):success = await handle_task_input(task_id=captured["task_id"],session_id=captured["session_id"],action="accept",- content={"value": "Bob"},+ content={"name": "Alice", "age": 30},fastmcp=mcp,)if success:break- await asyncio.sleep(poll_interval_seconds)+ await asyncio.sleep(0.05)- assert success is True, (- f"handle_task_input should succeed within {max_attempts * poll_interval_seconds}s"- )+ assert success is True- # Wait for task to completeawait task.wait(timeout=10.0)result = await task.result()+ assert result.data == "Alice is 30"- # Verify the tool received the elicited value and returned correctly- assert result.data == "Hello, Bob!"+ async def test_handle_task_input_rejects_when_not_waiting(self):+ """handle_task_input returns False when no task is waiting for input."""+ mcp = FastMCP("reject-test")++ @mcp.tool(task=True)+ async def simple_tool() -> str:+ return "done"++ async with Client(mcp) as client:+ task = await client.call_tool("simple_tool", {}, task=True)+ await task.wait(timeout=5.0)++ # Task already completed β no elicitation waiting+ success = await handle_task_input(+ task_id=task.task_id,+ session_id="nonexistent-session",+ action="accept",+ content={"value": "too late"},+ fastmcp=mcp,+ )+ assert success is Falsediff --git a/tests/server/tasks/test_notifications.py b/tests/server/tasks/test_notifications.pynew file mode 100644index 000000000..d669a5ed6--- /dev/null+++ b/tests/server/tasks/test_notifications.py@@ -0,0 +1,104 @@+"""Tests for distributed notification queue (SEP-1686).++Integration tests verify that the notification queue works end-to-end+using Client(mcp) with the real memory:// Docket backend.+No mocking of Redis, sessions, or Docket internals.+"""++import asyncio++from fastmcp import FastMCP+from fastmcp.client import Client+from fastmcp.server.context import Context+from fastmcp.server.elicitation import AcceptedElicitation+from fastmcp.server.tasks.elicitation import handle_task_input+from fastmcp.server.tasks.notifications import (+ get_subscriber_count,+)+++class TestNotificationIntegration:+ """Integration tests for the notification queue using real Docket memory backend.++ The elicitation flow implicitly validates the full notification pipeline:+ 1. Tool calls ctx.elicit() β stores request in Redis β pushes notification+ 2. Subscriber picks up notification β sends MCP notification to client+ 3. Client calls handle_task_input() β LPUSH response β BLPOP wakes tool+ """++ async def test_notification_delivered_during_elicitation(self):+ """Full E2E: notification queue delivers elicitation notification to client."""+ mcp = FastMCP("notification-test")+ elicit_started = asyncio.Event()+ captured: dict[str, str | None] = {"task_id": None, "session_id": None}++ @mcp.tool(task=True)+ async def elicit_tool(ctx: Context) -> str:+ captured["task_id"] = ctx.task_id+ captured["session_id"] = ctx.session_id+ elicit_started.set()++ result = await ctx.elicit("Enter value", str)+ if isinstance(result, AcceptedElicitation):+ return f"got: {result.data}"+ return "no value"++ async with Client(mcp) as client:+ task = await client.call_tool("elicit_tool", {}, task=True)+ await asyncio.wait_for(elicit_started.wait(), timeout=5.0)++ # Poll until the task is waiting for input+ success = False+ for _ in range(40):+ success = await handle_task_input(+ task_id=captured["task_id"],+ session_id=captured["session_id"],+ action="accept",+ content={"value": "hello"},+ fastmcp=mcp,+ )+ if success:+ break+ await asyncio.sleep(0.05)++ assert success is True++ await task.wait(timeout=10.0)+ result = await task.result()+ assert result.data == "got: hello"++ async def test_subscriber_lifecycle(self):+ """Subscriber starts during background task and stops when client disconnects."""+ mcp = FastMCP("subscriber-test")+ tool_started = asyncio.Event()+ tool_continue = asyncio.Event()++ @mcp.tool(task=True)+ async def lifecycle_tool(ctx: Context) -> str:+ tool_started.set()+ await asyncio.wait_for(tool_continue.wait(), timeout=10.0)+ return "done"++ count_before = get_subscriber_count()++ async with Client(mcp) as client:+ task = await client.call_tool("lifecycle_tool", {}, task=True)+ await asyncio.wait_for(tool_started.wait(), timeout=5.0)++ # While a background task is running, subscriber should be active+ count_during = get_subscriber_count()+ assert count_during > count_before++ # Let the tool complete+ tool_continue.set()+ await task.wait(timeout=5.0)+ result = await task.result()+ assert result.data == "done"++ # After client disconnects, subscriber should be cleaned up+ # Allow brief time for async cleanup+ for _ in range(20):+ if get_subscriber_count() == count_before:+ break+ await asyncio.sleep(0.05)+ assert get_subscriber_count() == count_before