# Testing Guide
This document provides comprehensive guidance on testing the Session Management MCP server, including strategy, current status, and quality standards.
## Quick Reference
```bash
# Run full test suite with coverage
pytest --cov=session_buddy --cov-report=term-missing
# Quick smoke tests (exclude slow tests)
pytest -m "not slow"
# Run specific test categories
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
pytest -m performance # Performance tests only
# Coverage with fail threshold
pytest --cov=session_buddy --cov-fail-under=85
```
**Coverage Targets:**
- Overall: 85%+
- Critical components (ReflectionDatabase, SessionManager): 95%+
- New code: 100% required
______________________________________________________________________
## Current Status
### Coverage Metrics
- **Current Coverage**: ~14.7% (improving from initial 11.66%)
- **Target Coverage**: 85% overall, 95% for critical components
- **Test Pass Rate**: 90%+ for implemented suites
### Well-Covered Areas (✅)
- **Reflection Tools** (55%) - Database operations, storage, search
- **Memory Tools** (80%) - MCP tool interfaces, search features
- **Worktree Manager** (74%) - Operations, session preservation, git integration
- **SessionLifecycleManager** - Quality assessment, checkpoints, status reporting
### Areas Needing Attention (⚠️)
**Critical Components with No Coverage:**
- InterruptionManager (0% - 353 lines)
- NaturalScheduler (0% - 338 lines)
- TeamKnowledge (0% - 284 lines)
**Low-Coverage Core Modules:**
- AdvancedSearch (16.88%) - 16/24 tests passing, needs filtering/sorting implementation
- MultiProjectCoordinator (21.43%) - Cross-project functionality
- TokenOptimizer (13.20%) - Token management and chunking
- SessionManager (62.07%) - Core session operations
### Recent Improvements
**Infrastructure Fixes Completed:**
- ✅ Fixed database initialization issues in tests
- ✅ Resolved DuckDB connection and syntax problems
- ✅ Updated SessionPermissionsManager constructor handling
- ✅ Fixed import and fixture errors across test suites
- ✅ Implemented proper logging configuration for tests
**New Test Suites:**
- ✅ Reflection Tools Tests - 83 test cases (21/24 passing)
- ✅ Memory Tools Tests - 30 test cases (comprehensive coverage)
- ✅ Worktree Manager Tests - 32 test cases (edge cases included)
- ✅ SessionLifecycleManager Tests - Complete workflow coverage
______________________________________________________________________
## Testing Strategy
### Test Categories
#### 1. Unit Tests (`tests/unit/`)
**Focus:** Isolated functionality testing
- Test individual functions and methods
- Mock external dependencies
- 100% coverage of public API
- Fast execution (< 1 second per test)
**Example:**
```text
def test_reflection_storage():
"""Test basic reflection storage."""
async with ReflectionDatabase() as db:
reflection_id = await db.store_reflection("Test content")
assert reflection_id is not None
```
#### 2. Integration Tests (`tests/integration/`)
**Focus:** Component interaction and workflows
- Test cross-component functionality
- Verify MCP tool registration and execution
- Test database integration with real operations
- Critical paths and user journeys
**Example:**
```python
async def test_session_lifecycle_integration():
"""Test complete session workflow."""
# Start → Work → Checkpoint → End
result = await start_session()
await create_checkpoint()
summary = await end_session()
assert summary["success"]
```
#### 3. Functional Tests (`tests/functional/`)
**Focus:** End-to-end functionality
- User-facing features from user perspective
- Complete feature workflows
- Real-world usage scenarios
#### 4. Performance Tests (`tests/performance/`)
**Focus:** Scalability and resource usage
- Response time benchmarks
- Memory usage monitoring
- High-load scenario testing
- Tools: pytest-benchmark
#### 5. Security Tests (`tests/security/`)
**Focus:** Security aspects
- Input validation and sanitization
- Access control verification
- Injection attack protection
- Tools: pytest, bandit
#### 6. Property-Based Tests
**Focus:** Robustness with random inputs
- Edge cases and boundary conditions
- Input validation stress testing
- Concurrency testing
- Tools: Hypothesis
### Test Structure Guidelines
**File Organization:**
```
tests/
├── unit/ # Isolated component tests
├── integration/ # Cross-component tests
├── functional/ # End-to-end feature tests
├── performance/ # Benchmark tests
├── security/ # Security-focused tests
├── conftest.py # Shared fixtures and configuration
└── helpers.py # Test utilities and factories
```
**Naming Conventions:**
- Test files: `test_*.py`
- Test classes: `Test[ComponentName][TestType]`
- Test methods: `test_[action]_[expected_result]`
**Test Data Management:**
- Use temporary directories for file operations
- Mock external dependencies (APIs, file systems)
- Clean up resources in teardown
- Use pytest fixtures for reusable test setup
______________________________________________________________________
## Implementation Roadmap
### Phase 1: Critical Missing Tests (Weeks 1-2)
**Priority: HIGH**
1. **Complete AdvancedSearch Tests** ✅ In Progress
- Fix remaining 8 failing tests
- Implement content type filtering
- Add sorting functionality
- Implement timeframe-based filtering
1. **InterruptionManager Testing** 📅 Not Started
- Create `tests/unit/test_interruption_manager.py`
- Test context preservation and recovery
- Test file system monitoring
- Test activity pattern detection
1. **NaturalScheduler Testing** 📅 Not Started
- Create `tests/unit/test_natural_scheduler.py`
- Test time expression parsing
- Test reminder creation and execution
- Test background service operations
### Phase 2: Core Feature Expansion (Weeks 2-3)
**Priority: MEDIUM**
1. **MultiProjectCoordinator Testing**
- Test project group management
- Test dependency tracking
- Test cross-project search
- Test session linking
1. **TokenOptimizer Testing**
- Test token counting accuracy
- Test optimization strategies
- Test caching mechanisms
- Test chunking for large content
1. **Parameter Validation Testing**
- Test all validation models
- Test edge cases and invalid inputs
- Test data normalization
### Phase 3: Integration & Advanced Testing (Weeks 3-4)
**Priority: MEDIUM-LOW**
1. **Integration Test Suites**
- Memory and search integration
- Worktree management workflows
- Session lifecycle end-to-end
1. **Performance Baselines**
- Reflection database operations
- Search performance with large datasets
- Worktree operations
### Phase 4: Quality & Security (Weeks 4-5)
**Priority: LOW (Future Work)**
1. **Security Testing**
- Input validation comprehensive testing
- Access control verification
- Injection attack scenarios
1. **Property-Based Testing**
- Use Hypothesis for generative testing
- Test concurrency edge cases
- Boundary condition exploration
______________________________________________________________________
## Quality Standards
### Code Coverage Requirements
| Component Type | Target Coverage | Status |
|---|---|---|
| Overall Project | 85%+ | 14.7% ⚠️ |
| Critical Modules | 95%+ | Varies |
| Reflection Tools | 95%+ | 55% 🔄 |
| Memory Tools | 95%+ | 80% ✅ |
| Worktree Manager | 95%+ | 74% 🔄 |
| New Code | 100% | Required |
### Test Quality Metrics
**Performance:**
- Unit tests: < 1 second execution time
- Integration tests: < 5 seconds execution time
- Full suite: < 5 minutes total
**Reliability:**
- Test pass rate: 100%
- Flaky test rate: < 10%
- Test determinism: Required
**Maintainability:**
- Clear, descriptive test names
- Comprehensive docstrings
- Minimal test duplication
- Well-documented fixtures
### Documentation Standards
All test files must include:
- Module-level docstring explaining purpose
- Complex scenario documentation
- Fixture documentation with examples
- Clear assertion messages
### Continuous Integration
**Requirements:**
- All tests run in CI pipeline
- Parallel test execution enabled
- Coverage reports generated automatically
- Performance regression detection
______________________________________________________________________
## Success Metrics
### Short-term Goals (Next 2-3 weeks)
- ✅ Fix all AdvancedSearch test failures
- ⏳ Implement missing functionality (filtering, sorting)
- ⏳ Reach 25%+ overall coverage
- ⏳ Zero failing tests in CI
### Medium-term Goals (Next 1-2 months)
- 📅 Complete all critical component tests
- 📅 Implement integration test suites
- 📅 Reach 50%+ overall coverage
- 📅 Establish performance baselines
### Long-term Goals (Next quarter)
- 📅 Achieve 85%+ overall coverage
- 📅 Complete security testing
- 📅 Full CI/CD integration
- 📅 Property-based test coverage
______________________________________________________________________
## Common Testing Patterns
### Async Test Pattern
```text
import pytest
@pytest.mark.asyncio
async def test_async_operation():
"""Test asynchronous database operation."""
async with ReflectionDatabase() as db:
result = await db.some_async_operation()
assert result is not None
```
### Fixture Usage
```text
@pytest.fixture
async def temp_database():
"""Provide temporary database for testing."""
db_path = tempfile.mktemp(suffix=".duckdb")
yield db_path
# Cleanup
if os.path.exists(db_path):
os.remove(db_path)
```
### Mocking External Dependencies
```text
from unittest.mock import patch, MagicMock
def test_with_mocked_git():
"""Test git operations with mocked subprocess."""
with patch("subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stdout="mocked output")
result = perform_git_operation()
assert result == "expected"
```
______________________________________________________________________
## Troubleshooting
### Common Test Issues
**Issue: Tests failing with DuckDB connection errors**
```text
# Solution: Use temporary database in fixtures
@pytest.fixture
async def db():
db_path = tempfile.mktemp(suffix=".duckdb")
async with ReflectionDatabase(db_path=db_path) as database:
yield database
```
**Issue: Async tests not running**
```python
# Solution: Add pytest-asyncio marker
@pytest.mark.asyncio
async def test_function(): ...
```
**Issue: Flaky tests due to timing**
```python
# Solution: Use proper async/await patterns
await asyncio.sleep(0.1) # Give time for async operations
```
### Running Specific Tests
```bash
# Single test file
pytest tests/unit/test_reflection_tools.py -v
# Single test function
pytest tests/unit/test_reflection_tools.py::test_store_reflection -v
# Tests matching pattern
pytest -k "reflection" -v
# With debugging
pytest tests/unit/test_reflection_tools.py -v -s --pdb
```
______________________________________________________________________
## Resources
**Documentation:**
- [pytest documentation](https://docs.pytest.org/)
- [pytest-asyncio](https://pytest-asyncio.readthedocs.io/)
- [Hypothesis](https://hypothesis.readthedocs.io/)
**Project Files:**
- Test configuration: `pyproject.toml` (tool.pytest.ini_options)
- Shared fixtures: `tests/conftest.py`
- Test utilities: `tests/helpers.py`
**Coverage Reports:**
```bash
# Generate HTML coverage report
pytest --cov=session_buddy --cov-report=html
# Open coverage report
open htmlcov/index.html
```
______________________________________________________________________
**Last Updated:** 2025-01-04
**Current Coverage:** 14.7%
**Next Milestone:** 25% coverage with AdvancedSearch completion
