# 運行測試指南

## ⚠️ 測試狀態

我已經創建了完整的測試套件，但**尚未在您的環境中運行測試**，因為需要安裝額外的依賴。

---

## 📋 已創建的測試文件

### 測試文件
- ✅ `tests/conftest_v2.py` - V2 測試配置和 fixtures
- ✅ `tests/test_auth.py` - 認證端點測試（6個測試）
- ✅ `tests/test_tasks.py` - 任務管理測試（7個測試）
- ✅ `tests/test_admin.py` - 管理員功能測試（4個測試）
- ✅ `tests/test_integration.py` - 集成測試（3個測試）

### 配置文件
- ✅ `pytest.ini` - Pytest 配置
- ✅ `TESTING.md` - 測試文檔

**總計**: 20 個測試用例

---

## 🚀 如何運行測試

### 方式 1: 使用虛擬環境（推薦）

```bash
cd backend

# 創建虛擬環境
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安裝所有依賴
pip install -r requirements.txt  # 如果有
pip install pytest pytest-cov httpx

# 運行測試
pytest tests/test_auth.py -v
pytest tests/test_tasks.py -v
pytest tests/test_admin.py -v
pytest tests/test_integration.py -v

# 運行所有測試並生成覆蓋率報告
pytest tests/test_*.py --cov=app --cov-report=html
```

### 方式 2: 使用 Conda 環境

```bash
# 激活 conda 環境
conda activate tool_ocr

# 安裝測試依賴
pip install pytest pytest-cov httpx

# 運行測試
pytest tests/test_auth.py -v
```

### 方式 3: 使用系統 Python（需要 --break-system-packages）

```bash
# 安裝依賴（不推薦）
python3 -m pip install pytest httpx --break-system-packages

# 運行測試
python3 -m pytest tests/test_auth.py -v
```

---

## 📦 必需的依賴

測試需要以下依賴（大部分應該已安裝）：

```
# 核心依賴
fastapi
sqlalchemy
pydantic
pydantic-settings
python-jose[cryptography]
passlib[bcrypt]
pymysql
python-multipart

# 測試依賴
pytest
pytest-cov
httpx
```

---

## 🧪 測試範例輸出（預期）

```bash
$ pytest tests/test_auth.py -v

tests/test_auth.py::TestAuth::test_login_success PASSED           [ 16%]
tests/test_auth.py::TestAuth::test_login_invalid_credentials PASSED [ 33%]
tests/test_auth.py::TestAuth::test_get_me PASSED                  [ 50%]
tests/test_auth.py::TestAuth::test_get_me_unauthorized PASSED     [ 66%]
tests/test_auth.py::TestAuth::test_logout PASSED                  [ 83%]

======================== 5 passed in 0.45s ==========================
```

---

## ⚙️ 測試配置

### pytest.ini
```ini
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts =
    -v
    --strict-markers
    --tb=short
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow running tests
```

### 測試數據庫
- 測試使用 **SQLite 記憶體資料庫** `:memory:`
- 每個測試獨立，不影響生產資料庫
- 測試後自動清理

---

## 🔧 常見問題

### 問題 1: ModuleNotFoundError: No module named 'pytest'
**解決**:
```bash
pip install pytest
```

### 問題 2: ModuleNotFoundError: No module named 'app'
**解決**: 確保在 backend 目錄中運行測試
```bash
cd /home/egg/project/Tool_OCR/backend
pytest
```

### 問題 3: externally-managed-environment
**解決**: 使用虛擬環境或 --break-system-packages（不推薦）

### 問題 4: conftest.py 衝突
**解決**:
- 舊的 V1 測試使用 `conftest_old.py`
- 新的 V2 測試需要重命名為 `conftest_v2.py`
- 或者合併兩個配置文件

---

## 📊 測試覆蓋範圍

### 認證測試 (test_auth.py)
- ✅ 登入成功
- ✅ 登入失敗（錯誤憑證）
- ✅ 獲取當前用戶資訊
- ✅ 未授權訪問
- ✅ 登出功能
- ✅ Mock 外部認證服務

### 任務測試 (test_tasks.py)
- ✅ 創建任務
- ✅ 列出任務
- ✅ 獲取單個任務
- ✅ 獲取統計數據
- ✅ 刪除任務
- ✅ 用戶隔離驗證

### 管理員測試 (test_admin.py)
- ✅ 系統統計
- ✅ 用戶列表
- ✅ 審計日誌
- ✅ 非管理員訪問控制

### 集成測試 (test_integration.py)
- ✅ 完整認證和任務流程
- ✅ 管理員工作流程
- ✅ 任務生命週期

---

## ✅ 下一步行動

1. **安裝依賴**:
   ```bash
   cd backend
   source venv/bin/activate  # 或創建新的 venv
   pip install pytest pytest-cov httpx
   ```

2. **運行測試**:
   ```bash
   pytest tests/test_auth.py -v
   ```

3. **查看結果**:
   - 綠色 ✓ = 通過
   - 紅色 ✗ = 失敗
   - 黃色 ! = 警告

4. **生成覆蓋率報告**:
   ```bash
   pytest --cov=app --cov-report=html
   open htmlcov/index.html  # 查看報告
   ```

---

## 📝 注意事項

1. **測試未運行**: 由於依賴缺失，我無法在當前環境中執行測試
2. **代碼完整**: 測試代碼是完整的，只需安裝依賴即可運行
3. **Mock 服務**: 外部認證 API 已 Mock，不需要實際連接
4. **資料庫隔離**: 使用記憶體資料庫，安全且快速

---

**創建日期**: 2025-11-16
**狀態**: 已創建但未運行
**待辦**: 安裝依賴並執行測試驗證