tests(feat[async_doctest]): Add comprehensive async doctest tests

why: Verify async doctest functionality works correctly
what:
- Test basic top-level await with asyncio.sleep
- Test async functions returning values
- Test mixed sync/async examples in same block
- Test state persistence across examples
- Test async context managers (async with)
- Test async iteration (async for)
- Test async comprehensions
- Test expected exceptions in async code
- Test Markdown file support
- Test AsyncDocTestRunner directly

Author: tony

tests/test_async_doctest.py

@@ -0,0 +1,255 @@
+"""Tests for async doctest support.
+
+These tests verify that top-level await works in doctests without requiring
+asyncio.run() boilerplate.
+"""
+
+from __future__ import annotations
+
+import textwrap
+import typing as t
+
+from doctest_docutils import (
+    AsyncDocTestRunner,
+    DocutilsDocTestFinder,
+    run_doctest_docutils,
+)
+
+if t.TYPE_CHECKING:
+    import pathlib
+
+
+class TestAsyncDoctestBasic:
+    """Basic async doctest functionality tests."""
+
+    def test_top_level_await_sleep(self, tmp_path: pathlib.Path) -> None:
+        """Test basic top-level await with asyncio.sleep."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Test async doctest
+            ==================
+
+            >>> import asyncio
+            >>> await asyncio.sleep(0)
+            >>> 1 + 1
+            2
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+        assert result.attempted >= 2
+
+    def test_top_level_await_with_result(self, tmp_path: pathlib.Path) -> None:
+        """Test top-level await that returns a value."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Async with result
+            =================
+
+            >>> import asyncio
+            >>> async def get_value():
+            ...     await asyncio.sleep(0)
+            ...     return 42
+            >>> await get_value()
+            42
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+    def test_mixed_sync_async(self, tmp_path: pathlib.Path) -> None:
+        """Test mixing sync and async examples in same block."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Mixed sync and async
+            ====================
+
+            >>> x = 1
+            >>> import asyncio
+            >>> await asyncio.sleep(0)
+            >>> x + 1
+            2
+            >>> y = await asyncio.sleep(0) or 10
+            >>> y
+            10
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+    def test_state_persistence_across_examples(self, tmp_path: pathlib.Path) -> None:
+        """Test that state persists across async examples in same block."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            State persistence
+            =================
+
+            >>> import asyncio
+            >>> async def set_value():
+            ...     global shared_value
+            ...     await asyncio.sleep(0)
+            ...     shared_value = 'hello'
+            >>> await set_value()
+            >>> shared_value
+            'hello'
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+
+class TestAsyncDoctestAdvanced:
+    """Advanced async doctest scenarios."""
+
+    def test_async_context_manager(self, tmp_path: pathlib.Path) -> None:
+        """Test async with statement."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Async context manager
+            =====================
+
+            >>> import asyncio
+            >>> class AsyncCM:
+            ...     async def __aenter__(self):
+            ...         await asyncio.sleep(0)
+            ...         return 'entered'
+            ...     async def __aexit__(self, *args):
+            ...         await asyncio.sleep(0)
+            >>> async with AsyncCM() as value:
+            ...     print(value)
+            entered
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+    def test_async_for(self, tmp_path: pathlib.Path) -> None:
+        """Test async for statement."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Async iteration
+            ===============
+
+            >>> import asyncio
+            >>> async def async_range(n):
+            ...     for i in range(n):
+            ...         await asyncio.sleep(0)
+            ...         yield i
+            >>> result = []
+            >>> async for x in async_range(3):
+            ...     result.append(x)
+            >>> result
+            [0, 1, 2]
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+    def test_async_comprehension(self, tmp_path: pathlib.Path) -> None:
+        """Test async list comprehension."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Async comprehension
+            ===================
+
+            >>> import asyncio
+            >>> async def async_range(n):
+            ...     for i in range(n):
+            ...         await asyncio.sleep(0)
+            ...         yield i
+            >>> [x async for x in async_range(3)]
+            [0, 1, 2]
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+
+class TestAsyncDoctestExceptions:
+    """Test exception handling in async doctests."""
+
+    def test_expected_async_exception(self, tmp_path: pathlib.Path) -> None:
+        """Test that expected exceptions from async code are handled."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Expected exception
+            ==================
+
+            >>> import asyncio
+            >>> async def raise_error():
+            ...     await asyncio.sleep(0)
+            ...     raise ValueError('test error')
+            >>> await raise_error()
+            Traceback (most recent call last):
+                ...
+            ValueError: test error
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+
+class TestAsyncDoctestMarkdown:
+    """Test async doctests in Markdown files."""
+
+    def test_markdown_async_doctest(self, tmp_path: pathlib.Path) -> None:
+        """Test async doctest in Markdown file."""
+        doc = tmp_path / "test.md"
+        doc.write_text(
+            textwrap.dedent("""
+            # Async Doctest in Markdown
+
+            ```python
+            >>> import asyncio
+            >>> await asyncio.sleep(0)
+            >>> 1 + 1
+            2
+            ```
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+
+
+class TestAsyncDocTestRunner:
+    """Test AsyncDocTestRunner directly."""
+
+    def test_runner_creates_event_loop(self, tmp_path: pathlib.Path) -> None:
+        """Test that runner properly creates and manages event loop."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(">>> import asyncio\n>>> await asyncio.sleep(0)\n")
+
+        finder = DocutilsDocTestFinder()
+        runner = AsyncDocTestRunner(verbose=True)
+
+        text = doc.read_text()
+        for test in finder.find(text, str(doc)):
+            result = runner.run(test)
+            assert result.failed == 0
+
+    def test_sync_code_still_works(self, tmp_path: pathlib.Path) -> None:
+        """Test that sync code works normally with AsyncDocTestRunner."""
+        doc = tmp_path / "test.rst"
+        doc.write_text(
+            textwrap.dedent("""
+            Sync code
+            =========
+
+            >>> 1 + 1
+            2
+            >>> x = 'hello'
+            >>> x.upper()
+            'HELLO'
+            """),
+        )
+        result = run_doctest_docutils(str(doc), module_relative=False, verbose=True)
+        assert result.failed == 0
+        assert result.attempted >= 2