better web tests

pyproject.toml

@@ -32,15 +32,19 @@ test = [
     "pytest>=9.1.1",
     "pytest-asyncio>=1.4.0",
     "pytest-cov>=7.1.0",
+    "pytest-env>=1.1.5",
 ]
 
 [tool.pytest.ini_options]
 addopts = ["--strict-markers"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 markers = [
     "unit: fast deterministic tests with no external dependencies",
     "integration: framework or component integration tests",
     "smoke: thin critical-path checks",
 ]
+env = ["PERSONAL_MCP_TEST_HTTP_URL=https://mcp.john-stream.com/mcp"]
 
 [tool.ty.src]
 include = ["src", "tests"]

tests/web/conftest.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 
 import pytest
 import pytest_asyncio
@@ -31,36 +32,28 @@ def mcp_endpoint_url() -> str:
     return os.getenv("PERSONAL_MCP_TEST_HTTP_URL", "")
 
 
-@pytest_asyncio.fixture
-async def mcp_http_client() -> AsyncIterator[AsyncClient]:
-    """Provides a reusable async HTTP client for MCP SDK transports."""
-    async with AsyncClient(timeout=10.0) as http_client:
-        yield http_client
+@pytest.fixture
+def mcp_session_factory(mcp_endpoint_url: str):
+    """Provides a context manager factory for MCP SDK sessions.
 
-
-@pytest_asyncio.fixture
-async def mcp_session_uninitialized(
-    mcp_endpoint_url: str,
-    mcp_http_client: AsyncClient,
-) -> AsyncIterator[ClientSession]:
-    """Provides a connected MCP SDK session before initialize is called."""
+    Keeping stream/client/session enter and exit in the test task avoids
+    cross-task cancel scope teardown errors from async generator fixtures.
+    """
     if not mcp_endpoint_url:
         pytest.skip("Set PERSONAL_MCP_TEST_HTTP_URL to run SDK-backed MCP endpoint tests.")
 
-    async with (
-        streamable_http_client(
-            mcp_endpoint_url,
-            http_client=mcp_http_client,
-        ) as (read_stream, write_stream, _),
-        ClientSession(read_stream, write_stream) as session,
-    ):
-        yield session
+    @asynccontextmanager
+    async def create_session(*, initialize: bool = True) -> AsyncIterator[ClientSession]:
+        async with (
+            AsyncClient(timeout=10.0) as http_client,
+            streamable_http_client(
+                mcp_endpoint_url,
+                http_client=http_client,
+            ) as (read_stream, write_stream, _),
+            ClientSession(read_stream, write_stream) as session,
+        ):
+            if initialize:
+                await session.initialize()
+            yield session
 
-
-@pytest_asyncio.fixture
-async def mcp_session(
-    mcp_session_uninitialized: ClientSession,
-) -> AsyncIterator[ClientSession]:
-    """Provides an initialized MCP SDK session ready for endpoint calls."""
-    await mcp_session_uninitialized.initialize()
-    yield mcp_session_uninitialized
+    return create_session

tests/web/test_endpoint_connections.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import pytest
 from httpx import AsyncClient
-from mcp import ClientSession
 
 pytestmark = pytest.mark.smoke
 
@@ -39,7 +38,7 @@ class TestMcpHttpEndpoints:
         async def test_rejects_get_stream_without_support(
             self,
             client: AsyncClient,
-            mcp_session: ClientSession,
+            mcp_session_factory,
         ) -> None:
             """Ensures GET /mcp returns method not allowed for current transport mode."""
             response = await client.get(
@@ -47,18 +46,20 @@ class TestMcpHttpEndpoints:
                 headers={"Accept": "text/event-stream"},
             )
 
-            # Keep the SDK-backed session in use for this route smoke lane.
-            await mcp_session.list_tools()
+            async with mcp_session_factory() as mcp_session:
+                # Keep the SDK-backed session in use for this route smoke lane.
+                await mcp_session.list_tools()
 
             assert response.status_code == 405
 
         @pytest.mark.asyncio
         async def test_accepts_initialize_jsonrpc_request(
             self,
-            mcp_session_uninitialized: ClientSession,
+            mcp_session_factory,
         ) -> None:
             """Ensures POST /mcp accepts an initialize JSON-RPC request."""
-            initialize_result = await mcp_session_uninitialized.initialize()
+            async with mcp_session_factory(initialize=False) as mcp_session_uninitialized:
+                initialize_result = await mcp_session_uninitialized.initialize()
 
             assert initialize_result.protocolVersion
             assert initialize_result.serverInfo.name

tests/web/test_mcp_prompts.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.smoke
+
+
+class TestMcpPromptSurface:
+    """Covers smoke-level MCP prompt discovery and retrieval paths."""
+
+    class TestPromptDiscovery:
+        """Covers MCP prompts/list behavior using native prompt objects."""
+
+        @pytest.mark.asyncio
+        async def test_lists_prompt_objects(self, mcp_session_factory) -> None:
+            """Ensures prompts/list returns native prompt objects with stable names."""
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.list_prompts()
+
+            assert result.prompts
+            assert all(prompt.name for prompt in result.prompts)
+
+    class TestPromptResolution:
+        """Covers MCP prompts/get behavior using native request and response objects."""
+
+        @pytest.mark.asyncio
+        async def test_gets_prompt_as_native_object(self, mcp_session_factory) -> None:
+            """Ensures prompts/get resolves a listed prompt into structured message objects."""
+            async with mcp_session_factory() as mcp_session:
+                listed_prompts = await mcp_session.list_prompts()
+                prompt_name = listed_prompts.prompts[0].name
+
+                resolved_prompt = await mcp_session.get_prompt(name=prompt_name)
+
+            assert resolved_prompt.messages
+            assert all(message.content for message in resolved_prompt.messages)

tests/web/test_mcp_skills.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import pytest
-from mcp import ClientSession
 
 pytestmark = pytest.mark.smoke
 
@@ -48,25 +47,27 @@ class TestMcpCatalogSurface:
         @pytest.mark.asyncio
         async def test_lists_core_catalog_tools(
             self,
-            mcp_session: ClientSession,
+            mcp_session_factory,
             tool_name: str,
         ) -> None:
             """Ensures tools/list exposes each required core catalog tool name."""
-            result = await mcp_session.list_tools()
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.list_tools()
             tool_names = {tool.name for tool in result.tools}
 
             assert tool_name in tool_names
 
         @pytest.mark.asyncio
-        async def test_calls_search_patterns_tool(self, mcp_session: ClientSession) -> None:
+        async def test_calls_search_patterns_tool(self, mcp_session_factory) -> None:
             """Ensures tools/call succeeds for search_patterns with basic args."""
-            result = await mcp_session.call_tool(
-                "search_patterns",
-                {
-                    "query": "pytest",
-                    "limit": 5,
-                },
-            )
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.call_tool(
+                    "search_patterns",
+                    {
+                        "query": "pytest",
+                        "limit": 5,
+                    },
+                )
 
             assert result.isError is False
             assert result.content
@@ -78,19 +79,21 @@ class TestMcpCatalogSurface:
         @pytest.mark.asyncio
         async def test_lists_catalog_resources(
             self,
-            mcp_session: ClientSession,
+            mcp_session_factory,
             resource_uri: str,
         ) -> None:
             """Ensures resources/list exposes each required catalog resource URI."""
-            result = await mcp_session.list_resources()
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.list_resources()
             resource_uris = {str(resource.uri) for resource in result.resources}
 
             assert resource_uri in resource_uris
 
         @pytest.mark.asyncio
-        async def test_lists_resource_templates(self, mcp_session: ClientSession) -> None:
+        async def test_lists_resource_templates(self, mcp_session_factory) -> None:
             """Ensures resources/templates/list includes skills and prompt templates."""
-            result = await mcp_session.list_resource_templates()
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.list_resource_templates()
             template_uris = {template.uriTemplate for template in result.resourceTemplates}
 
             assert "resource://skills/{skill_id}/document" in template_uris
@@ -100,8 +103,9 @@ class TestMcpCatalogSurface:
         """Covers MCP prompt discovery surface."""
 
         @pytest.mark.asyncio
-        async def test_lists_registered_prompts(self, mcp_session: ClientSession) -> None:
+        async def test_lists_registered_prompts(self, mcp_session_factory) -> None:
             """Ensures prompts/list returns at least one registered prompt."""
-            result = await mcp_session.list_prompts()
+            async with mcp_session_factory() as mcp_session:
+                result = await mcp_session.list_prompts()
 
             assert result.prompts

uv.lock

@@ -1131,6 +1131,7 @@ test = [
     { name = "pytest" },
     { name = "pytest-asyncio" },
     { name = "pytest-cov" },
+    { name = "pytest-env" },
 ]
 
 [package.metadata]
@@ -1154,6 +1155,7 @@ test = [
     { name = "pytest", specifier = ">=9.1.1" },
     { name = "pytest-asyncio", specifier = ">=1.4.0" },
     { name = "pytest-cov", specifier = ">=7.1.0" },
+    { name = "pytest-env", specifier = ">=1.1.5" },
 ]
 
 [[package]]
@@ -1433,6 +1435,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" },
 ]
 
+[[package]]
+name = "pytest-env"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+    { name = "python-dotenv" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ff/69/4db1c30625af0621df8dbe73797b38b6d1b04e15d021dd5d26a6d297f78c/pytest_env-1.6.0.tar.gz", hash = "sha256:ac02d6fba16af54d61e311dd70a3c61024a4e966881ea844affc3c8f0bf207d3", size = 16163, upload-time = "2026-03-12T22:39:43.78Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/16/ad52f56b96d851a2bcfdc1e754c3531341885bd7177a128c13ff2ca72ab4/pytest_env-1.6.0-py3-none-any.whl", hash = "sha256:1e7f8a62215e5885835daaed694de8657c908505b964ec8097a7ce77b403d9a3", size = 10400, upload-time = "2026-03-12T22:39:41.887Z" },
+]
+
 [[package]]
 name = "python-discovery"
 version = "1.4.2"

zensical.toml

@@ -58,6 +58,7 @@ nav = [
     { "Copilot" = "copilot.md" },
     { "Usage" = "usage.md" },
     { "Future Work" = "future_work.md" },
+    { "Testing" = "testing.md" },
     { "Security" = "securing.md" },
   ] },
   { "Skills" = [