backend/test/doc/TEST_RESULTS_GUIDE.md

# 測試結果解讀指南

## 📊 如何解讀測試結果

### ✅ 成功的測試結果特徵

1. **所有檢查通過**：`checks_succeeded: 100%`
2. **請求成功**：`http_req_failed: 0%`
3. **閾值通過**：所有閾值顯示 `✓`
4. **響應時間正常**：在預期的時間範圍內

### ❌ 失敗的測試結果特徵

1. **連接錯誤**：`connection refused`、`timeout`、`no route to host`
2. **HTTP 錯誤**：`http_req_failed > 0%`
3. **檢查失敗**：`checks_succeeded < 100%`
4. **閾值失敗**：閾值顯示 `✗`

## 🔍 常見錯誤及解決方案

### 錯誤 1: Connection Refused

**錯誤信息：**
```
dial tcp 127.0.0.1:8888: connect: connection refused
```

**原因：**
- API 服務器沒有運行
- BASE_URL 設置錯誤
- 服務器運行在不同的端口或地址

**解決方案：**

```bash
# 1. 檢查 API 服務器是否運行
curl https://api.example.com/api/v1/health

# 2. 設置正確的 BASE_URL
export BASE_URL=https://api.example.com
make smoke-health

# 或直接在命令中指定
make smoke-health BASE_URL=https://api.example.com
```

### 錯誤 2: Timeout

**錯誤信息：**
```
context deadline exceeded
```

**原因：**
- 服務器響應太慢
- 網絡問題
- 服務器過載

**解決方案：**

```bash
# 1. 檢查服務器響應時間
curl -w "@-" -o /dev/null -s https://api.example.com/api/v1/health <<'EOF'
     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n
EOF

# 2. 調整測試的閾值（如果需要）
# 編輯測試文件，增加響應時間閾值
```

### 錯誤 3: HTTP 4xx/5xx 錯誤

**錯誤信息：**
```
http_req_failed: 20.00% (4xx/5xx responses)
```

**原因：**
- API 端點不存在
- 認證失敗
- 服務器內部錯誤

**解決方案：**

```bash
# 1. 檢查 API 端點是否正確
curl -v https://api.example.com/api/v1/health

# 2. 檢查認證（如果需要）
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/api/v1/health

# 3. 查看服務器日誌
# 檢查應用程序的日誌文件
```

### 錯誤 4: 閾值失敗

**錯誤信息：**
```
✗ 'rate==1.0' rate=95.00%
```

**原因：**
- 部分請求失敗
- 部分檢查未通過
- 性能未達標

**解決方案：**

```bash
# 1. 查看詳細的失敗原因
# 檢查輸出中的具體錯誤信息

# 2. 調整閾值（如果合理）
# 編輯測試文件，調整閾值要求
# 例如：從 'rate==1.0' 改為 'rate>0.95'

# 3. 修復根本問題
# 如果是服務器問題，需要修復服務器
```

## 📈 測試結果指標說明

### HTTP 指標

- **http_reqs**: 總請求數
- **http_req_duration**: 請求持續時間
  - `avg`: 平均時間
  - `min`: 最短時間
  - `max`: 最長時間
  - `p(90)`: 90% 的請求在此時間內完成
  - `p(95)`: 95% 的請求在此時間內完成
- **http_req_failed**: 失敗的請求百分比

### 檢查指標

- **checks_total**: 總檢查數
- **checks_succeeded**: 成功的檢查數
- **checks_failed**: 失敗的檢查數

### 執行指標

- **iterations**: 迭代次數
- **iteration_duration**: 每次迭代的持續時間
- **vus**: 虛擬用戶數

### 網絡指標

- **data_received**: 接收的數據量
- **data_sent**: 發送的數據量

## 🎯 閾值說明

閾值（Thresholds）是測試的通過標準：

- **`rate==1.0`**: 100% 必須通過
- **`rate>0.95`**: 至少 95% 必須通過
- **`p(95)<2000`**: 95% 的請求必須在 2000ms 內完成
- **`rate<0.05`**: 失敗率必須低於 5%

## 💡 最佳實踐

1. **先運行健康檢查**：確保服務器可用
   ```bash
   make smoke-health BASE_URL=https://api.example.com
   ```

2. **逐步增加負載**：從冒煙測試開始，然後負載測試，最後壓力測試

3. **監控關鍵指標**：
   - 響應時間
   - 錯誤率
   - 吞吐量

4. **設置合理的閾值**：
   - 開發環境：較寬鬆的閾值
   - 生產環境：嚴格的閾值

5. **保存測試結果**：
   ```bash
   make run-with-output TEST=tests/smoke/smoke-health-test.js OUTPUT=results.json
   ```

## 🔧 調試技巧

### 1. 使用詳細輸出

```bash
# 查看詳細的請求信息
k6 run --http-debug tests/smoke/smoke-health-test.js
```

### 2. 檢查網絡連接

```bash
# 測試連接
curl -v https://api.example.com/api/v1/health

# 檢查 DNS
nslookup api.example.com

# 檢查端口
telnet api.example.com 443
```

### 3. 查看 Docker 日誌

```bash
# 如果使用 Docker，查看容器日誌
docker logs k6-test
```

### 4. 本地測試

```bash
# 如果本地安裝了 k6，可以直接運行
export BASE_URL=https://api.example.com
k6 run tests/smoke/smoke-health-test.js
```

## 📝 示例：解讀你的測試結果

### 你的測試結果分析

```
✗ checks: rate==1.0 (實際: 50.00%)
  - 10 個檢查中，5 個通過，5 個失敗
  - 狀態碼檢查：0% 通過（因為連接失敗）
  - 響應時間檢查：100% 通過（沒有實際請求）

✗ health_check_success: rate==1.0 (實際: 0.00%)
  - 所有健康檢查都失敗了

✓ http_req_duration: p(95)<500 (實際: 0s)
  - 沒有實際請求，所以響應時間為 0

http_req_failed: 100.00% (5 out of 5)
  - 所有請求都失敗了
```

### 解決方案

```bash
# 1. 確認 API 服務器地址
# 例如：https://dev-api.example.com 或 https://localhost:8888

# 2. 設置 BASE_URL
export BASE_URL=https://dev-api.example.com

# 3. 重新運行測試
make smoke-health

# 或如果服務器在本地運行
export BASE_URL=http://localhost:8888
make smoke-health
```