Python Testing

Python Testing Skill

Testing Framework & Configuration

• Use pytest combined with pytest-asyncio for all testing.
• Auto Mode: The project is configured with asyncio_mode = "auto" in server/pyproject.toml. Because of this, any test function declared with async def is automatically run inside an asyncio event loop.
• No Decorators Needed: Do not use the @pytest.mark.anyio or @pytest.mark.asyncio decorators on async test functions, as asyncio_mode = "auto" handles this automatically.

Directory Structure

All test files are located under server/tests/ and are organized as follows:

• tests/unit/: Contains unit tests testing components in isolation. Subdirectories match the application structure (e.g., core, repositories, service, utils).
• tests/integrations/: Contains end-to-end integration tests that call API endpoints using a test client.
• tests/mocks/: Contains mock classes for repositories and external integrations (e.g. MockTodoRepository).
• tests/factories.py: Contains factory methods (like create_user, create_todo) to generate mock data.
• tests/conftest.py: Contains common fixtures and configuration for all tests.

Conventions & Best Practices

• Docstrings: Every test function MUST have a descriptive docstring explaining exactly what it verifies.
• Mocking: Mock external dependencies (like database repositories or third-party HTTP clients) when writing unit tests for services. Use the classes in tests/mocks/.
• Fixture Scopes: Ensure all fixtures are explicitly scoped (e.g. scope="session").
• Code Coverage: Ensure test coverage is strictly more than 80%.
• Async loops: Use the default loop scopes defined in pyproject.toml (asyncio_default_fixture_loop_scope = "session" and asyncio_default_test_loop_scope = "session").
• No need to add comments inside any of the test code. Docstrings are enough.

Example: Unit Test

async def test_add_todo_without_attachments(
    todo_service: TodoService,
    mock_todo_repository: MockTodoRepository,
) -> None:
    """Test that creating a Todo task without specifying attachment IDs persists the Todo correctly."""
    todo_data = TodoCreate(
        title="Buy groceries",
        description="Milk and bread",
        is_completed=False,
        attachment_ids=None,
    )
    todo = await todo_service.add(todo_data)
    assert len(mock_todo_repository.todos_db) == 1
    assert mock_todo_repository.todos_db[0].title == "Buy groceries"
    assert mock_todo_repository.todos_db[0].id == todo.id

Example: Integration Test

async def test_get_todos_list_success(client: Any) -> None:
    """Integration test verifying that an authenticated user can list their seeded Todo items successfully."""
    api_client = await client("user@email.com", "SecurePass123!")
    response = await api_client.get("/v2/todos/")
    assert response.status_code == 200
    data = response.json()
    assert "founds" in data

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aps08
• Source: aps08/fullstack-clean-architecture
• License: Apache-2.0
• Homepage: https://aps08.medium.com

Install and usage instructions live in the source repository linked above.