Backend Testing Skill (pytest)

何時使用

•你改了後端 use case / repository / router / schema，想快速確認沒壞
•CI 報測試失敗，你想在本機快速重現與縮小範圍
•想針對單一模組或單一測試用例跑迭代（TDD）
•想跑 coverage 或找出最慢的測試

預設策略（推薦）

•
優先用 Poetry 環境跑測試（poetry run pytest）
- •原因：後端 Docker container 的啟動腳本只安裝 main dependencies（不含 pytest/ruff 等 dev deps），因此「直接在目前的 backend 容器內跑 pytest」通常不可行。
•測試 root 位置：apps/backend

最常用指令

下列命令都假設你在 repo 根目錄；若你已在 apps/backend，可省略 cd apps/backend。

1) 跑全套（最常用）

bash

cd apps/backend
poetry run pytest -v

2) 只跑 unit 或 integration

bash

# Unit
cd apps/backend
poetry run pytest -v tests/unit

# Integration
cd apps/backend
poetry run pytest -v tests/integration

3) 跑單一檔案 / 單一測試

bash

# 單一檔案
cd apps/backend
poetry run pytest -v tests/unit/posts/test_create_post_use_case.py

# 單一測試（用節點表示法）
cd apps/backend
poetry run pytest -v tests/test_main.py::test_api_health_check

4) 以關鍵字篩選（快速縮小範圍）

bash

cd apps/backend
poetry run pytest -v -k "profile or login"

5) 失敗重跑 / 快速迭代

bash

# 只跑上次失敗的測試
cd apps/backend
poetry run pytest -v --lf

# 先跑上次失敗的，再跑其他（適合修完後確認）
cd apps/backend
poetry run pytest -v --ff

6) 看到最慢的測試（效能排查）

bash

cd apps/backend
poetry run pytest -v --durations=10

7) 快速 fail-fast（縮短回饋時間）

bash

cd apps/backend
poetry run pytest -v -x
# 或：poetry run pytest -v --maxfail=1

Coverage（pytest-cov）

此專案已安裝 pytest-cov（dev dependencies）。常用命令：

bash

cd apps/backend
poetry run pytest -v --cov=app --cov-report=term-missing

需要 HTML 報告：

bash

cd apps/backend
poetry run pytest -v --cov=app --cov-report=html

成功判準：終端機出現 coverage summary，或生成 htmlcov/。

特殊情境：GCS smoke tests

•專案定義了 gcs_smoke marker，並建議只在設定 RUN_GCS_SMOKE=1 時執行。
•一般開發/CI 的 unit/integration 測試應使用 Mock GCS。

執行方式：

bash

cd apps/backend
RUN_GCS_SMOKE=1 poetry run pytest -v -m gcs_smoke

注意：如果沒有任何測試實際標記 @pytest.mark.gcs_smoke，上述命令會跑不到測試；此時應以目前既有測試為準。

Makefile 對應指令

•你也可以用 repo 根目錄的 Makefile：

bash

make test

注意：make test 目前是直接呼叫 pytest -v（不經 poetry run）。若你不是在已啟用 dev venv 的環境，可能會找不到 pytest；此時請改用本 skill 的 Poetry 指令。

已知限制 / 待改善點（如需可再做成另一個 skill）

•
apps/backend/tests/conftest.py 內的 testcontainers fixture 目前是 pytest.skip("Testcontainers not yet configured")。
- •若你想讓「需要資料庫容器的整合測試」真正跑起來，需要補上 testcontainers[postgres] 並解除註解。

觸發本 skill 的建議提問方式（範例）

•「請用 Poetry 跑後端全套測試，失敗就用 --lf 重跑」
•「只跑 posts 模組的 unit tests，並列出最慢 10 個」
•「幫我跑這個單一測試並用 -x fail-fast」
•「我要跑 coverage（term-missing + html）」