跳轉到

ui-translator E2E Three-Layer Integration Testing

概念概覽

三層 E2E 測試架構

核心知識

三層 E2E 測試架構

第一層：環境管理（backend/scripts/e2e-setup.sh）

  • --up / --down / --status 三個指令，E2E_TIMEOUT 環境變數控制超時（預設 120s）
  • 依序等待 PostgreSQL(5442) → MongoDB(27027) → Redis(6389) → Nakama(7350) 就緒
  • Nakama 先嘗試 /healthcheck，備用方案為 port 可達判斷
  • Makefile 新增 e2e-up / e2e-down / e2e-status / test-e2e targets

第二層：前端測試

  • Playwright smoke tests（frontend/e2e/smoke.spec.ts）：canvas 渲染、JS 錯誤偵測、截圖驗證；偵測 Nakama 認證請求，backend 不可用時自動 skip
  • Vitest API 整合測試（frontend/src/__tests__/e2e-api.integration.test.ts）：5 個 describe block、10 個測試；使用 crypto.randomUUID() 隔離狀態；Nakama 不可用時全部 skip（非 fail）

第三層：後端 Go E2E 測試

  • 使用 //go:build e2e build tag 隔離，執行方式：go test -tags=e2e ./test/... -v
  • skipIfNakamaUnavailable(t) helper 確保無環境時自動跳過
  • 11 個測試涵蓋：HealthCheck/Liveness/Readiness、CalculateDestiny 確定性驗證、GetQiState 自動初始化（currentQi == maxQi == 50）、完整業務流程（Calculate → Confirm → GetQi → RequestChapter → 扣 10 qi → RestoreQi daily → 驗證增加）

關鍵設計決策

  • 前端用 skip 而非 fail 處理 backend 不可用，使 CI 可在無 Docker 環境下跑單元測試
  • Go e2e 測試獨立 device ID（e2e-test-{uuid}）避免測試間狀態污染
  • Backend server key 硬碼為 15Mountjoy（開發用），生產須改為環境變數

經驗教訓

  • Playwright config 需指定 Vite dev server port（5173），否則測試找不到頁面

  • Go build tags（//go:build e2e）是隔離 E2E 測試的最佳做法，不影響一般 go test ./...

  • 多服務 Docker Compose 環境需依序健康檢查，Nakama 啟動較慢需備用 port 可達判斷

常見陷阱

  • scripts 建立後需手動 chmod +x，Bash 工具被拒絕時無法自動執行

  • Nakama /healthcheck endpoint 可能不存在，需備用方案確認 port 可達

  • 前後端聯調前所有測試都是各自單元測試，串接驗證必須實際啟動完整 backend stack

最佳實踐

  • 三層架構：環境腳本 → 前端 Playwright/Vitest → 後端 Go e2e，各層獨立可 skip

  • 使用 UUID 隔離每個測試的 device/user 狀態

  • 健康檢查腳本加入 timeout + 彩色輸出提升可觀測性

相關概念

來源 Sessions

日期 Session 貢獻摘要

| 2026-04-12 | 38030a5c-54da-4873-9a63-680709c843f1 | 為 ui-translator 建立三層整合測試架構：Docker Compose 環境腳本、Playwright smoke tests、Vitest API 整合測試、Go e2e build-tagged 測試 |

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-12