robot
da3cd5b2ed
CI Pipeline / backend-test (push) Failing after 12s
CI Pipeline / frontend-test (push) Successful in 34s
CI Pipeline / backend-lint (push) Successful in 9s
CI Pipeline / backend-test (pull_request) Failing after 14s
CI Pipeline / frontend-test (pull_request) Successful in 27s
CI Pipeline / backend-lint (pull_request) Successful in 8s
CI Pipeline / quality-gate (push) Successful in 2s
CI Pipeline / quality-gate (pull_request) Successful in 2s
- Remove .gitlab-ci.yml (duplicative with Gitea Actions workflow) - Add lookup_geo() unit tests with mocked MaxMind reader (4 tests) - Expand README.md Testing section with backend/frontend/CI docs - Add CLAUDE.md with test framework documentation
105 lines
2.5 KiB
Markdown
105 lines
2.5 KiB
Markdown
# CLAUDE.md — Test Framework Documentation
|
|
|
|
This document describes the test framework configuration, conventions, and workflows for the kmtnflower project.
|
|
|
|
## Overview
|
|
|
|
The project uses two test frameworks:
|
|
- **pytest** for the FastAPI backend (Python)
|
|
- **Vitest** for the Angular frontend (TypeScript)
|
|
|
|
## Backend Testing (pytest)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
cd backend
|
|
pip install -r requirements-test.txt
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
python -m pytest tests/ -v
|
|
|
|
# Run a single test file
|
|
python -m pytest tests/test_log_parser.py -v
|
|
|
|
# Run with coverage report
|
|
python -m pytest tests/ --cov=app --cov-report=term-missing --cov-report=html
|
|
|
|
# Enforce minimum coverage threshold
|
|
python -m pytest tests/ --cov=app --cov-fail-under=10
|
|
```
|
|
|
|
### Test Structure
|
|
|
|
```
|
|
backend/tests/
|
|
├── conftest.py # Shared fixtures
|
|
├── test_auth.py # Authentication & JWT tests
|
|
├── test_log_parser.py # Log parsing & geolocation tests
|
|
├── test_storage.py # Database operation tests
|
|
├── test_theme_export.py # Theme export tests
|
|
├── test_config.py # Configuration tests
|
|
└── test_models.py # SQLAlchemy model tests
|
|
```
|
|
|
|
### Writing Tests
|
|
|
|
- Use `pytest` fixtures in `conftest.py` for shared setup
|
|
- Mock external dependencies (GeoIP, network calls)
|
|
- Follow the pattern: Arrange → Act → Assert
|
|
- Name test methods clearly: `test_<function>_<scenario>_<expected_result>`
|
|
|
|
Example:
|
|
```python
|
|
def test_resolve_client_ip_xff_single_ip():
|
|
entry = {"remote_addr": "10.0.0.1", "x_forwarded_for": "203.0.113.50"}
|
|
assert resolve_client_ip(entry) == "203.0.113.50"
|
|
```
|
|
|
|
## Frontend Testing (Vitest)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
npm install --save-dev vitest @vitest/coverage-v8 jsdom
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
npx vitest run
|
|
|
|
# Watch mode
|
|
npx vitest
|
|
|
|
# With coverage
|
|
npx vitest run --coverage
|
|
```
|
|
|
|
### Configuration
|
|
|
|
The Vitest config is in `vitest.config.ts` at the project root.
|
|
|
|
## CI/CD Integration
|
|
|
|
The Gitea Actions workflow (`.gitea/workflows/ci.yaml`) runs:
|
|
1. `backend-test` — pytest with coverage enforcement
|
|
2. `frontend-test` — Vitest unit tests
|
|
3. `backend-lint` — ruff linting
|
|
4. `quality-gate` — final verification
|
|
|
|
All jobs run on every push to `main`, `develop`, and `feature/tests-and-ci` branches.
|
|
|
|
## Best Practices
|
|
|
|
- Tests should be deterministic and isolated
|
|
- Mock external dependencies (GeoIP DB, network, file system)
|
|
- Use fixtures for repeated setup code
|
|
- Keep tests fast — avoid slow operations in test suites
|
|
- Document test coverage in commit messages when adding new tests
|