# sanguo_llmwiki 测试指南

## 测试结构

```
tests/
├── unit/              # 单元测试
│   ├── test_database.py    # 数据库层测试
│   └── test_services.py    # 服务层测试
└── integration/       # 集成测试
    └── test_mcp_tools.py   # MCP 工具集成测试
```

## 运行测试

### 运行所有单元测试（默认）

```bash
pytest
```

### 运行集成测试

需要设置环境变量 `RUN_INTEGRATION=1`：

```bash
RUN_INTEGRATION=1 pytest tests/integration/
```

### 运行特定测试

```bash
# 运行特定文件
pytest tests/unit/test_database.py

# 运行特定类
pytest tests/unit/test_database.py::TestDatabaseBasics

# 运行特定测试方法
pytest tests/unit/test_database.py::TestDatabaseBasics::test_upsert_and_get_page
```

### 生成覆盖率报告

```bash
pytest --cov=mcp_server --cov-report=html
```

覆盖率报告将生成在 `htmlcov/` 目录。

### 运行并显示详细输出

```bash
pytest -v --tb=long
```

## 测试标记

- `unit`: 单元测试（不需要外部依赖）
- `integration`: 集成测试（需要 `RUN_INTEGRATION=1`）
- `e2e`: 端到端测试（需要完整的 MCP 环境）
- `slow`: 慢速测试

### 按标记运行

```bash
# 只运行单元测试
pytest -m unit

# 跳过慢速测试
pytest -m "not slow"
```

## 环境变量

| 变量 | 说明 | 默认值 |
|-----|------|-------|
| `RUN_INTEGRATION` | 启用集成测试 | 未设置 |
| `WIKI_VAULT_PATH` | Wiki vault 路径 | `/Volumes/KnowledgeBase/wiki-vault` |
| `WIKI_INDEX_PATH` | 索引文件路径 | `~/.sanguo-llmwiki/index.db` |

## 编写新测试

1. 单元测试放在 `tests/unit/`
2. 集成测试放在 `tests/integration/`
3. 使用适当的 pytest 标记
4. 测试文件名以 `test_` 开头
5. 测试类以 `Test` 开头
6. 测试方法以 `test_` 开头

### 单元测试模板

```python
"""测试模块描述"""

import pytest
from mcp_server.module import ClassToTest

@pytest.fixture
def setup():
    """测试fixture"""
    obj = ClassToTest()
    yield obj
    # 清理（如果需要）

class TestClassToTest:
    """类测试"""

    @pytest.mark.asyncio
    async def test_method(self, setup):
        """测试方法"""
        result = await setup.method()
        assert result == expected
```

### 集成测试模板

```python
"""集成测试描述"""

import pytest

pytestmark = pytest.mark.skipif(
    not os.environ.get("RUN_INTEGRATION"),
    reason="需要 RUN_INTEGRATION=1"
)

@pytest.mark.asyncio
async def test_integration_flow():
    """测试集成流程"""
    # 测试代码
    assert True
```