# 測試架構說明

本目錄包含基於 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 提供的命令：

```bash
# 查看所有可用命令
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

```bash
# 構建 Docker 映像
docker-compose build

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

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

```bash
# 設置環境變數
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
```

### 環境變數設置

```bash
# 設置 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`），可以直接訪問主機上的服務。

```bash
# 如果 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 官方文檔](https://k6.io/docs/)
- [AI_GUIDE.md](./AI_GUIDE.md) - 詳細的 AI 助手指南