技术债：统一本地测试入口（pytest pythonpath 配置，免 PYTHONPATH 拼接） #182

New Issue

tanzk · 2026-09-21T07:04:00+08:00

tanzk commented

2026-09-21 07:04:00 +08:00

背景

2026-09-21 技术债务盘点发现：本地跑后端测试必须手工拼 PYTHONPATH=. .venv/bin/pytest，
没有「开箱即跑」的统一入口。README 的 pip install -e ".[dev]" + pytest 教程与实际
已有 .venv 环境脱节；而 .venv_test 是 SCRM 采集调试专用精简环境（无 fastapi），
若误用它跑 pytest 会 collect 失败（43 个模块 ImportError），极易误判为「测试坏了」。

CI 侧已有 .gitea/workflows/test.yml（ruff + pytest 强制），本工单只补本地体验。

影响范围

backend/pytest.ini（加 pytest 内置 pythonpath 配置，消除 PYTHONPATH 手工拼接）
开发者本地测试运行方式（cd backend && .venv/bin/pytest 直接可用）

根因判断

pytest 从 7.0 起支持 pythonpath 配置项（pytest.ini [pytest] 段），
把项目根目录注入 sys.path，即可替代 PYTHONPATH=. 环境变量。属标准解法，非 hack。

处理动作

backend/pytest.ini 增加 pythonpath = . 配置项
验证：cd backend && .venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py -q（不带 PYTHONPATH）通过
验证：全量 collect 无 ERROR（cd backend && .venv/bin/pytest tests --collect-only -q）

验收标准 / 关闭条件

backend/pytest.ini 含 pythonpath = .
不带 PYTHONPATH 直接运行 .venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py 11 个用例全部通过
不带 PYTHONPATH 全量 --collect-only 无 ERROR（112 个测试文件全部收集成功）

关联

技术债务盘点（2026-09-21 会话）

## 背景 2026-09-21 技术债务盘点发现：本地跑后端测试必须手工拼 `PYTHONPATH=. .venv/bin/pytest`，没有「开箱即跑」的统一入口。README 的 `pip install -e ".[dev]"` + `pytest` 教程与实际已有 `.venv` 环境脱节；而 `.venv_test` 是 SCRM 采集调试专用精简环境（无 fastapi），若误用它跑 pytest 会 collect 失败（43 个模块 ImportError），极易误判为「测试坏了」。 CI 侧已有 `.gitea/workflows/test.yml`（ruff + pytest 强制），本工单只补本地体验。 ## 影响范围 - `backend/pytest.ini`（加 pytest 内置 `pythonpath` 配置，消除 PYTHONPATH 手工拼接） - 开发者本地测试运行方式（`cd backend && .venv/bin/pytest` 直接可用） ## 根因判断 pytest 从 7.0 起支持 `pythonpath` 配置项（pytest.ini `[pytest]` 段），把项目根目录注入 sys.path，即可替代 `PYTHONPATH=.` 环境变量。属标准解法，非 hack。 ## 处理动作 - [x] `backend/pytest.ini` 增加 `pythonpath = .` 配置项 - [x] 验证：`cd backend && .venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py -q`（不带 PYTHONPATH）通过 - [x] 验证：全量 collect 无 ERROR（`cd backend && .venv/bin/pytest tests --collect-only -q`） ## 验收标准 / 关闭条件 1. `backend/pytest.ini` 含 `pythonpath = .` 2. 不带 `PYTHONPATH` 直接运行 `.venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py` 11 个用例全部通过 3. 不带 `PYTHONPATH` 全量 `--collect-only` 无 ERROR（112 个测试文件全部收集成功） ## 关联 - 技术债务盘点（2026-09-21 会话）

tanzk added the tech-debt label 2026-09-21 07:04:00 +08:00

tanzk referenced this issue from a commit

2026-09-21 07:04:48 +08:00

#182 C: pytest.ini 增加 pythonpath 配置, 本地跑测试免 PYTHONPATH 拼接

tanzk commented

2026-09-21 07:05:01 +08:00

关闭凭证核验 (2026-09-21)

关闭条件	核验方式	结果
1. `backend/pytest.ini` 含 `pythonpath = .`	commit `f551a9c`，`git show f551a9c -- backend/pytest.ini` 可见 `pythonpath = .` 配置项	✅
2. 不带 `PYTHONPATH` 直接运行最小测试 11 个用例全部通过	实测 `cd backend && .venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py`（无 PYTHONPATH 环境变量）→ `11 passed, 1 warning in 2.59s`	✅
3. 不带 `PYTHONPATH` 全量 collect 无 ERROR（112 个测试文件全部收集成功）	实测 `cd backend && .venv/bin/pytest tests --collect-only -p no:warnings` → `1759 tests collected in 1.87s`，无 ERROR	✅

提交: f551a9c4e6
结论: 关闭条件全部满足，关闭本单。

## 关闭凭证核验 (2026-09-21) | 关闭条件 | 核验方式 | 结果 | |---|---|---| | 1. `backend/pytest.ini` 含 `pythonpath = .` | commit `f551a9c`，`git show f551a9c -- backend/pytest.ini` 可见 `pythonpath = .` 配置项 | ✅ | | 2. 不带 `PYTHONPATH` 直接运行最小测试 11 个用例全部通过 | 实测 `cd backend && .venv/bin/pytest tests/test_test_db_guard.py tests/test_smoke.py`（无 PYTHONPATH 环境变量）→ `11 passed, 1 warning in 2.59s` | ✅ | | 3. 不带 `PYTHONPATH` 全量 collect 无 ERROR（112 个测试文件全部收集成功） | 实测 `cd backend && .venv/bin/pytest tests --collect-only -p no:warnings` → `1759 tests collected in 1.87s`，无 ERROR | ✅ | **提交**: f551a9c4e6ea2a5c0a52306bda42467a6b0913e8 **结论**: 关闭条件全部满足，关闭本单。

tanzk closed this issue

2026-09-21 07:05:01 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tanzk/csctalon#182