refactor: Reorganize async tests into tests/asyncio/ directory

Moved all async-specific tests into tests/asyncio/ following CPython's
organization pattern. Added comprehensive README.md with testing guidelines,
fixture documentation, and best practices.

Structure:
- test_basic.py (was test_async.py) - Basic async functionality
- test_acmd.py (was test_async_acmd.py) - Pattern A tests (8 tests)
- test_tmux_cmd.py (was test_async_tmux_cmd.py) - Pattern B tests (9 tests)
- test_hybrid.py (was test_async_hybrid.py) - Both patterns tests (7 tests)
- test_docstring_examples.py - Docstring verification tests (11 tests)
- README.md - Comprehensive testing guide with examples
- __init__.py - Package marker

Benefits:
- Clear separation of async tests
- Follows CPython's organizational patterns
- Comprehensive documentation for contributors
- Easy to run all async tests: pytest tests/asyncio/

Verified with: pytest tests/asyncio/ -v
Result: 37 passed in 1.20s (36 tests + 1 README doctest)

Author: tony

tests/asyncio/README.md

@@ -0,0 +1,175 @@
+# Async Tests for libtmux
+
+This directory contains all async-specific tests for libtmux's async support.
+
+## Structure
+
+```
+tests/asyncio/
+├── README.md                    # This file
+├── test_basic.py                # Basic async functionality tests
+├── test_acmd.py                 # Pattern A (.acmd() methods) tests
+├── test_tmux_cmd.py             # Pattern B (tmux_cmd_async) tests
+├── test_hybrid.py               # Tests for both patterns working together
+└── test_docstring_examples.py  # Verification tests for docstring examples
+```
+
+## Test Organization
+
+### test_basic.py
+Basic async functionality tests:
+- Async command execution
+- Event loop integration
+- Basic async/await patterns
+
+### test_acmd.py (Pattern A)
+Tests for `.acmd()` methods on Server/Session/Window/Pane objects:
+- `server.acmd()` execution
+- Object-oriented async operations
+- Gradual migration from sync to async patterns
+
+### test_tmux_cmd.py (Pattern B)
+Tests for direct `tmux_cmd_async()` execution:
+- Direct async command execution
+- Socket isolation with `-L` flag
+- Async-first architecture patterns
+
+### test_hybrid.py
+Tests for using both patterns together:
+- Pattern A and Pattern B in same codebase
+- Concurrent execution across patterns
+- Integration scenarios
+
+### test_docstring_examples.py
+Verification tests for all docstring examples:
+- Ensures all code examples in docstrings actually work
+- Tests examples from src/libtmux/common_async.py
+- Tests examples from docs/quickstart_async.md
+- Tests examples from docs/topics/async_programming.md
+
+## Running Tests
+
+Run all async tests:
+```bash
+pytest tests/asyncio/ -v
+```
+
+Run specific test file:
+```bash
+pytest tests/asyncio/test_acmd.py -v
+```
+
+Run with coverage:
+```bash
+pytest tests/asyncio/ --cov=libtmux.common_async --cov-report=term-missing
+```
+
+## Test Requirements
+
+All async tests must:
+
+1. **Use pytest-asyncio**: Mark test functions with `@pytest.mark.asyncio`
+   ```python
+   @pytest.mark.asyncio
+   async def test_something(async_server):
+       result = await async_server.acmd('list-sessions')
+       assert result is not None
+   ```
+
+2. **Use TestServer fixtures**: Always use `async_server` or `async_test_server` fixtures
+   - `async_server`: Pre-configured server with unique socket
+   - `async_test_server`: Factory for creating multiple servers
+
+3. **Ensure isolation**: All tests must use unique sockets to avoid affecting:
+   - Developer's active tmux sessions
+   - Other concurrent tests
+   - System tmux server
+
+4. **Include cleanup**: All resources should be cleaned up
+   - Sessions, windows, panes created during tests
+   - Use fixture cleanup or explicit cleanup in tests
+
+5. **Assert behavior, not values**: Test boolean conditions, types, lengths
+   ```python
+   # Good - Tests behavior
+   assert isinstance(result.stdout, list)
+   assert len(result.stdout) > 0
+   assert result.returncode == 0
+
+   # Bad - Tests exact values
+   assert result.stdout == ['session1']  # Fragile!
+   ```
+
+## Fixtures
+
+Available from `conftest.py`:
+
+- `async_server`: Async wrapper for server fixture
+  - Provides Server instance with unique socket
+  - Automatic cleanup via finalizer
+  - Socket name: `libtmux_test{random}`
+
+- `async_test_server`: Async wrapper for TestServer factory
+  - Creates multiple unique servers
+  - Each call returns new isolated server
+  - All servers cleaned up automatically
+
+## CPython-Inspired Patterns
+
+Following CPython's asyncio test patterns:
+
+1. **Use `asyncio.run()` in doctests**:
+   ```python
+   >>> async def example():
+   ...     result = await tmux_cmd_async('list-sessions')
+   ...     return isinstance(result.stdout, list)
+   >>> asyncio.run(example())
+   True
+   ```
+
+2. **Test concurrent operations with `asyncio.gather()`**:
+   ```python
+   results = await asyncio.gather(
+       tmux_cmd_async('cmd1'),
+       tmux_cmd_async('cmd2'),
+       tmux_cmd_async('cmd3'),
+   )
+   ```
+
+3. **Use `return_exceptions=True` for resilience**:
+   ```python
+   results = await asyncio.gather(
+       tmux_cmd_async('cmd1'),
+       tmux_cmd_async('cmd2'),
+       return_exceptions=True,
+   )
+   ```
+
+## Coverage Goals
+
+Current coverage: ~25 async tests
+
+Target coverage:
+- ✅ Core async functionality (tmux_cmd_async, get_version)
+- ✅ Pattern A (.acmd methods)
+- ✅ Pattern B (tmux_cmd_async)
+- ✅ Concurrent operations
+- ✅ Error handling
+- ⏳ AsyncEnvironmentMixin methods (pending)
+- ⏳ Version checking functions (pending)
+- ⏳ Edge cases and error conditions (pending)
+
+## Best Practices
+
+1. **Keep tests fast**: Use minimal tmux operations
+2. **Test behavior, not implementation**: Focus on observable outcomes
+3. **Use descriptive test names**: `test_pattern_a_creates_session_concurrently`
+4. **Document test purpose**: Add docstrings explaining what's being tested
+5. **Follow pytest conventions**: Use `test_*.py` naming, `Test*` classes
+
+## See Also
+
+- [pytest-asyncio documentation](https://pytest-asyncio.readthedocs.io/)
+- [CPython asyncio tests](https://github.com/python/cpython/tree/main/Lib/test/test_asyncio)
+- [libtmux async guide](../../docs/topics/async_programming.md)
+- [Async quickstart](../../docs/quickstart_async.md)

tests/asyncio/__init__.py

@@ -0,0 +1,5 @@
+"""Async tests for libtmux.
+
+This package contains all async-specific tests for libtmux's async support,
+organized following CPython's test structure patterns.
+"""