# 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