Tc To Pytest

tc-to-pytest

⚙️ 執行前先讀 modules/config-loader.md。 啟用條件：config.backend.pytest_enabled = true 且 config.backend.pytest_project_root 已設定。

適用場景

• ✅ 已有 Sheet TC（白箱 API 驗證類），要產對應 pytest test 檔
• ✅ speckit-to-tc 草擬完 draft markdown，要把 WB 區塊轉 pytest
• ✅ 想新增 BE feature 的 pytest 測試骨架

不適用場景

• ❌ Black-box UI / a11y / 跨平台 — 那是 test-automation 範疇
• ❌ Sheet 還沒 finalize（會生空殼）
• ❌ 純效能基準 / 壓測 — 用 Locust / JMeter

設定來源

從 config.json#backend 讀：

{
  "backend": {
    "pytest_enabled": true,
    "pytest_project_root": "~/Desktop/your_pytest_repo",
    "pytest_kit_pattern": "schemas.py + conftest.py + tests/test_<feature>_api.py",
    "client_naming": "<feature>_client + <feature>_auth_client",
    "schema_dsl": "S DSL (custom)",
    "feature_modules": ["health", "stamp", "wallet"]
  }
}

三件套位置（依 pytest_project_root）：

{{PYTEST_PROJECT_ROOT}}/
├── utils/schemas.py            # ① schema 定義
├── conftest.py                 # ② client fixture
└── tests/test_<feature>_api.py # ③ 測試函式

Phase 1: 取 TC 來源

Phase 2: 篩 WB API 驗證 row

從所有 WB row 中只挑這些分類：

跳過：純效能（cold start / TTFB）、純記憶體 leak、純內部狀態。

Phase 3: 抽取每條 TC 的 4 要素

對齊規則：每條 TC 的 ID（如 WB-{FEATURE}-XXX）→ pytest test function 開頭 docstring 寫對應 ID（雙向 traceability）。

Phase 4: 生成三件套

① utils/schemas.py — schema 定義

對每個 unique response shape 加一個 symbol（以 S DSL 為例）：

HEALTH_STEPS_SYNC = S.object({
    "synced_at": S.string(format="datetime"),
    "today_steps": S.integer(min=0),
    "trust_level": S.integer(min=0, max=5),
    "raw_archive_id": S.string(),
})

命名規則：<FEATURE>_<ENDPOINT_INTENT> 全大寫底線。

避免重複：先 Read 既有 utils/schemas.py，已存在就重用，不重複定義。

② conftest.py — fixture

每個新 feature 加一組 client fixture（依 client_naming 規則）：

@pytest.fixture(scope="session")
def health_client(config):
    client = APIClient(base_url=config["health_url"])
    return client

@pytest.fixture(scope="session")
def health_auth_client(health_client, uat_token):
    health_client.set_default_headers({"Authorization": f"Bearer {uat_token}"})
    return health_client

對齊：跟既有 client fixture 同 pattern。不重新定義 APIClient base class、不另外發明 auth 機制。

需要新 base_url 設定就只動 config/env.template.yaml 加 key，不動 env.yaml（私有檔）。

③ tests/test_<feature>_api.py — 測試函式

每條 TC 對應一個 pytest function：

def test_steps_sync_unauth_rejected(health_client):
    """
    對應 TC: WB-HEALTH-XXX（步數 sync 未授權 401 防偽）
    Spec: {{JIRA_PROJECT_KEY}}-XXXX
    """
    resp = health_client.post("/api/v1/health/steps/sync", json={"today_steps": 1000})
    assert resp.status_code in (401, 403), f"預期 401/403 got {resp.status_code}"

強制元素：

• docstring 第一行寫 對應 TC: <ID>（雙向 traceability）
• 用既有 assert_* helper（如有），別重發明
• schema 驗證統一 from utils.schema import validate, S
• skip 邏輯：feature 還沒部署 UAT → pytestmark = pytest.mark.skipif(...)

function 命名範例：

intent-based 命名 > 純 ID 命名（ID 進 docstring 即可）。

Phase 5: 雙向 traceability 報表

✅ 生成 X 條 pytest function；對應 X 條 WB TC

雙向對齊（pytest ↔ TC）：
test_steps_sync_unauth_rejected     ↔ WB-HEALTH-001
test_steps_range_7days_schema       ↔ WB-HEALTH-002
...

未對齊的 TC（需手動補或本 skill 不適用）：
WB-HEALTH-XXX 並發測試 → 標 @pytest.mark.parallel 但骨架待補
WB-HEALTH-XXX 效能基準 → Locust 範疇，不上 pytest

新增 schema symbols:
HEALTH_STEPS_SYNC / HEALTH_STEPS_RANGE / ...

新增 fixtures:
health_client / health_auth_client

下一步：
1. 你 review pytest（特別是 skip 條件、assert 嚴格度）
2. 部署到 UAT 後跑 `HEALTH_API_LIVE=1 pytest tests/test_health_api.py`
3. 跑 `pytest --collect-only` 確認 TC 雙向對齊
4. 在對應 TC Sheet 的「自動化」欄標 Y，「備註」欄寫 pytest function name

⚠️ 安全護欄

• ✅ 只 Write 到 {{PYTEST_PROJECT_ROOT}} 內三個目標檔
• ✅ Edit 既有檔時保留既有 import / fixture / schema，只追加新項
• ❌ 不動 config/env.yaml（私有 secrets）
• ❌ 不動 Dockerfile / .github/workflows/（CI 設定）
• ❌ 不主動跑 pytest（測試實際跑由使用者控制）
• ❌ 不主動 commit / push
• ⚠️ TC 沒寫清楚 endpoint / schema → 跳過該條，標 TODO，不要編造

BE feature 是新的（pytest 專案沒對應 client）

如果 feature 完全新，需要：

1. 加 {FEATURE}_API_LIVE env var + skip 邏輯
2. 加 <feature>_client fixture
3. 加 tests/test_<feature>_api.py
4. 建議跟使用者確認 base_url + auth 模式才動工

配套整合

• 草稿 TC → 用 speckit-to-tc 先草，再用此 skill 把 WB 段轉 pytest
• 寫完 pytest → 用 test-review 審 pytest 程式碼品質
• 部署到 UAT → 使用者手動 {FEATURE}_API_LIVE=1 pytest
• 想驗 TC 抓 bug 能力 → 用 mutation-testing
• 想升級 boundary 覆蓋 → 用 property-based-test-gen

設定依賴

範例

詳見 examples.md