跳轉到

ui-translator E2E 環境建置、三層整合測試全覆蓋與引擎選型評估（融合版 v13）

文檔資訊

  • 分類: best-practices
  • 難度: intermediate
  • 預估閱讀時間: 27 分鐘
  • 標籤: e2e-testing, nakama, docker-compose, crlf, makefile, playwright, go-build-tags, integration-testing, ui-translator, vitest, pixijs, canvas-testing, cocos-typescript, engine-evaluation, slm-novel-generation, qwen3, local-llm, ollama, session-token, nakama-config, ux-gap, agent-browser, state-machine, polling, resource-exhaustion, debugging

摘要

在 ui-translator 專案中識別前後端從未真正聯調的問題，完成 CRLF 修復、Makefile bug 修正、E2E 環境管理腳本建立，並新增三層整合測試（Playwright smoke、Vitest API integration、Go e2e RPC）。v13 新增關鍵診斷線索：前端確實顯示「正在為您撰寫章節...」訊息，表示生成流程已觸發，UX 缺口範圍從「整個流程不通」縮小至「章節內容結果未渲染」。WSL2 資源耗盡（exit code 144）與 Nakama session token 過短問題均已確認並記錄。

關鍵學習

  • 所有單元測試通過 ≠ 前後端串接正常，必須有實際打 RPC 的整合驗證

  • exit code 0 的後台任務驗證不等於 UX 修復：v11 輪詢邏輯通過驗證但用戶實測仍無效（v12/v13 實證）

  • 「正在為您撰寫章節...」訊息出現 = 生成流程已觸發，UX 缺口縮小為「章節內容結果未渲染」（v13 新增）

  • PixiJS canvas 內容無法被 DOM selector 或 Playwright codegen 檢查，這是根本性限制

  • Cocos TypeScript 引擎具備 DOM/節點樹可查詢結構，對 AI agent 輔助開發顯著優於 PixiJS

  • Nakama 預設 session 生命週期過短，需配置 token_expiry_sec 與 refresh_token_expiry_sec

  • Ollama 在 Ubuntu/WSL2 上安裝需先安裝 zstd 套件，否則 install.sh 會報錯

  • WSL2 並行啟動 Docker 服務群 + Ollama + E2E 測試可能觸發 OOM，exit code 144 是典型信號

  • 前端 UX 問題在多次迭代後仍未解決時，正確診斷方向是靜態代碼路徑審查而非更多背景測試任務

  • Makefile 新增 target 時必須同步更新 .PHONY，否則同名目錄會導致 target 不執行

  • Go e2e 測試使用 //go:build e2e tag 隔離，避免一般 go test 時誤跑

  • Claude 無法直接操作前端瀏覽器（agent-browser 工具不可用），UX 驗收必須由用戶手動執行

技術細節

技術堆疊

ui-translator 後端使用 Nakama（遊戲伺服器框架）+ MongoDB + Redis + PostgreSQL 的組合，前端透過 Nakama RPC 呼叫取得命格生成、章節閱讀、靈力消耗等資料。前端為 Vite + TypeScript + PixiJS，整合測試框架為 Vitest，E2E 瀏覽器測試框架為 Playwright。

三層整合測試架構

  • 層一：Playwright Smoke Tests（frontend/e2e/smoke.spec.ts）— App Startup、API Connectivity、Visual Smoke Test
  • 層二：Vitest API Integration Tests（frontend/src/__tests__/e2e-api.integration.test.ts）— 5 個 describe block、10 個測試案例，Nakama 不可用時 skip 而非 fail
  • 層三：Go E2E RPC Tests（backend/test/）— 使用 //go:build e2e tag，11 個測試案例，完整流程：Calculate → Confirm → GetQi → RequestChapter → RestoreQi

Nakama Session 設定問題

瀏覽器 Console 出現以下警告，表示 session token 預設生命週期過短：

Session lifetime too short, please set '--session.token_expiry_sec' option.
Session refresh lifetime too short, please set '--session.refresh_token_expiry_sec' option.

需在 docker-compose.yml 中加入：

environment:
  - NAKAMA_SESSION_TOKEN_EXPIRY_SEC=86400
  - NAKAMA_SESSION_REFRESH_TOKEN_EXPIRY_SEC=604800

WSL2 資源耗盡問題

同時運行以下服務會觸發 OOM：

  • Docker 服務群（PostgreSQL + MongoDB + Redis + Nakama）
  • Ollama（Qwen3-4B 佔 2.5GB VRAM）
  • 前端 dev server（Vite）
  • 背景 E2E 測試任務

exit code 144 是 Linux OOM killer 強制終止進程的典型信號（128 + signal 16 SIGTERM）。

UX 缺口診斷演進（v13 關鍵更新）

v12 狀態：已排除 (1) Nakama session 過期、(2) 輪詢邏輯缺失，下一步為靜態代碼路徑審查。

v13 新增診斷線索：用戶在前端頁面確認出現「正在為您撰寫章節...」訊息，這是關鍵縮小：

  • 生成流程**已觸發**（章節請求有發出、後端有接收）
  • UX 缺口**不在觸發端**，而在**結果渲染端**
  • 靜態追蹤重點縮小為：TaskResult 回傳後 → 前端如何更新 PixiJS canvas 顯示章節文字

Ollama / Qwen3-4B 安裝

# Ubuntu/WSL2 必須先裝 zstd，否則 install.sh 報錯
sudo apt-get install -y zstd
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3:4b  # 約 2.5 GB

顯卡需求：Qwen3-4B 約佔 2.5GB VRAM，用戶的 MSI 顯卡已確認可跑。

What Changed

v12 → v13 的關鍵演進：UX 缺口範圍縮小

v12 的診斷是「整個前端流程不通，需靜態審查調用鏈」。v13 用戶實測確認前端出現「正在為您撰寫章節...」訊息，這將問題範圍從「流程是否觸發」縮小到「結果是否渲染」。這是多版本迭代後第一次有具體的 UI 狀態作為診斷依據。

Nakama Session Token 警告確認

v13 用戶提供了瀏覽器 Console 截圖，確認出現 session token 生命週期過短的警告。這個問題在 v12 已記錄修復方案，但 v13 確認該警告在實際運行中確實存在，需要套用 docker-compose.yml 的環境變數修正。

WSL2 OOM 與 exit code 144 確認

背景 E2E 任務（Full E2E with backend destiny lock）以 exit code 144 失敗，同時用戶報告 CPU/記憶體被耗盡、筆電風扇大聲。這是 WSL2 OOM killer 介入的直接證據，與 v12 的預測完全吻合。用戶被迫手動停止所有後台工作。

So What

「正在為您撰寫章節...」是此系列第一個確切的 UX 狀態錨點

在六個版本的迭代中，每次都是「程式碼層面通過驗證 → 宣告修復 → 用戶測試否定」的循環。v13 首次有具體的 UI 字串作為診斷依據：生成有觸發，但結果文字未渲染到 canvas 上。這將靜態審查的範圍從整個調用鏈縮小到「TaskResult 取得後的 PixiJS 渲染邏輯」。

agent-browser 限制是 canvas 密集型專案的長期障礙

Claude 無法直接操作前端瀏覽器，這意味著每次 UX 驗收都必須依賴用戶手動測試。這個限制與 PixiJS canvas 無法被 DOM selector 查詢的特性疊加，形成了「AI 輔助開發的死角」。這是評估引擎遷移（PixiJS → Cocos TypeScript）的核心動機之一。

Trade-offs

  • Playwright CLI vs @playwright/test：CLI 提供 codegen 便利性，但對 canvas 應用無差異；維持現有 @playwright/test 即可
  • PixiJS（現有）vs Cocos TypeScript：PixiJS 生態成熟，但 AI agent 可見性差；Cocos 遷移成本高，但長期 AI 輔助開發效率更好
  • Go e2e build tag 隔離 vs 永遠跑：使用 //go:build e2e 讓一般 go test ./... 不觸發，CI 需要分開的 e2e stage
  • Vitest skip vs fail（Nakama 不可用）：skip 讓 CI 不紅燈，但可能遮蔽真正的連線問題
  • 後台任務 exit code 0 vs 實際 UX 驗收：exit code 0 只代表程式碼結構正確，不代表 UX 流程可用（v12/v13 實證）
  • WSL2 並行服務數量：Docker 服務群 + Ollama + E2E 測試並行可能觸發 OOM，建議分階段啟動並監控記憶體
  • Qwen3-4B（本地 SLM）vs LLM API：SLM 延遲低、成本低、可本地部署；LLM 創意更強但成本高

Try It Fast

# 1. Ubuntu/WSL2 安裝 Ollama（需先裝 zstd，這是 install.sh 的依賴）
sudo apt-get install -y zstd
curl -fsSL https://ollama.com/install.sh | sh

# 2. 拉取 Qwen3-4B 模型（約 2.5 GB）
ollama pull qwen3:4b

# 3. 測試武俠章節生成品質
ollama run qwen3:4b "你是武俠小說作家，請生成一段300字的修煉突破場景，主角靈根為金系，剛完成築基期突破。"

# 4. Nakama session 設定（docker-compose.yml 中加入，解決 token 過短警告）
# environment:
#   - NAKAMA_SESSION_TOKEN_EXPIRY_SEC=86400
#   - NAKAMA_SESSION_REFRESH_TOKEN_EXPIRY_SEC=604800

# 5. 啟動後端服務（先不開 Ollama，避免 OOM）
cd /mnt/d/projects/ui-translator/backend
chmod +x scripts/e2e-setup.sh scripts/e2e-teardown.sh
make e2e-up

# 6. 確認 Nakama 可達
curl -f http://localhost:7350/healthcheck && echo "Nakama OK"

# 7. v13 重點：追蹤 TaskResult 取得後的渲染邏輯（已知觸發端正常）
grep -r "TaskResult\|chapterContent\|renderChapter\|setText\|addChild" \
  /mnt/d/projects/ui-translator/frontend/src --include="*.ts" -l

# 8. 跑後端 Go e2e 測試（11 個案例）
go test -tags=e2e ./test/... -v

# 9. 前端 API integration tests
cd /mnt/d/projects/ui-translator/frontend
npm run test:e2e-api

# 10. 手動 UX 驗收（重點：確認「正在為您撰寫章節...」之後有沒有渲染出文字）
npm run dev
# DevTools Network 面板：鎖定命格後確認 RequestChapter → polling TaskResult 流程
# 觀察「正在為您撰寫章節...」訊息出現後，canvas 是否更新顯示章節內容

Recommendation

  1. 靜態追蹤渲染端（最優先，v13 縮小範圍）：已知「正在為您撰寫章節...」訊息出現，表示觸發端正常。追蹤 TaskResult 取得後 → PixiJS canvas 文字渲染的完整調用鏈，這是 v13 確認的精確診斷方向
  2. 修復 Nakama session token 設定：在 docker-compose.yml 加入 NAKAMA_SESSION_TOKEN_EXPIRY_SEC=86400 和 NAKAMA_SESSION_REFRESH_TOKEN_EXPIRY_SEC=604800，消除瀏覽器 Console 警告
  3. 分離資源管理：WSL2 記憶體有限，建議順序：(1) 啟動後端服務 (2) 確認 Nakama OK 後才啟動前端 (3) Ollama 在需要時才啟動，避免 OOM（exit code 144 已確認會發生）
  4. 手動 UX 驗收 checklist：制定每次功能完成必須手動驗收的 UX 流程清單（Claude 無法自主操作前端瀏覽器，這是架構限制，非暫時問題）
  5. 接入 Qwen3-4B 並評估小說品質：後端服務穩定後，設計固定格式 prompt template（風格、字數、靈根類型參數）
  6. CI/CD 整合：加入兩個 stage：(1) make e2e-up && go test -tags=e2e ./test/... && make e2e-down；(2) npm run test:e2e-api
  7. 評估引擎遷移時機：若 AI agent 輔助前端開發是長期目標，評估遷移至 Cocos TypeScript；MVP 階段可暫緩

本文檔由 Semi-Brain 自動生成

Session ID: 38030a5c-54da-4873-9a63-680709c843f1

分析信心度: 91%