10 KiB
10 KiB
Gateway E2E 測試指南
本文件列出 所有 HTTP API 測試情境 與 一鍵跑完整 E2E 的方式。自動化測試程式在 test/e2e/（build tag: e2e）。
一鍵完整測試（推薦）
從 全新 Docker volume 開始，依序：起 Mongo/Redis → 建 index → seed 資料 → 起 Gateway → 跑 E2E → 關閉並刪除 volume。
cd gateway
make e2e-full
等同於：
bash scripts/e2e-run.sh
成功時最後一行：>> E2E OK
流程圖
flowchart LR
A[docker compose down -v] --> B[up mongo + redis]
B --> C[cmd/mongo-index]
C --> D[cmd/e2e-seed]
D --> E[gateway :18888]
E --> F[go test -tags=e2e]
F --> G[stop gateway + down -v]
其他指令
| 指令 | 用途 |
|---|---|
make e2e-up |
起環境 + seed + Gateway，不跑測試（本機除錯） |
make test-e2e |
對已啟動的 Gateway 跑 E2E（需先有 state.json） |
make e2e-casbin |
以 Permission.Casbin.Enabled: true 跑 RBAC reload / deny E2E |
make e2e-down |
停 Gateway + docker compose down -v |
E2E_KEEP_DOCKER=1 make e2e-full |
測完保留 Docker（方便查 Mongo/Redis） |
E2E 專用設定
| 檔案 | 說明 |
|---|---|
test/e2e/fixtures/e2e.yaml |
Port 18888、DB gateway_e2e、Notification mock、Casbin 關閉 |
test/e2e/fixtures/e2e.casbin.yaml |
同上，但 Casbin 開啟，搭配 make e2e-casbin |
test/e2e/fixtures/state.json |
seed 產生的 tenant / uid / JWT（gitignore，執行後生成） |
測試覆蓋矩陣（一目瞭然）
圖例：✅ 自動 E2E · ⏭ 需 ZITADEL / 手動 · 🔧 基礎設施
基礎設施
| ID | 情境 | 自動 | 測試檔 |
|---|---|---|---|
| INF-01 | Mongo + Redis docker healthy | ✅ | scripts/e2e-run.sh |
| INF-02 | 全模組 Mongo index | ✅ | cmd/mongo-index |
| INF-03 | E2E tenant + member + permission + JWT seed | ✅ | cmd/e2e-seed |
| INF-04 | Gateway 監聽 :18888 | ✅ | scripts/e2e-run.sh |
Normal
| ID | Method | Path | 情境 | 自動 | 測試 |
|---|---|---|---|---|---|
| N-01 | GET | /api/v1/health |
Ping 200 | ✅ | TestHealth_Ping |
| N-02 | GET | /api/v1/health |
無需 Bearer | ✅ | TestHealth_NoAuthRequired |
Auth（/api/v1/auth）
| ID | Method | Path | 情境 | 自動 | 測試 / 備註 |
|---|---|---|---|---|---|
| A-01 | POST | /register |
Email 註冊 | ⏭ | 需 ZITADEL + invite |
| A-02 | POST | /register/confirm |
OTP 確認 | ⏭ | 同上 |
| A-03 | POST | /register/resend |
重發 OTP | ⏭ | 同上 |
| A-04 | POST | /register/social/start |
社交註冊 | ⏭ | 需 ZITADEL OAuth |
| A-05 | GET | /register/social/callback |
社交註冊 callback | ⏭ | 需 ZITADEL |
| A-06 | POST | /login |
密碼登入 | ⏭ | 需 ZITADEL ROPG |
| A-07 | POST | /login/social/start |
社交登入 | ⏭ | 需 ZITADEL |
| A-08 | GET | /login/social/callback |
社交登入 callback | ⏭ | 需 ZITADEL |
| A-09 | POST | /token/exchange |
id_token 換 JWT | ⏭ | 需 ZITADEL |
| A-10 | POST | /token/refresh |
刷新 token | ✅ | TestZZZ_AuthTokenRefreshAndLogout（最後跑） |
| A-11 | POST | /logout |
登出黑名單 jti | ✅ | 同上（同一測試內連續驗證） |
| A-12 | GET | /members/me（無 Bearer） |
401 | ✅ | TestAuth_MissingBearer_401 |
| A-13 | POST | /register、/login、/token/refresh、/login/social/start |
公開 Auth validation 400 | ✅ | TestAuth_PublicValidationErrors（不需 ZITADEL） |
E2E 透過
cmd/e2e-seed直接核發 JWT，不走 ZITADEL，因此 A-01～A-09 列為手動／staging 測試。
Member（/api/v1/members，需 Bearer）
| ID | Method | Path | 情境 | 自動 | 測試 |
|---|---|---|---|---|---|
| M-01 | GET | /me |
讀 profile | ✅ | TestMember_GetMe |
| M-02 | PATCH | /me |
更新 display_name | ✅ | TestMember_UpdateMe |
| M-03 | POST | /me/verifications/email/start |
發起 email OTP | ✅ | TestMember_EmailVerification_FullFlow |
| M-04 | POST | /me/verifications/email/confirm |
確認 email OTP | ✅ | 同上（GATEWAY_E2E=1 從 Redis 取碼） |
| M-05 | POST | /me/verifications/phone/start |
發起 phone OTP | ✅ | TestMember_PhoneVerification_FullFlow |
| M-06 | POST | /me/verifications/phone/confirm |
確認 phone OTP | ✅ | 同上（GATEWAY_E2E=1 從 Redis 取碼） |
| M-07 | GET | /me/totp |
TOTP 狀態 | ✅ | TestMember_TOTP_Status |
| M-08 | POST | /me/totp/enroll-start |
開始綁定 | ✅ | TestMember_TOTP_FullFlow（解析 otpauth_url） |
| M-09 | POST | /me/totp/enroll-confirm |
確認綁定 | ✅ | 同上 |
| M-10 | POST | /me/totp/verify |
Step-up 驗碼 + replay 防護 | ✅ | 同上 |
| M-11 | DELETE | /me/totp |
解除綁定 | ✅ | 同上 |
| M-12 | POST | /me/totp/backup-codes |
重產備援碼 | ✅ | 同上 |
Permission（/api/v1/permissions，需 Bearer）
| ID | Method | Path | Middleware | 情境 | 自動 | 測試 |
|---|---|---|---|---|---|---|
| P-01 | GET | /catalog |
AuthJWT | 權限樹 | ✅ | TestPermission_Catalog |
| P-02 | GET | /me |
AuthJWT | 當前 user 權限 | ✅ | TestPermission_Me |
| P-03 | GET | /roles |
AuthJWT+Casbin* | 列角色 | ✅ | TestPermission_RoleCRUD |
| P-04 | POST | /roles |
AuthJWT+Casbin* | 建角色 | ✅ | 同上 |
| P-05 | PATCH | /roles/:id |
AuthJWT+Casbin* | 更新角色 | ✅ | 同上 |
| P-06 | DELETE | /roles/:id |
AuthJWT+Casbin* | 刪角色 | ✅ | 同上 |
| P-07 | GET | /roles/:id/permissions |
AuthJWT+Casbin* | 讀角色權限 | ✅ | TestPermission_RolePermissions |
| P-08 | PUT | /roles/:id/permissions |
AuthJWT+Casbin* | 取代角色權限 | ✅ | 同上 |
| P-09 | GET | /users/:uid/roles |
AuthJWT+Casbin* | 列 user 角色 | ✅ | TestPermission_AssignUserRole |
| P-10 | POST | /users/:uid/roles |
AuthJWT+Casbin* | 指派角色 | ✅ | 同上 |
| P-11 | DELETE | /users/:uid/roles/:role_id |
AuthJWT+Casbin* | 撤銷角色 | ✅ | 同上 |
| P-12 | GET/PUT/DELETE | /role-mappings |
AuthJWT+Casbin* | 外部映射 CRUD | ✅ | TestPermission_RoleMappingCRUD |
| P-13 | POST | /policy/reload |
AuthJWT+Casbin | 重載 policy | ✅ | TestPermission_CasbinRBAC（make e2e-casbin） |
| P-14 | GET | /roles |
AuthJWT+Casbin | no-role user RBAC denied 403 | ✅ | 同上 |
* 預設 make e2e-full 使用 Permission.Casbin.Enabled: false，Casbin middleware 放行（rbac=nil passthrough）。make e2e-casbin 會改用 e2e.casbin.yaml，並額外驗證 policy reload 與 no-role 403。
Notification（無 HTTP API）
| ID | 情境 | 自動 | 備註 |
|---|---|---|---|
| NT-01 | 同步 Send（mock email） | 🔧 | make notify-test METHOD=email-send MOCK=1 |
| NT-02 | 異步 Enqueue + Worker | 🔧 | make notify-test METHOD=email-enqueue MOCK=1 |
| NT-03 | Member email OTP 寄送 | ✅ | 含在 M-03/M-04（mock provider） |
統計摘要
| 類別 | 自動 E2E | 待擴充 / 手動 |
|---|---|---|
| Normal | 2 | 0 |
| Auth | 4 | 9（ZITADEL） |
| Member | 12 | 0 |
| Permission | 14 | 0 |
| 合計 | 32 | 9 |
Auth refresh/logout 會撤銷 JWT，因此腳本分兩輪跑：
member/permission先用 seed token，最後才跑TestZZZ_AuthTokenRefreshAndLogout。
手動 / 延伸測試
Auth 全链路（需 ZITADEL）
- 設定
etc/gateway.dev.yaml的Zitadel.* make deps-up && make run-dev- 依
docs/auth-unified-registration.md跑 register → confirm → login
TOTP 互動測試
make deps-up
make totp-test STEP=flow
Notification
見 docs/notification-testing.md。
環境變數
| 變數 | 預設 | 說明 |
|---|---|---|
GATEWAY_E2E |
1（腳本內） |
開啟 OTP 寫入 Redis e2e:otp:{challenge_id} |
E2E_STATE_FILE |
test/e2e/fixtures/state.json |
seed 輸出路徑 |
E2E_BASE_URL |
http://127.0.0.1:18888 |
覆寫 Gateway URL |
E2E_KEEP_DOCKER |
— | 1 = 測完不 down -v |
GATEWAY_PORT |
18888 |
health check 用 |
E2E_ROLE |
tenant_owner |
覆寫 seed 指派給主測試使用者的 system role |
E2E_TEST_PATTERN |
Test(Auth_|Health|Member|Permission) |
覆寫第一輪 go test -run pattern |
E2E_CASBIN |
— | 1 = 執行 Casbin 專用 assertion（make e2e-casbin 已設定） |
目錄結構
gateway/
├── cmd/e2e-seed/ # E2E 資料 + JWT seed
├── scripts/
│ ├── e2e-run.sh # 一鍵完整流程
│ ├── e2e-up.sh # 只起環境
│ └── e2e-down.sh # 關閉
├── test/e2e/
│ ├── fixtures/
│ │ ├── e2e.yaml # E2E 設定
│ │ ├── e2e.casbin.yaml # Casbin enabled E2E 設定
│ │ └── state.json # 生成（gitignore）
│ ├── client.go # HTTP helper
│ ├── health_test.go
│ ├── auth_test.go
│ ├── member_test.go
│ └── permission_test.go
└── docs/e2e-testing.md # 本文件
CI 建議
# 範例 GitHub Actions job
- name: E2E
run: make e2e-full
working-directory: gateway
- name: E2E Casbin
run: make e2e-casbin
working-directory: gateway
PR 門檻：make check（unit）+ make e2e-full（整合）+ make e2e-casbin（RBAC enforcement）。
常見問題
Q: missing e2e otp for challenge
A: Gateway 必須以 GATEWAY_E2E=1 啟動（e2e-run.sh 已設定）。
Q: connection refused :18888
A: 先 make e2e-up 或確認沒有其他 process 佔用 18888。
Q: 跑完 make e2e-full 後 Gateway 還在 :18888？
A: 舊版用 go run 背景跑，kill $! 只殺 wrapper、子行程會留著。現已改為編譯 .cache/e2e-gateway 再啟動，cleanup 會依 pid 檔 + port + orphan 三層關閉。若仍有殘留：
make e2e-down
# 或
lsof -ti tcp:18888 | xargs kill -9
Q: 與 make run-dev（:8888）衝突？
A: E2E 固定用 18888 + gateway_e2e DB，互不影響。
Q: 如何只跑單一測試？
make e2e-up
GATEWAY_E2E=1 go test -tags=e2e -v -count=1 ./test/e2e/ -run TestMember_GetMe
make e2e-down