Testing Guide¶

# Run all tests
pytest

# Run with coverage report
pytest --cov=file_organizer --cov-report=html

# Fast smoke tests (pre-commit validation, matches actual gate)
pytest tests/ -m "smoke" -q --strict-markers --timeout=30 --override-ini="addopts="

# Run specific module tests
pytest tests/services/ -v

tests/
├── api/              # FastAPI routes, middleware, models (100+ tests)
├── cli/              # CLI commands (65+ tests)
├── services/         # Business logic (300+ tests)
├── tui/              # Terminal UI (50+ tests)
├── web/              # Web routes and templates (40+ tests)
├── models/           # Data models (40+ tests)
├── config/           # Configuration (30+ tests)
├── integration/      # Cross-module workflows (130+ tests)
└── ci/               # CI/workflow validation (20+ tests)

@pytest.mark.unit          # Unit tests (isolated, fast)
@pytest.mark.smoke         # Critical path tests (< 30s total, pre-commit validation)
@pytest.mark.integration   # Integration tests (cross-module workflows)
@pytest.mark.e2e           # End-to-end tests (full user journeys)
@pytest.mark.asyncio       # Async tests (FastAPI, TUI, services)
@pytest.mark.benchmark     # Performance tests
@pytest.mark.ci            # CI-specific tests
@pytest.mark.slow          # Long-running tests (>5s)
@pytest.mark.regression    # Regression tests (full suite only)

# Only smoke tests (fast pre-commit validation - full gate)
pytest tests/ -m "smoke" -q --strict-markers --timeout=30 --override-ini="addopts="

# All unit tests
pytest -m unit

# Integration + E2E tests
pytest -m "integration or e2e"

# Exclude slow tests
pytest -m "not slow"

# CI gate tests only
pytest -m ci

# Per-module coverage
pytest --cov=file_organizer.api --cov-report=term-missing

# Full project coverage with HTML report
pytest --cov=file_organizer --cov-report=html
# Open htmlcov/index.html to view

# Docstring coverage (requires interrogate)
interrogate -v src/file_organizer --fail-under 95

import pytest
from httpx import ASGITransport, AsyncClient, Client
from file_organizer.api.main import create_app

@pytest.fixture
async def client():
    app = create_app()
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        yield ac

# Or for synchronous use:
@pytest.fixture
def sync_client():
    app = create_app()
    transport = ASGITransport(app=app)
    with Client(transport=transport, base_url="http://test") as c:
        yield c

@pytest.mark.asyncio
async def test_organize_endpoint(client):
    response = await client.post("/api/organize", json={"path": "/tmp"})
    assert response.status_code == 200
    assert "organized" in response.json()

from pathlib import Path
from file_organizer.services.text_processor import TextProcessor

def test_text_processor(tmp_path):
    processor = TextProcessor()
    # Create test file
    test_file = tmp_path / "test.txt"
    test_file.write_text("Sample content for testing")

    result = processor.process_file(test_file)
    assert result is not None
    assert "test" in str(result).lower() or len(result) > 0

from typer.testing import CliRunner
from file_organizer.cli.main import app

runner = CliRunner()

def test_organize_command():
    result = runner.invoke(app, ["organize", "/tmp/files"])
    assert result.exit_code == 0
    assert "organized" in result.output

import pytest
from file_organizer.tui.app import FileOrganizerApp

@pytest.mark.asyncio
async def test_app_loads():
    app = FileOrganizerApp()
    async with app.run_test() as pilot:
        assert pilot.app.title == "File Organizer"

# Run all integration tests
pytest -m integration

# Run a specific integration test file
pytest tests/integration/test_error_propagation.py -v

@pytest.mark.integration
class TestModelErrors:
    def test_model_exception_uses_fallback_values(
        self,
        stub_text_model_init: None,
        stub_nltk: None,
        integration_source_dir: Path,
    ) -> None:
        """When model.generate() raises, TextProcessor uses fallback values."""
        text_cfg = make_text_config()
        processor = TextProcessor(config=text_cfg)
        processor.initialize()

        with patch_text_generate_error(RuntimeError("GPU out of memory")):
            result = processor.process_file(
                integration_source_dir / "report.txt"
            )

        # Graceful degradation — fallback values, not failure
        assert result.error is None
        assert result.folder_name == "documents"

"""Tests for the file organization pipeline.

Covers: text extraction, pattern analysis, suggestion generation.
"""

# Fast pre-commit validation (< 30 seconds, matches actual gate)
pytest tests/ -m "smoke" -q --strict-markers --timeout=30 --override-ini="addopts="

# Or use the canonical pre-PR guardrail orchestrator
bash .claude/scripts/pre-commit-validation.sh

touch tests/your_module/__init__.py

@pytest.mark.asyncio
async def test_async_function():
    result = await some_async_call()
    assert result is not None

@pytest.fixture(scope="function")  # Reset for each test
def temp_dir():
    with tempfile.TemporaryDirectory() as tmpdir:
        yield tmpdir

# Bad: depends on timing
time.sleep(0.1)
assert event_received

# Good: use explicit synchronization
event.wait(timeout=5)
assert event.is_set()

# Instead of: time.sleep(1)
import os

old_mtime = path.stat().st_mtime
os.utime(path, (old_mtime + 60, old_mtime + 60))

# Instead of: time.sleep(2)
import threading
import time
import pytest

deadline = time.monotonic() + 5.0
while time.monotonic() < deadline:
    if condition_met():
        break
    threading.Event().wait(0.05)
else:
    pytest.fail("Timed out waiting for condition")