OCR/TESTING.md

# Tool_OCR Testing Guide

## 測試架構

本專案包含完整的測試套件，包括單元測試和集成測試。

---

## 後端測試

### 安裝測試依賴

```bash
cd backend
pip install pytest pytest-cov httpx
```

### 運行所有測試

```bash
# 運行所有測試
pytest

# 運行並顯示詳細輸出
pytest -v

# 運行並生成覆蓋率報告
pytest --cov=app --cov-report=html
```

### 運行特定測試

```bash
# 僅運行單元測試
pytest tests/test_auth.py
pytest tests/test_tasks.py
pytest tests/test_admin.py

# 僅運行集成測試
pytest tests/test_integration.py

# 運行特定測試類
pytest tests/test_tasks.py::TestTasks

# 運行特定測試方法
pytest tests/test_tasks.py::TestTasks::test_create_task
```

### 測試覆蓋

**單元測試** (`tests/test_*.py`):
- `test_auth.py` - 認證端點測試
  - 登入成功/失敗
  - Token 驗證
  - 登出功能
- `test_tasks.py` - 任務管理測試
  - 任務 CRUD 操作
  - 用戶隔離驗證
  - 統計數據
- `test_admin.py` - 管理員功能測試
  - 系統統計
  - 用戶列表
  - 審計日誌

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

---

## 測試資料庫

測試使用 SQLite 記憶體資料庫，每次測試後自動清理：
- 不影響開發或生產資料庫
- 快速執行
- 完全隔離

---

## Fixtures (測試夾具)

在 `conftest.py` 中定義：

- `db` - 測試資料庫 session
- `client` - FastAPI 測試客戶端
- `test_user` - 一般測試用戶
- `admin_user` - 管理員測試用戶
- `auth_token` - 測試用戶的認證 token
- `admin_token` - 管理員的認證 token
- `test_task` - 測試任務

---

## 測試範例

### 編寫新的單元測試

```python
# tests/test_my_feature.py

import pytest


class TestMyFeature:
    """Test my new feature"""

    def test_feature_works(self, client, auth_token):
        """Test that feature works correctly"""
        response = client.get(
            '/api/v2/my-endpoint',
            headers={'Authorization': f'Bearer {auth_token}'}
        )

        assert response.status_code == 200
        data = response.json()
        assert 'expected_field' in data
```

### 編寫新的集成測試

```python
# tests/test_integration.py

class TestIntegration:

    def test_complete_workflow(self, client, db):
        """Test complete user workflow"""
        # Step 1: Login
        # Step 2: Perform actions
        # Step 3: Verify results
        pass
```

---

## CI/CD 整合

### GitHub Actions 範例

```yaml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: 3.11

    - name: Install dependencies
      run: |
        cd backend
        pip install -r requirements.txt
        pip install pytest pytest-cov

    - name: Run tests
      run: |
        cd backend
        pytest --cov=app --cov-report=xml

    - name: Upload coverage
      uses: codecov/codecov-action@v2
```

---

## 前端測試 (未來計劃)

### 建議測試框架
- **單元測試**: Vitest
- **元件測試**: React Testing Library
- **E2E 測試**: Playwright

### 範例配置

```bash
# 安裝測試依賴
npm install --save-dev vitest @testing-library/react @testing-library/jest-dom

# 運行測試
npm test

# 運行 E2E 測試
npm run test:e2e
```

---

## 測試最佳實踐

### 1. 測試命名規範
- 使用描述性名稱: `test_user_can_create_task`
- 遵循 AAA 模式: Arrange, Act, Assert

### 2. 測試隔離
- 每個測試獨立執行
- 使用 fixtures 提供測試數據
- 不依賴其他測試的狀態

### 3. Mock 外部服務
- Mock 外部 API 呼叫
- Mock 檔案系統操作
- Mock 第三方服務

### 4. 測試覆蓋率目標
- 核心業務邏輯: >90%
- API 端點: >80%
- 工具函數: >70%

---

## 故障排除

### 常見問題

**問題**: `ImportError: cannot import name 'XXX'`
**解決**: 確保 PYTHONPATH 正確設定
```bash
export PYTHONPATH=$PYTHONPATH:$(pwd)
```

**問題**: 資料庫連接錯誤
**解決**: 測試使用記憶體資料庫，不需要實際資料庫連接

**問題**: Token 驗證失敗
**解決**: 檢查 JWT secret 設定，使用測試用 fixtures

---

## 測試報告

執行測試後生成的報告：

1. **終端輸出**: 測試結果概覽
2. **HTML 報告**: `htmlcov/index.html` (需要 --cov-report=html)
3. **覆蓋率報告**: 顯示未測試的代碼行

---

## 持續改進

- 定期運行測試套件
- 新功能必須包含測試
- 維護測試覆蓋率在 80% 以上
- Bug 修復時添加回歸測試

---

**最後更新**: 2025-11-16
**維護者**: Development Team