feat: add admin dashboard, audit logs, token expiry check and test suite
Frontend Features: - Add ProtectedRoute component with token expiry validation - Create AdminDashboardPage with system statistics and user management - Create AuditLogsPage with filtering and pagination - Add admin-only navigation (Shield icon) for ymirliu@panjit.com.tw - Add admin API methods to apiV2 service - Add admin type definitions (SystemStats, AuditLog, etc.) Token Management: - Auto-redirect to login on token expiry - Check authentication on route change - Show loading state during auth check - Admin privilege verification Backend Testing: - Add pytest configuration (pytest.ini) - Create test fixtures (conftest.py) - Add unit tests for auth, tasks, and admin endpoints - Add integration tests for complete workflows - Test user isolation and admin access control Documentation: - Add TESTING.md with comprehensive testing guide - Include test running instructions - Document fixtures and best practices Routes: - /admin - Admin dashboard (admin only) - /admin/audit-logs - Audit logs viewer (admin only) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
258
TESTING.md
Normal file
258
TESTING.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user