| name | python-fastapi-ddd-testing-skill |
| description | Guides unit testing for Python DDD + Onion Architecture apps (Domain Entities/Value Objects and UseCases) using pytest and repository mocks, based on the dddpy reference. Use when adding tests, choosing what to mock, or structuring test folders for a DDD FastAPI project. |
| license | Apache-2.0 |
| metadata | {"author":"Takahiro Ikeuchi","version":"1.0.0"} |
Testing DDD Layers with pytest (Domain / UseCase)
This skill focuses on unit tests for the inner layers:
- Domain: Value Objects + Entities (pure business rules)
- UseCase: application workflows that orchestrate Domain + Repository interfaces
It intentionally avoids full HTTP/API tests unless explicitly requested.
Test strategy (recommended)
- Domain tests: no mocks, assert invariants and state transitions.
- UseCase tests: mock repository interfaces (
Mock(spec=...)), assert:
- correct repository method calls
- correct domain exceptions raised
- correct entity state transitions
- Infrastructure/Presentation: add integration tests separately (optional).
Folder structure
Mirror the Onion layers:
tests/
domain/{aggregate}/...
usecase/{aggregate}/...
infrastructure/... # optional integration tests
presentation/... # optional API tests
UseCase testing pattern (dddpy-based)
Use unittest.mock.Mock(spec=RepoInterface) so typos fail fast.
from unittest.mock import Mock
import pytest
@pytest.fixture
def todo_repository_mock():
return Mock(spec=TodoRepository)
def test_create_todo_calls_save(todo_repository_mock):
usecase = CreateTodoUseCaseImpl(todo_repository_mock)
title = TodoTitle("Test")
todo = usecase.execute(title=title)
todo_repository_mock.save.assert_called_once_with(todo)
For more examples (Value Object validation, entity lifecycle tests, and exception cases), read references/TESTING.md.
