ai-agents-workspace-starter: Skill for Claude Code

Skill: Write Python Tests

Unit Tests (backend/app/tests/unit/)

Test services in isolation (mock repositories):

• Mock repo with AsyncMock(), inject into service via fixture
• Test one service method per test function
• Assert return values AND mock interactions (assert_called_once)
• Test error paths: pytest.raises(NotFoundError) when entity not found
• Naming: test_<what>_<scenario> or test_<what>_<scenario>_<expectation>

Integration Tests (backend/app/tests/integration/)

Test API endpoints with httpx + TestClient:

• Use AsyncClient(app=app, base_url="http://test")
• Test HTTP status codes AND response body structure
• Include auth tests: unauthenticated returns 401
• Test CRUD operations: GET list, GET by id, POST create, PUT update, DELETE

Factories (backend/app/tests/factories.py)

• Use factory.Factory with Meta.model pointing to domain entity
• factory.Sequence for unique IDs and names
• factory.LazyAttribute for computed fields (e.g. email from id)
• NEVER use fixtures for test data - factories only

Running Tests

make test                              # all tests
docker compose -f infra/docker-compose.yml exec backend pytest -v --tb=short    # verbose
docker compose -f infra/docker-compose.yml exec backend pytest -k "test_name"   # specific test
docker compose -f infra/docker-compose.yml exec backend pytest --cov=app        # with coverage

TDD Flow

1. RED - Write failing test
2. GREEN - Minimum code to pass
3. REFACTOR - Clean up

Rules

• Tests MUST run in Docker (NEVER locally)
• Each service method requires unit tests
• Each API endpoint requires integration test
• Use factory-boy for test data (NOT fixtures)
• Test edge cases: null, empty, boundary, error

---

See also (MANDATORY)

• Before implementation - read workflows/spec-development.md
• After implementation - run workflows/post-impl-verify.md