578 lines
21 KiB
Markdown
578 lines
21 KiB
Markdown
# Life Echo API Pytest 测试覆盖计划
|
||
|
||
本计划假设架构重构计划已完成，项目已迁移至 `app/` 下的 feature-first 结构。
|
||
|
||
策略：**删除全部旧 unittest，用 pytest 从零重写。**
|
||
|
||
---
|
||
|
||
## 一、旧测试处置
|
||
|
||
### 删除（13 个 unittest 文件）
|
||
|
||
全部删除。重写时参考其覆盖场景：
|
||
|
||
| 旧文件 | 覆盖场景 | 重写到 |
|
||
|--------|----------|--------|
|
||
| `test_memoir_image_settings.py` | from_env 默认值、无效整数回退 | `unit/adapters/test_image_gen_liblib.py` |
|
||
| `test_memoir_image_schema.py` | normalize 无效 status、缺字段 | `unit/features/test_memoir_service.py` |
|
||
| `test_memoir_image_parser.py` | 占位符解析、双大括号 | `unit/features/test_memoir_service.py` |
|
||
| `test_memoir_image_provider.py` | 签名、提交、轮询、下载 | `unit/adapters/test_image_gen_liblib.py` |
|
||
| `test_memoir_image_storage.py` | 单例、上传、下载 URL、错误 | `unit/adapters/test_storage_tencent_cos.py` |
|
||
| `test_memoir_image_prompting.py` | 无 LLM 回退、JSON 解析 | `unit/features/test_memoir_service.py` |
|
||
| `test_memoir_image_bootstrap.py` | 启用/禁用、动态上限 | `unit/features/test_memoir_service.py` |
|
||
| `test_generate_chapter_images_task.py` | 锁、重试、幂等、JPEG->PNG | `unit/tasks/test_memoir_tasks.py` |
|
||
| `test_process_memoir_segments_image_enqueue.py` | markdown JSON、入队、禁用 | `unit/tasks/test_memoir_tasks.py` |
|
||
| `test_memoir_tasks_redis.py` | Redis 锁复用 | `unit/tasks/test_memoir_tasks.py` |
|
||
| `test_pdf_service_images.py` | 图片宽高比、签名失败跳过 | `unit/features/test_memoir_service.py` |
|
||
| `test_chapters_router_images.py` | 签名 URL、畸形资产 | `unit/features/test_memoir_router.py` |
|
||
| `test_websocket_baseline.py` | 无效 token、文本/音频/转写、结束、乱序、去重、重连 | `unit/features/test_ws_pipeline.py` |
|
||
|
||
### 移出（2 个手工脚本）
|
||
|
||
- `test_sms_verification.py` -> `scripts/manual/sms_verification.py`
|
||
- `test_conversation.py` -> `scripts/manual/conversation_e2e.py`
|
||
|
||
---
|
||
|
||
## 二、测试目录结构
|
||
|
||
```
|
||
api/
|
||
pyproject.toml # 生产依赖 + dev 依赖 + pytest/coverage 配置
|
||
uv.lock # lockfile，纳入版本控制
|
||
Makefile
|
||
|
||
tests/
|
||
conftest.py # unit 层 fixtures
|
||
factories.py # make_user(), make_conversation() 等
|
||
fakes/ # port fake 实现（无 __init__.py）
|
||
sms.py
|
||
llm.py
|
||
storage.py
|
||
image_gen.py
|
||
tts.py
|
||
asr.py
|
||
helpers.py
|
||
|
||
unit/
|
||
core/
|
||
test_config.py
|
||
test_security.py
|
||
test_errors.py
|
||
test_middleware.py
|
||
adapters/
|
||
test_sms_tencent.py
|
||
test_llm_deepseek.py
|
||
test_image_gen_liblib.py
|
||
test_storage_tencent_cos.py
|
||
test_tts_openai.py
|
||
test_asr_whisper.py
|
||
test_asr_tencent.py
|
||
test_payment_wechat.py
|
||
test_payment_alipay.py
|
||
features/
|
||
test_auth_service.py
|
||
test_auth_router.py
|
||
test_conversation_service.py
|
||
test_conversation_router.py
|
||
test_ws_connection_manager.py
|
||
test_ws_message_types.py
|
||
test_ws_pipeline.py
|
||
test_ws_profile_collector.py
|
||
test_ws_quota_guard.py
|
||
test_memoir_service.py
|
||
test_memoir_router.py
|
||
test_payment_service.py
|
||
test_payment_router.py
|
||
test_user_service.py
|
||
test_user_router.py
|
||
test_quota_service.py
|
||
test_quota_router.py
|
||
test_plan_service.py
|
||
test_plan_router.py
|
||
test_content_router.py
|
||
agents/
|
||
test_conversation_agent.py
|
||
test_memory_agent.py
|
||
tasks/
|
||
test_memoir_tasks.py
|
||
|
||
integration/
|
||
conftest.py
|
||
test_auth_repo.py
|
||
test_conversation_repo.py
|
||
test_memoir_repo.py
|
||
test_payment_repo.py
|
||
test_user_repo.py
|
||
test_quota_repo.py
|
||
test_auth_service_write.py
|
||
test_payment_service_write.py
|
||
test_conversation_service_write.py
|
||
test_memoir_tasks_db.py
|
||
test_auth_flow.py
|
||
test_conversation_flow.py
|
||
test_payment_flow.py
|
||
test_alembic.py
|
||
```
|
||
|
||
### 设计原则
|
||
|
||
- **无 `__init__.py`**：测试目录不放 `__init__.py`，避免包导入副作用。
|
||
- **repo 测试全部放 integration/**：不用 SQLite 模拟 Postgres。SQLite 掩盖 JSON/JSONB、约束、排序、方言差异。
|
||
- **router 测试在 unit/**：override service stub，不跑真实 service/repo/DB。
|
||
- **service 测试分两层**：unit mock repo 测编排；integration 真实 Postgres 测关键写路径的事务边界。
|
||
- features 下文件名 flat，减少嵌套。
|
||
|
||
---
|
||
|
||
## 三、基建代码
|
||
|
||
### 3.1 pyproject.toml
|
||
|
||
生产依赖通过 `uv add <pkg>` 添加到 `[project.dependencies]`，dev 依赖通过 `uv add --dev <pkg>` 添加到 `[dependency-groups]`。禁止手动编辑依赖列表。
|
||
|
||
用 `uv sync --dev` 安装全部依赖（含 dev），`uv.lock` 纳入版本控制。不在 `addopts` 中全局过滤 marker。
|
||
|
||
当前开发工具链职责约定：
|
||
|
||
- `ruff`：负责 `lint` + `format`
|
||
- `pytest`：统一测试入口
|
||
- `pytest-asyncio`：负责 `async def` 测试和异步 fixture
|
||
- `pytest-cov`：负责覆盖率统计
|
||
- `pyright`：负责类型检查，但不替代测试和 `lint`
|
||
|
||
### 3.2 Makefile
|
||
|
||
```makefile
|
||
.PHONY: lint format typecheck test test-unit test-integration test-all test-cov
|
||
|
||
lint: ## 代码检查
|
||
uv run ruff check .
|
||
|
||
format: ## 代码格式化
|
||
uv run ruff format .
|
||
|
||
typecheck: ## 类型检查
|
||
uv run pyright
|
||
|
||
test: test-unit ## 默认只跑 unit
|
||
|
||
test-unit: ## 零外部依赖
|
||
uv run pytest tests/unit/ -x -q
|
||
|
||
test-integration: ## 需要 Postgres + Redis
|
||
uv run pytest tests/integration/ -x -q
|
||
|
||
test-all: ## 全部
|
||
uv run pytest tests/ -x -q
|
||
|
||
test-cov: ## 带覆盖率
|
||
uv run pytest tests/ --cov=app --cov-report=term-missing
|
||
```
|
||
|
||
### 3.3 tests/conftest.py（unit 测试用）
|
||
|
||
关键设计：router 测试 override **service**（不是 port），service 测试直接构造实例注入 fake ports。两者不重叠。
|
||
|
||
```python
|
||
import pytest
|
||
from unittest.mock import AsyncMock
|
||
from httpx import ASGITransport, AsyncClient
|
||
|
||
|
||
# ---- Service stubs ----
|
||
# 每个 feature service 一个 AsyncMock，预设 return_value 匹配方法签名。
|
||
# 以 auth 为例，其余 feature 同理。
|
||
@pytest.fixture
|
||
def auth_service_stub():
|
||
stub = AsyncMock()
|
||
stub.register.return_value = {"access_token": "t", "refresh_token": "r"}
|
||
stub.login.return_value = {"access_token": "t", "refresh_token": "r"}
|
||
return stub
|
||
|
||
@pytest.fixture
|
||
def conversation_service_stub():
|
||
return AsyncMock()
|
||
|
||
# memoir_service_stub, payment_service_stub, user_service_stub,
|
||
# quota_service_stub, plan_service_stub 同理，均为 AsyncMock()
|
||
|
||
|
||
# ---- Fake ports（service 层单测用）----
|
||
# 每个 port 一个 fixture，从 tests/fakes/ 导入。
|
||
@pytest.fixture
|
||
def fake_sms():
|
||
from tests.fakes.sms import InMemorySmsSender
|
||
return InMemorySmsSender()
|
||
|
||
@pytest.fixture
|
||
def fake_llm():
|
||
from tests.fakes.llm import StubLLMProvider
|
||
return StubLLMProvider(default_response="测试回复")
|
||
|
||
# fake_storage, fake_image_gen, fake_tts, fake_asr 同理
|
||
|
||
|
||
# ---- Router 测试用 app（override service 层）----
|
||
@pytest.fixture
|
||
def app(auth_service_stub, conversation_service_stub, ...):
|
||
from app.main import create_app
|
||
from app.features.auth.deps import get_auth_service
|
||
from app.features.conversation.deps import get_conversation_service
|
||
# ... 其余 feature deps
|
||
|
||
application = create_app()
|
||
application.dependency_overrides[get_auth_service] = lambda: auth_service_stub
|
||
application.dependency_overrides[get_conversation_service] = lambda: conversation_service_stub
|
||
# ... 其余 feature overrides
|
||
return application
|
||
|
||
@pytest.fixture
|
||
async def client(app):
|
||
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
|
||
yield c
|
||
|
||
|
||
# ---- 认证 fixture ----
|
||
# 必须 override get_current_user 本身，不能只提供 JWT header。
|
||
# get_current_user 通常会查 DB 加载用户，只发 header 会泄漏真实依赖。
|
||
@pytest.fixture
|
||
def stub_current_user():
|
||
from tests.factories import make_user
|
||
return make_user(id="test-user-id", subscription_type="free")
|
||
|
||
@pytest.fixture
|
||
def authenticated_app(app, stub_current_user):
|
||
from app.core.dependencies import get_current_user
|
||
app.dependency_overrides[get_current_user] = lambda: stub_current_user
|
||
return app
|
||
|
||
@pytest.fixture
|
||
async def auth_client(authenticated_app):
|
||
async with AsyncClient(
|
||
transport=ASGITransport(app=authenticated_app),
|
||
base_url="http://test",
|
||
) as c:
|
||
yield c
|
||
```
|
||
|
||
### 3.4 integration/conftest.py（savepoint 隔离）
|
||
|
||
```python
|
||
import pytest
|
||
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
|
||
from sqlalchemy import event, create_engine
|
||
from app.core.db import Base
|
||
|
||
@pytest.fixture(scope="session")
|
||
async def pg_engine():
|
||
import os
|
||
url = os.environ["TEST_DATABASE_URL"]
|
||
engine = create_async_engine(url)
|
||
|
||
from alembic.config import Config
|
||
from alembic.command import upgrade
|
||
cfg = Config("alembic.ini")
|
||
cfg.set_main_option("sqlalchemy.url", url.replace("+asyncpg", "+psycopg"))
|
||
upgrade(cfg, "head")
|
||
|
||
yield engine
|
||
await engine.dispose()
|
||
|
||
@pytest.fixture
|
||
async def pg_session(pg_engine):
|
||
"""
|
||
连接级事务 + savepoint。
|
||
service 内部 commit() 变为 savepoint release，
|
||
测试结束时外层事务 rollback 撤销一切。
|
||
|
||
硬性前提：被测代码必须复用此 session，不得自行创建 session。
|
||
自行创建 session 的代码（如 Celery 任务）不走此 fixture。
|
||
"""
|
||
conn = await pg_engine.connect()
|
||
txn = await conn.begin()
|
||
session = AsyncSession(bind=conn)
|
||
|
||
nested = await conn.begin_nested()
|
||
|
||
@event.listens_for(session.sync_session, "after_transaction_end")
|
||
def restart_savepoint(s, transaction):
|
||
nonlocal nested
|
||
if transaction.nested and not transaction._parent.nested:
|
||
nested = conn.sync_connection.begin_nested()
|
||
|
||
yield session
|
||
|
||
await session.close()
|
||
await txn.rollback()
|
||
await conn.close()
|
||
|
||
# ---- Celery 任务用同步 session（不走 savepoint，用 truncate 清理）----
|
||
@pytest.fixture
|
||
def sync_session(pg_engine):
|
||
import os
|
||
sync_url = os.environ["TEST_DATABASE_URL"].replace("+asyncpg", "+psycopg")
|
||
sync_engine = create_engine(sync_url)
|
||
from sqlalchemy.orm import Session
|
||
with Session(sync_engine) as session:
|
||
yield session
|
||
with sync_engine.begin() as conn:
|
||
for table in reversed(Base.metadata.sorted_tables):
|
||
conn.execute(table.delete())
|
||
|
||
# ---- Integration app（注入 pg_session + fake ports）----
|
||
@pytest.fixture
|
||
async def integration_app(pg_session, fake_sms, fake_llm, fake_storage,
|
||
fake_image_gen, fake_tts, fake_asr):
|
||
from app.main import create_app
|
||
from app.core.db import get_async_db
|
||
from app.core.dependencies import (
|
||
get_sms_sender, get_llm_provider, get_storage,
|
||
get_image_generator, get_tts_provider, get_asr_provider,
|
||
)
|
||
application = create_app()
|
||
application.dependency_overrides[get_async_db] = lambda: pg_session
|
||
application.dependency_overrides[get_sms_sender] = lambda: fake_sms
|
||
application.dependency_overrides[get_llm_provider] = lambda: fake_llm
|
||
application.dependency_overrides[get_storage] = lambda: fake_storage
|
||
application.dependency_overrides[get_image_generator] = lambda: fake_image_gen
|
||
application.dependency_overrides[get_tts_provider] = lambda: fake_tts
|
||
application.dependency_overrides[get_asr_provider] = lambda: fake_asr
|
||
yield application
|
||
application.dependency_overrides.clear()
|
||
|
||
@pytest.fixture
|
||
async def integration_client(integration_app):
|
||
async with AsyncClient(
|
||
transport=ASGITransport(app=integration_app),
|
||
base_url="http://test",
|
||
) as c:
|
||
yield c
|
||
```
|
||
|
||
### 3.5 factories.py
|
||
|
||
不使用 factory-boy（`SQLAlchemyModelFactory` 默认为同步 Session，和 AsyncSession 配合需大量封装）。用简单同步 helper 函数：
|
||
|
||
```python
|
||
import uuid
|
||
from datetime import datetime, timezone
|
||
from app.features.user.models import User
|
||
from app.features.conversation.models import Conversation
|
||
|
||
_seq = 0
|
||
|
||
def make_user(**overrides) -> User:
|
||
global _seq; _seq += 1
|
||
defaults = dict(
|
||
id=str(uuid.uuid4()),
|
||
phone=f"1380000{_seq:04d}",
|
||
nickname=f"用户{_seq}",
|
||
subscription_type="free",
|
||
created_at=datetime.now(timezone.utc),
|
||
)
|
||
defaults.update(overrides)
|
||
return User(**defaults)
|
||
|
||
# make_conversation, make_segment, make_book, make_chapter,
|
||
# make_memoir_state, make_order, make_refresh_token, make_sms_code 同理。
|
||
# 同步构造 model 实例，integration 测试中 session.add() + await session.flush() 入库。
|
||
```
|
||
|
||
### 3.6 Fake Port 实现
|
||
|
||
`tests/fakes/` 下每个 port 一个文件，无 `__init__.py`，实现完整 Protocol 签名：
|
||
|
||
- **sms.py** -- `InMemorySmsSender`：`sent: list` 记录历史，`should_fail` 可切换失败模式
|
||
- **llm.py** -- `StubLLMProvider`：`default_response`，`responses: list`（按序消耗），`call_count`
|
||
- **storage.py** -- `InMemoryStorage`：`dict[str, bytes]` 后端
|
||
- **image_gen.py** -- `StubImageGenerator`：`generate()` 返回预设结果，`check_status()` 按调用次数切换
|
||
- **tts.py** -- `StubTTSProvider`：返回固定 bytes
|
||
- **asr.py** -- `StubASRProvider`：`default_text`，空串模拟转写失败
|
||
|
||
---
|
||
|
||
## 四、分层测试策略
|
||
|
||
### 4.1 Service unit 测试（unit/features/test_*_service.py）
|
||
|
||
mock repo + fake ports，测编排逻辑和错误分支。每个 feature 预计 10-25 case。
|
||
|
||
```python
|
||
# 示例：展示 service unit test 的边界——mock repo，不碰 DB
|
||
async def test_auth_register_duplicate_phone(fake_sms):
|
||
repo = AsyncMock()
|
||
repo.find_by_phone.return_value = make_user(phone="13800000001")
|
||
|
||
service = AuthService(repo=repo, sms=fake_sms)
|
||
with pytest.raises(ConflictError):
|
||
await service.register(RegisterRequest(phone="13800000001", ...))
|
||
```
|
||
|
||
### 4.2 Service integration 测试（integration/test_*_service_write.py）
|
||
|
||
真实 Postgres（savepoint 隔离）+ 真实 repo + fake ports。**只覆盖关键写路径**的事务边界和 ORM 状态持久化：
|
||
|
||
- **auth register**：User + RefreshToken 在同一事务创建，失败时两者都不残留
|
||
- **payment callback**：订单状态变更 + 用户订阅升级在同一事务
|
||
- **conversation end**：段落状态标记 + Celery 任务提交边界
|
||
|
||
```python
|
||
# 示例：展示与 unit test 的关键区别——验证 DB 中真实存在数据
|
||
@pytest.mark.integration
|
||
async def test_register_creates_user_and_token_atomically(pg_session, fake_sms):
|
||
repo = AuthRepo(pg_session)
|
||
service = AuthService(repo=repo, sms=fake_sms)
|
||
|
||
result = await service.register(RegisterRequest(phone="13800000001", ...))
|
||
|
||
user = await pg_session.get(User, result.user_id)
|
||
assert user is not None
|
||
assert user.phone == "13800000001"
|
||
|
||
tokens = await repo.find_refresh_tokens_by_user(user.id)
|
||
assert len(tokens) == 1
|
||
```
|
||
|
||
每个 feature 写路径预计 3-8 case，总计约 15-25 case。
|
||
|
||
### 4.3 Router unit 测试（unit/features/test_*_router.py）
|
||
|
||
override service stub + get_current_user，只验证 HTTP 契约。与 service 测试不重叠：router 不验证"重复手机号返回什么"，只验证"service 抛 ConflictError 时 router 返回 409"。
|
||
|
||
```python
|
||
# 示例：展示 router test 的边界——验证 HTTP 契约，不碰 service 内部
|
||
async def test_register_calls_service(client, auth_service_stub):
|
||
resp = await client.post("/api/auth/register", json={"phone": "13800000001", ...})
|
||
assert resp.status_code == 201
|
||
auth_service_stub.register.assert_called_once()
|
||
|
||
async def test_profile_requires_auth(client):
|
||
resp = await client.get("/api/user/profile")
|
||
assert resp.status_code == 401
|
||
```
|
||
|
||
每个 feature 预计 8-20 case。
|
||
|
||
### 4.4 Repo integration 测试（integration/test_*_repo.py）
|
||
|
||
真实 Postgres（savepoint 隔离），factory helper 构造数据。不用 SQLite。
|
||
|
||
```python
|
||
# 示例：展示 repo test 的边界——真实 Postgres，验证 SQL 正确性
|
||
@pytest.mark.integration
|
||
async def test_find_refresh_token(pg_session):
|
||
user = make_user()
|
||
pg_session.add(user)
|
||
token = make_refresh_token(user_id=user.id, token="abc123")
|
||
pg_session.add(token)
|
||
await pg_session.flush()
|
||
|
||
repo = AuthRepo(pg_session)
|
||
found = await repo.find_refresh_token("abc123")
|
||
assert found is not None
|
||
assert found.user_id == user.id
|
||
```
|
||
|
||
每个 feature 预计 5-15 case。
|
||
|
||
### 4.5 Adapter unit 测试（unit/adapters/）
|
||
|
||
`respx` mock httpx / `unittest.mock.patch` mock SDK client。每个 adapter 至少：成功路径 + 网络超时 + rate limit + 响应格式异常。每个 adapter 预计 8-15 case。
|
||
|
||
### 4.6 WebSocket unit 测试（unit/features/test_ws_*.py）
|
||
|
||
5 个文件对应 ws/ 子包 5 个模块：
|
||
|
||
- **test_ws_connection_manager.py**：注册/注销、并发同 ID、断开容错（6-8 case）
|
||
- **test_ws_message_types.py**：枚举完整性、序列化（5-6 case）
|
||
- **test_ws_pipeline.py**：文本->Agent->落库、音频->ASR->Agent->TTS、无效 token、ASR 失败降级、乱序聚合、幂等去重、结束->整理、重连（15-20 case）
|
||
- **test_ws_profile_collector.py**：缺失检测、提取、已满跳过（5-8 case）
|
||
- **test_ws_quota_guard.py**：配额内通过、耗尽拒绝、plan 差异（5-8 case）
|
||
|
||
### 4.7 Agents unit 测试
|
||
|
||
注入 StubLLMProvider，验证 prompt 构建、响应解析、异常降级。每个 agent 8-12 case。
|
||
|
||
### 4.8 Celery Tasks 测试——两层
|
||
|
||
**Unit**（unit/tasks/test_memoir_tasks.py）：mock repo/service 测编排逻辑。20-25 case。
|
||
|
||
**Integration**（integration/test_memoir_tasks_db.py）：真实 Postgres + fake ports，验证 DB 状态机持久化。纯 mock 测不到 Chapter 状态转换、segment is_processed 标记、image_assets JSON 持久化。
|
||
|
||
由于 Celery 任务使用同步 Session（不经过 DI），savepoint 隔离不住，改用 truncate 策略（见 `integration/conftest.py` 中的 `sync_session` fixture）。5-10 case，只覆盖关键状态转换。
|
||
|
||
---
|
||
|
||
## 五、端到端流程 + Alembic
|
||
|
||
### 端到端流程（integration/）
|
||
|
||
- **test_auth_flow.py**：注册 -> 登录 -> 获取 profile -> 刷新 -> 登出 -> 旧 token 失效
|
||
- **test_conversation_flow.py**：创建对话 -> 发消息 -> Agent 回复 -> 消息列表 -> 结束 -> 触发整理
|
||
- **test_payment_flow.py**：查看计划 -> 创建订单 -> 模拟回调 -> 验证订阅类型变更
|
||
|
||
### Alembic 测试
|
||
|
||
Forward-only smoke，不做 downgrade（业务 migration 不一定可逆）：
|
||
- `test_alembic_upgrade_clean_db`：空库 upgrade head 无报错
|
||
- `test_alembic_current_at_head`：验证测试库 current == head
|
||
|
||
---
|
||
|
||
## 六、CI 集成
|
||
|
||
```yaml
|
||
jobs:
|
||
test:
|
||
name: Run Tests
|
||
runs-on: ubuntu-latest
|
||
services:
|
||
postgres:
|
||
image: postgres:16
|
||
env: { POSTGRES_DB: life_echo_test, POSTGRES_PASSWORD: test }
|
||
ports: ["5432:5432"]
|
||
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
|
||
redis:
|
||
image: redis:7
|
||
ports: ["6379:6379"]
|
||
defaults:
|
||
run:
|
||
working-directory: api
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: astral-sh/setup-uv@v4
|
||
- run: uv sync --dev
|
||
- name: Unit tests
|
||
run: make test-unit
|
||
- name: Integration tests
|
||
run: make test-integration
|
||
env:
|
||
TEST_DATABASE_URL: postgresql+asyncpg://postgres:test@localhost:5432/life_echo_test
|
||
REDIS_URL: redis://localhost:6379/0
|
||
- uses: codecov/codecov-action@v4
|
||
|
||
build-and-push:
|
||
needs: test
|
||
# ... 现有 build 步骤 ...
|
||
```
|
||
|
||
---
|
||
|
||
## 七、测试规则
|
||
|
||
1. **新代码必须附带测试**，PR 不通过无测试的业务变更
|
||
2. **全部使用 pytest 函数 + fixture 风格**
|
||
3. **repo 测试只在 integration/ 中跑 Postgres**，不用 SQLite
|
||
4. **service unit 测试 mock repo + fake ports**；关键写路径补 service integration 测试（真实 Postgres + fake ports）
|
||
5. **router 测试 override service stub + get_current_user**，只验证 HTTP 契约
|
||
6. **adapter 测试 mock 外部调用**，至少成功 + 2 种错误场景
|
||
7. **每个 test function 状态独立**（unit 无 DB；integration 用 savepoint 隔离）
|
||
8. **savepoint 硬性前提：被测代码必须复用注入的 session，不得自行创建**。Celery 任务用独立测试库 + truncate
|
||
9. **integration 标记 `@pytest.mark.integration`**
|
||
10. **默认命令 `make test`**（unit），`make test-all` 全部
|
||
11. **测试目录无 `__init__.py`**
|
||
12. **依赖通过 uv 管理**：`uv sync --dev` 安装，`uv add --dev <pkg>` 新增 dev 依赖，禁止 `pip install`
|
||
13. **类型检查由 `pyright` 负责**：它用于发现静态类型问题，但不能替代 `ruff` 或 `pytest`
|