🧪 Test Walkthrough

This section guides you through the LibreFolio test suite. Understanding the tests is one of the best ways to understand the codebase.

🚀 Running Tests

All tests are executed through dev.py:

# Run everything
./dev.py test all

# Run a single category
./dev.py test api all

# Run a specific test file
./dev.py test api test_auth_api

# List available tests (without running them)
./dev.py test api --list

🌐 Global Flags

Flag	Description
--verbose / -v	Show full pytest output
--coverage	Run with code coverage tracking
--cov-clean	Clean coverage database before run
--db-reset	Reset test database before DB tests

🖥️ Frontend Flags

Frontend test categories support additional flags (--headed, --debug, --ui). See the Frontend Tests Overview for details.

---

📋 Test Categories

LibreFolio organizes tests into 10 categories, grouped by layer:

Category	Command	What It Tests
External	./dev.py test external all	Provider integrations (FX, assets, BRIM) — no server needed
Database	./dev.py test db all	SQLite schema, migrations, CRUD — no server needed
Services	./dev.py test services all	Business logic in the service layer
Utils	./dev.py test utils all	Helper functions and utility modules
Schemas	./dev.py test schemas all	Pydantic model validation
API	./dev.py test api all	FastAPI endpoints (auto-starts server)
E2E	./dev.py test e2e all	Backend end-to-end with API interaction
Front-Utility	./dev.py test front-utility all	Auth, settings, files, select, image-crop (Playwright)
Front-User	./dev.py test front-user all	Brokers, multi-user, sharing (Playwright)
Front-FX	./dev.py test front-fx all	FX list, detail, add-pair, editor, sync (Playwright)

---

🏗️ Architecture Overview

graph TD
    ALL["./dev.py test all"]

    ALL --> BACKEND["Backend Tests"]
    ALL --> FRONTEND["Frontend Tests (Playwright)"]

    BACKEND --> EXT["External<br/><small>Provider integrations</small>"]
    BACKEND --> DB["Database<br/><small>Schema, CRUD</small>"]
    BACKEND --> SVC["Services<br/><small>Business logic</small>"]
    BACKEND --> UTL["Utils<br/><small>Helper functions</small>"]
    BACKEND --> SCH["Schemas<br/><small>Pydantic validation</small>"]
    BACKEND --> API["API<br/><small>FastAPI endpoints</small>"]
    BACKEND --> E2E["E2E<br/><small>API integration</small>"]

    FRONTEND --> FU["Front-Utility<br/><small>Auth, settings, files,<br/>select, image-crop</small>"]
    FRONTEND --> FUSR["Front-User<br/><small>Brokers, multi-user,<br/>sharing</small>"]
    FRONTEND --> FFX["Front-FX<br/><small>FX list, detail,<br/>add-pair, editor, sync</small>"]

---

📑 Category Details

🔧 Backend Categories

• External — Tests that call real external APIs (FX providers, asset providers, BRIM parsers). Run without the backend server.
• Database — Tests the database layer directly (schema validation, persistence, migrations). Uses an isolated test SQLite file.
• Services — Tests the service layer business logic, often with mocked dependencies.
• Utils — Tests utility modules and helper functions.
• Schemas — Tests Pydantic model validation, serialization, and edge cases.
• API — Integration tests for FastAPI endpoints. Automatically starts a test server if needed.
• E2E — End-to-end backend tests with real API interaction and database state.

🎭 Frontend Categories (Playwright)

• Front-Utility — Tests UI components: authentication flow, settings tabs, file upload, search selects, image cropping.
• Front-User — Tests user-facing features: broker CRUD, multi-user scenarios, broker sharing with RBAC.
• Front-FX — Tests the FX module: pair list, detail chart, add-pair modal, data editor, sync, and FX-specific API calls.

Frontend tests require a running server

Frontend categories automatically start both the backend server and serve the frontend build. Use --headed to watch the browser in action.

---

📊 Coverage

Generate a code coverage report:

./dev.py test all --coverage

This generates an HTML report in htmlcov/index.html showing which lines of code are covered by tests.