---
icon: lucide/flask-conical
---

# Testing

This page describes the current test layout and execution model for this repository.

Primary guidance sources:
- [Pytest scaffolding skill](./skills/pytest-scaffolding/SKILL.md)
- [Pytest docs reference](./skills/pytest-scaffolding/references/pytest-docs.md)
- [FastAPI + uv + Docker skill](./skills/fastapi-uv-docker/SKILL.md)

## Goals

1. Keep local feedback fast with deterministic tests.
2. Mirror source modules with focused test groups.
3. Keep endpoint and MCP surface checks explicit.
4. Make marker usage strict and intentional.

## Current Test Layout

Current tree:

```text
tests/
    __init__.py
    conftest.py
    registry/
        ingest/
            conftest.py
            test_current_docs.py
            test_document.py
            test_prompt.py
            test_skill.py
        models/
            test_document_validation.py
            test_prompt_validation.py
            test_registry_payload_models.py
            test_skill_validation.py
    web/
        conftest.py
        test_endpoint_connections.py
        test_mcp_skills.py
```

Source-to-test alignment today:
- `src/personal_mcp/registry/ingest/` -> `tests/registry/ingest/`
- `src/personal_mcp/registry/models/` -> `tests/registry/models/`
- `src/personal_mcp/web/` and MCP HTTP surface -> `tests/web/`

## Markers And Strictness

Configured markers in `pyproject.toml`:
- `unit`: fast deterministic tests with no external dependencies
- `integration`: framework or component integration tests
- `smoke`: thin critical-path checks

Pytest runs with `--strict-markers`, so any unregistered marker fails the test run.

## Fixture Layering

Fixture placement follows test scope:
1. `tests/conftest.py` for cross-suite defaults.
2. `tests/registry/ingest/conftest.py` for ingest-specific setup.
3. `tests/web/conftest.py` for web and endpoint client setup.

Prefer adding fixtures at the narrowest scope that serves more than one test.

## Command Baseline

Canonical invocation:

```bash
uv run pytest
```

Useful filtered runs:

```bash
uv run pytest --collect-only -q
uv run pytest -m unit -q
uv run pytest -m integration -q
uv run pytest -m smoke -q
```

## Adding New Tests

When adding coverage:
1. Place tests under the nearest existing module subtree (`registry/` or `web/`).
2. Mirror the source path where practical.
3. Reuse existing `conftest.py` files before adding new fixture layers.
4. Add markers only when they convey execution intent, and register new markers in `pyproject.toml` first.

This keeps the suite aligned with the current architecture while preserving a fast local test loop.