# 测试使用指南
本项目已从单一测试文件重构为模块化的 pytest 测试结构。
## 测试结构
```
tests/
├── conftest.py # pytest fixtures 和共享配置
├── bitable/
│ ├── test_table.py # 数据表操作测试 (3个测试)
│ └── test_record.py # 记录 CRUD 测试 (8个测试)
└── integration/
└── test_bitable_workflow.py # 完整工作流集成测试 (1个测试)
todoTestList.md # 详细测试清单文档
```
**总计**: 12个测试用例（100% 通过）
**注意**: 应用级测试（创建/复制应用）已移除，使用 `FEISHU_DEFAULT_APP_TOKEN` 指定的应用进行测试。
---
## 快速开始
### 1. 安装依赖
```bash
uv sync --all-extras
```
### 2. 配置环境变量
复制 `.env.example` 到 `.env` 并配置：
```bash
cp .env.example .env
```
编辑 `.env` 文件：
```bash
# 飞书应用凭据
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
# 默认测试用多维表格app_token（必需）
# 在飞书中打开你的多维表格，从URL中复制 app_token
FEISHU_DEFAULT_APP_TOKEN=your_app_token_here
```
### 3. 运行测试
```bash
# 运行数据表和记录测试（推荐）
PYTHONPATH=src uv run pytest tests/bitable/test_table.py tests/bitable/test_record.py -v
# 运行所有测试（包括应用测试）
PYTHONPATH=src uv run pytest tests/ -v
# 运行特定测试模块
PYTHONPATH=src uv run pytest tests/bitable/test_table.py -v
```
---
## Pytest Fixtures 依赖关系
测试使用 pytest fixtures 管理数据依赖：
```
test_config (配置)
↓
default_app_token (默认应用 - 从环境变量读取)
↓
test_table_id (数据表 - session级别，所有测试共享)
↓
test_record_id (单条记录 - function级别)
test_record_ids (批量记录 - function级别)
```
pytest 会自动解析依赖关系，按需创建 fixtures。
---
## 测试数据管理
使用环境变量 `FEISHU_DEFAULT_APP_TOKEN` 指定的多维表格进行测试：
- 不会创建新的应用
- 数据表和记录测试在指定的应用中进行
- 测试数据会保留在飞书中，便于检查结果
如需清理测试数据，请在飞书中手动删除测试数据表和记录。
---
## 测试命令参考
### 基础命令
```bash
# 运行所有测试
PYTHONPATH=src uv run pytest tests/ -v
# 运行特定模块
PYTHONPATH=src uv run pytest tests/bitable/test_app.py
# 运行特定测试
PYTHONPATH=src uv run pytest tests/bitable/test_record.py::TestBitableRecord::test_create_bitable_record
# 列出所有测试（不执行）
PYTHONPATH=src uv run pytest tests/ --co -q
```
### 高级选项
```bash
# 带覆盖率报告
PYTHONPATH=src uv run pytest tests/ --cov=src --cov-report=html
# 显示详细输出
PYTHONPATH=src uv run pytest tests/ -vv
# 遇到第一个失败就停止
PYTHONPATH=src uv run pytest tests/ -x
# 只运行上次失败的测试
PYTHONPATH=src uv run pytest tests/ --lf
# 只运行集成测试
PYTHONPATH=src uv run pytest tests/ -m integration
# 显示打印输出
PYTHONPATH=src uv run pytest tests/ -s
```
---
## 测试分类
### 数据表测试 (test_table.py)
- `test_create_bitable_table`: 创建空字段表
- `test_create_table_with_fields`: 创建带字段定义的表
- `test_create_table_invalid_token`: 创建失败场景
### 记录测试 (test_record.py)
- `test_create_bitable_record`: 创建记录
- `test_search_bitable_records_default`: 分页查询（默认page_size）
- `test_search_bitable_records_custom_page`: 自定义page_size查询
- `test_update_bitable_record`: 更新记录
- `test_batch_create_bitable_records`: 批量创建
- `test_batch_create_empty_list`: 空列表批量创建
- `test_batch_update_bitable_records`: 批量更新
- `test_batch_get_bitable_records`: 批量获取
- `test_batch_delete_bitable_records`: 批量删除
### 集成测试 (test_bitable_workflow.py)
- `test_full_workflow`: 完整工作流测试（创建应用 → 复制 → 创建表 → CRUD）
---
## 测试结果示例
```
============================= test session starts ==============================
platform darwin -- Python 3.10.19, pytest-9.0.2, pluggy-1.6.0
cachedir: .pytest_cache
rootdir: /Users/yuhuimr/Documents/Github/yuppie-mcp-feishu
configfile: pyproject.toml
plugins: anyio-4.12.0, cov-7.0.0
collected 17 items
tests/bitable/test_app.py::TestBitableApp::test_create_bitable_app PASSED [ 5%]
tests/bitable/test_app.py::TestBitableApp::test_create_app_without_folder PASSED [ 11%]
tests/bitable/test_app.py::TestBitableApp::test_copy_bitable_app PASSED [ 17%]
tests/bitable/test_app.py::TestBitableApp::test_copy_app_to_different_folder PASSED [ 23%]
tests/bitable/test_record.py::TestBitableRecord::test_create_bitable_record PASSED [ 29%]
...
======================= 17 passed, 3 warnings in 35.66s =======================
```
---
## 旧测试文件
`test_integration.py` 已被重构后的测试结构替代，但暂时保留。
**建议**：使用 `tests/` 目录下的新测试结构。
---
## 添加新测试
### 1. 创建测试文件
在相应模块下创建测试文件，例如 `tests/bitable/test_your_feature.py`
### 2. 编写测试
```python
import pytest
from tools.your_feature import your_function
class TestYourFeature:
"""功能测试类"""
@pytest.mark.integration
def test_your_function(self, test_app_token, test_table_id):
"""测试描述"""
result = your_function(
app_token=test_app_token,
table_id=test_table_id,
)
# 验证结果
assert result is not None
```
### 3. 使用 fixtures
在测试函数参数中声明需要的 fixtures：
- `test_config`: 测试配置
- `test_app_token`: 应用token（session级别）
- `test_table_id`: 数据表ID（session级别）
- `test_record_id`: 单条记录ID（function级别）
- `test_record_ids`: 批量记录ID（function级别）
### 4. 更新测试清单
在 `todoTestList.md` 中添加新测试的描述。
---
## 故障排查
### ImportError: No module named 'xxx'
确保使用 `PYTHONPATH=src` 运行测试：
```bash
PYTHONPATH=src uv run pytest tests/
```
### FEISHU_TEST_FOLDER_TOKEN not set
需要在 `.env` 文件中配置 `FEISHU_TEST_FOLDER_TOKEN`，或跳过需要该配置的测试。
### 测试失败
使用 `-v` 或 `-vv` 查看详细输出：
```bash
PYTHONPATH=src uv run pytest tests/ -vv
```
---
## 更多信息
- **详细测试清单**: 查看 `todoTestList.md`
- **项目文档**: 查看 `CLAUDE.md`
- **需求文档**: 查看 `需求文档.md`
