kmtnflower/CLAUDE.md

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

cd backend
pip install -r requirements-test.txt

Running Tests

# 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:

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

npm install --save-dev vitest @vitest/coverage-v8 jsdom

Running Tests

# 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