python-testing

Python Testing Patterns

Use this skill for writing tests that are deterministic, fast, and maintainable. The bias is toward testing behavior, not implementation — tests should survive refactoring.

Delivery Workflow

Python Testing progress:
- [ ] Step 1: Discover existing test structure, fixtures, and conventions
- [ ] Step 2: Identify what to test — behavior, not internals
- [ ] Step 3: Write fixtures for shared setup and teardown
- [ ] Step 4: Implement tests with clear arrange/act/assert structure
- [ ] Step 5: Verify coverage of happy path, error cases, and edge cases

Test Organization

• Mirror the source package structure: src/app/services/doc.py → tests/services/test_doc.py.
• Use conftest.py for shared fixtures scoped to the directory they serve.
• Keep test files focused on one module or class.
• Name tests after the behavior they verify: test_create_document_returns_201 not test_route.
• Group related tests in a class only when they share fixture setup; otherwise use top-level functions.

Fixtures

• Prefer function-scoped fixtures (the default) unless shared setup is genuinely expensive.
• Use session-scoped fixtures for external connections (DB, Docker containers) to avoid repeated startup cost.
• Use yield fixtures for resources requiring teardown.
• Use pytest-factoryboy or manual factory functions for domain object creation — avoid duplicating object construction in every test.

import pytest
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine

@pytest.fixture(scope="session")
def engine():
    return create_async_engine("postgresql+asyncpg://test:test@localhost/testdb")

@pytest.fixture
async def db(engine) -> AsyncGenerator[AsyncSession, None]:
    async with AsyncSession(engine) as session:
        yield session
        await session.rollback()

Async Tests

• Use pytest-asyncio with asyncio_mode = "auto" in pytest.ini or pyproject.toml to avoid per-test @pytest.mark.asyncio decoration.
• Do not mix sync and async fixtures carelessly — use anyio backend fixtures when both are needed.
• Never use asyncio.run() inside test functions — let pytest-asyncio handle the event loop.