OCR/TESTING.md

Tool_OCR Testing Guide

測試架構

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

---

後端測試

安裝測試依賴

cd backend
pip install pytest pytest-cov httpx

運行所有測試

# 運行所有測試
pytest

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

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

運行特定測試

# 僅運行單元測試
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 - 測試任務

---

測試範例

編寫新的單元測試

# 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

編寫新的集成測試

# 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 範例

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

範例配置

# 安裝測試依賴
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 正確設定

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