prompts/docs/testing.md

icon

icon
lucide/flask-conical

Testing

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

Primary guidance sources:

• Pytest scaffolding skill
• Pytest docs reference
• FastAPI + uv + Docker skill

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:

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:

uv run pytest

Useful filtered runs:

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.