測試與 CI

這個倉庫的測試策略是「便宜的檢查每次跑，昂貴的檢查按範圍跑」。CI 負責保證生成產物一致、模組可匯入、關鍵鏈路不迴歸；真機識別效果仍然只能人工驗證。

測試分層

層	工具	數量級	特點
Python 單元測試	unittest	200+ 檔案	不連設備，使用夾具與臨時配置
Python 專項	pytest	tests/shop_event 等	參數化場景
前端單元	Vitest	組件、hooks、工具	jsdom 環境
前端端到端	Playwright	真實後端 / mock 兩套	覆蓋關鍵交互
匯入冒煙	自研腳本	遍歷 module/、deploy/	子處理程序匯入，白名單已知失敗
生成產物校驗	git diff	全量	配置、按鈕、API 契約

本地跑測試

# 全量 Python 单元测试
uv run python -m unittest discover -s tests

# 单个模块
uv run python -m unittest tests.test_api

# pytest 专项
uv run pytest tests/shop_event

# 导入冒烟（不连设备）
uv run python -m dev_tools.import_smoke_test

# 基础 lint
uv run ruff check . --select E9,F63,F7,F82 --ignore F821,F722

前端：

npm run typecheck --prefix frontend
npm test --prefix frontend
npm run test:e2e:mock --prefix frontend

不要每次改一行就跑全量

AGENTS.md 的約定是：優先跑與改動直接相關的測試；只有行為影響三個以上模組或大規模重構時才跑全量。生成檔案、翻譯、說明文件不計入「行為模組」數量。

CI 作業

.github/workflows/ci.yml，在 push 與 PR 時觸發，同一分支併發會取消舊執行。

作業	執行環境	內容
game-data	Ubuntu / Windows / macOS-14 矩陣	身份持久化、交易所、歷史認證、賬戶恢復、部署遷移
frontend	Ubuntu + Node 24	鎖檔案下載源、API 契約 diff、API/執行時/島嶼/心智/艦隊科技測試、前端構建與 Vitest、Playwright
ruff	Ubuntu	E9,F63,F7,F82（忽略 F821,F722）
button-config-check	Ubuntu	重跑 button_extract 與 config_updater，git diff --exit-code
import-smoke	Ubuntu	全量匯入 + tests.test_ci_import，上傳彙總

另有兩條協作工作流：

• ci-report-placeholder.yml：PR 提交時建立佔位評論。
• ci-report.yml：CI 完成後把佔位評論更新為結果報告。

為什麼 macOS 只跑 macos-14

macos-15-intel 沒有 llvmlite 的 x86_64 wheel，uv sync 會必然失敗。矩陣因此只包含 Apple Silicon 的 macos-14。

API 契約校驗

uv run python -m dev_tools.export_api_schema
git diff --exit-code -- frontend/src/api/generated.ts frontend/src/api/contract.json

改了後端參數模型卻沒匯出契約，CI 直接失敗。

生成產物校驗

uv run -m dev_tools.button_extract
uv run -m module.config.config_updater
git diff --exit-code

這條檢查攔住兩類問題：改了 YAML 沒生成，以及手改了生成檔案。

前端 e2e 的三種配置

命令	配置	用途
npm run test:e2e	預設	連真實後端，覆蓋主流程
npm run test:e2e:mock	playwright.mock.config.ts	模擬服務，介面改動首選
npx playwright test --config playwright.mind.config.ts	心智專項	心智計算器流程

CI 裡會安裝 Chromium 依賴並依次執行。

寫測試的邊界

能測	不能測
配置遷移、參數校驗	真實識別準確率
排程狀態機、恢復矩陣	模擬器兼容性
API 契約與會話鑑權	遊戲活動機制
前端交互與表單儲存	OEM 系統上的懸浮窗行為

靜態驗證不等於真機驗證

說明文件裡會明確區分「原始碼靜態驗證」與「真實設備驗證」。編譯通過、單測通過、甚至 CI 全綠，都不能說明某個識別在真機上可用。

提交前自檢

• [ ] 改動相關的 Python 測試通過
• [ ] ruff 通過
• [ ] 前端改動用 typecheck + vitest 驗證
• [ ] 改了 YAML → 跑過 config_updater
• [ ] 改了按鈕 → 跑過 button_extract
• [ ] 改了 API → 跑過 export_api_schema
• [ ] 生成產物與原始碼一起提交
• [ ] PR 描述寫清驗證方式與未驗證部分
• [ ] 未執行的檢查不要勾選

發佈相關

工作流	觸發	作用
docker-publish.yml	tag / master	構建並推送鏡像
sync-cnb.yml	推送	同步到 CNB
git-over-cdn-*.yml	定時 / 手動	國內鏡像分發
ai-issue-labeler.yml	Issue	自動打標籤

發佈流程見發佈與版本。