backend/test

測試架構說明

本目錄包含基於 k6 的負載測試架構，採用模組化設計，支援場景重複使用。

📁 目錄結構

test/
├── scenarios/           # 可重複使用的場景模組
│   ├── apis/           # API 層級場景（單一 API 端點）
│   └── e2e/            # 端到端業務流程場景
├── tests/              # 不同環境的測試配置
│   ├── smoke/          # 冒煙測試（Dev/QA 環境）
│   ├── pre/            # 預發布環境測試（負載/壓力測試）
│   └── prod/           # 生產環境測試（夜間監控）
├── Dockerfile          # Docker 映像定義
├── docker-compose.yml  # Docker Compose 配置
├── Makefile            # Make 命令文件
├── AI_GUIDE.md         # AI 助手指南（如何添加新 API）
└── README.md           # 本文件

🎯 設計原則

1. 模組化場景：每個 API 端點對應一個場景函數，可獨立使用
2. 可擴展預設行為：場景函數接受 options 參數，可覆蓋預設行為
3. 自定義指標可選：支援可選的自定義指標，不強制使用
4. 請求標籤與檢查：每個請求添加 tag，並檢查響應結果
5. 使用 Scenarios 設置工作負載：提供更大的靈活性
6. 避免多用途測試：每個測試文件專注於一個主要目的

🚀 快速開始

使用 Makefile（推薦）

最簡單的方式是使用 Makefile 提供的命令：

# 查看所有可用命令
make help

# 運行所有冒煙測試
make smoke

# 運行特定冒煙測試
make smoke-health
make smoke-auth
make smoke-user

# 運行負載測試
make load
make load-auth
make load-user

# 運行壓力測試
make stress
make stress-auth
make stress-user

# 運行生產環境測試（需要設置環境變數）
export BASE_URL=https://api.example.com
export TEST_LOGIN_ID=test@example.com
export TEST_PASSWORD=TestPassword123!
make nightly

# 運行指定的測試文件
make run TEST=tests/smoke/smoke-auth-test.js

# 運行測試並輸出結果
make run-with-output TEST=tests/smoke/smoke-auth-test.js OUTPUT=results.json

使用 Docker Compose

# 構建 Docker 映像
docker-compose build

# 運行測試（需要設置環境變數）
BASE_URL=https://api.example.com docker-compose run --rm k6 run tests/smoke/smoke-auth-test.js

直接使用 k6（需要本地安裝 k6）

# 設置環境變數
export BASE_URL=https://api.example.com
export TEST_LOGIN_ID=test@example.com
export TEST_PASSWORD=TestPassword123!

# 運行冒煙測試
k6 run tests/smoke/smoke-auth-test.js
k6 run tests/smoke/smoke-user-test.js
k6 run tests/smoke/smoke-health-test.js

# 運行負載測試
k6 run tests/pre/load-auth-test.js
k6 run tests/pre/stress-auth-test.js

# 運行生產環境測試
k6 run tests/prod/nightly-auth-test.js

環境變數設置

# 設置 API 基礎 URL（必需）
export BASE_URL=https://api.example.com

# 生產環境測試帳號（僅用於生產環境測試）
export TEST_LOGIN_ID=test@example.com
export TEST_PASSWORD=TestPassword123!

# 或在 Makefile 命令中直接指定
make smoke BASE_URL=https://api.example.com
make nightly BASE_URL=https://api.example.com TEST_LOGIN_ID=test@example.com TEST_PASSWORD=TestPassword123!

網絡配置說明

重要：如果 API 服務器在主機上運行（不在容器內），測試容器已經配置為使用主機網絡模式（--network host），可以直接訪問主機上的服務。

# 如果 API 在本地主機運行
export BASE_URL=http://localhost:8888
# 或
export BASE_URL=https://localhost:8888

# 如果 API 在其他地址運行
export BASE_URL=https://api.example.com

# 運行測試
make smoke-health

注意：

• 使用 --network host 模式時，容器直接使用主機網絡，可以訪問 localhost 和主機上的所有端口
• 如果 API 使用 HTTPS 但沒有有效證書，可能需要設置 K6_SKIP_TLS_VERIFY=true

📝 添加新 API 場景

請參考 AI_GUIDE.md 文件，其中包含詳細的步驟和模板。

快速步驟：

1. 在 scenarios/apis/ 創建場景模組
2. 在 scenarios/e2e/ 創建流程場景（如果需要）
3. 在 tests/smoke/ 創建冒煙測試
4. 在 tests/pre/ 創建負載/壓力測試
5. 在 tests/prod/ 創建夜間測試（如果適用）

📊 測試類型

環境	測試類型	目的	並發數	持續時間
Dev/QA	Smoke	快速驗證功能可用性	1	30s
Pre-release	Load	正常負載下的性能	10-20	5-10m
Pre-release	Stress	高負載下的穩定性	50-100	5-10m
Production	Nightly	監控生產環境穩定性	5	5-10m

🔗 相關資源

• k6 官方文檔
• AI_GUIDE.md - 詳細的 AI 助手指南