python-fastapi-ddd-testing-skill
Scannednpx machina-cli add skill iktakahiro/python-fastapi-ddd-skill/python-fastapi-ddd-testing-skill --openclawTesting 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.
Source
git clone https://github.com/iktakahiro/python-fastapi-ddd-skill/blob/main/skills/python-fastapi-ddd-testing-skill/SKILL.mdView on GitHub Overview
Guides unit testing for Python DDD + Onion Architecture apps, focusing on Domain (Entities and Value Objects) and UseCase layers, based on the dddpy reference. It emphasizes avoiding full HTTP/API tests unless requested and recommends structuring tests to reflect onion architecture.
How This Skill Works
Tests are organized by onion layers: domain tests validate invariants with no mocks, usecase tests mock repository interfaces (Mock(spec=...)) and verify calls, domain exceptions, and entity transitions, while infrastructure/presentation tests are optional integration tests. Practical patterns and examples are provided to mirror real-world DDD FastAPI projects.
When to Use It
- When starting test coverage for a DDD FastAPI project and you want domain invariants tested without mocks
- When validating UseCase workflows by confirming correct repository calls
- When organizing tests by onion-layer folders: domain, usecase, infrastructure, presentation
- When choosing what to mock (prefer repository interfaces in UseCase tests)
- When you need optional integration tests for infrastructure or API layers
Quick Start
- Step 1: Create a Mock(spec=RepoInterface) for the repository
- Step 2: Instantiate the UseCase implementation with the mock
- Step 3: Execute the use case and assert repository calls and domain behavior
Best Practices
- Test Domain: no mocks, assert invariants and state transitions
- Test UseCases: mock repository interfaces with Mock(spec=...); verify calls and exceptions
- Use Mock from unittest.mock to enable fast interface checks and fail-fast typos
- Mirror onion structure in tests/ domain, usecase, infrastructure, presentation
- Keep integration tests optional and separate from unit tests
Example Use Cases
- test_create_todo_calls_save demonstrates a UseCase calling repo.save(todo)
- Value Object validation tests ensure TodoTitle enforces rules
- Entity lifecycle tests verify state transitions on domain events
- Exception cases: UseCase raises domain exceptions for invalid input
- Reference tests in references/TESTING.md for additional patterns
