test:first

Command /test:first — TDD Red Phase

Create a test BEFORE writing implementation. This is the key command for TDD workflow.

TDD Principle

1. Red — write a failing test (this command)
2. Green — write minimal code to pass the test
3. Refactor — improve code while keeping tests green

Instructions

Step 1: Determine test structure

Based on the feature description, determine:

• What to test (function, method, endpoint)
• Which scenarios to cover (happy path, edge cases, errors)
• Which dependencies to mock

Step 2: Determine test location

src/modules/users/services.py → tests/modules/users/test_services.py
src/modules/users/routers.py → tests/modules/users/test_routers.py
src/core/security.py → tests/core/test_security.py

Step 3: Create a failing test

import pytest
from unittest.mock import AsyncMock, MagicMock

# Import what does NOT exist yet — test will fail
from src.modules.users.services import UserService


class TestUserService:
    """Tests for UserService — user creation."""

    @pytest.fixture
    def mock_repository(self) -> AsyncMock:
        """Mock repository."""
        return AsyncMock()

    @pytest.fixture
    def service(self, mock_repository: AsyncMock) -> UserService:
        """Service with mocked dependencies."""
        return UserService(repository=mock_repository)

    async def test_create_user_success(
        self,
        service: UserService,
        mock_repository: AsyncMock,
    ) -> None:
        """Successful user creation."""
        # Arrange
        user_data = {"email": "[email protected]", "name": "Test User"}
        mock_repository.save.return_value = {"id": 1, **user_data}

        # Act
        result = await service.create(user_data)

        # Assert
        assert result["id"] == 1
        assert result["email"] == "[email protected]"
        mock_repository.save.assert_called_once()

    async def test_create_user_duplicate_email_raises_conflict(
        self,
        service: UserService,
        mock_repository: AsyncMock,
    ) -> None:
        """Creating user with existing email raises ConflictError."""
        # Arrange
        from src.core.exceptions import ConflictError

        user_data = {"email": "[email protected]", "name": "Test User"}
        mock_repository.get_by_email.return_value = {"id": 1}  # already exists

        # Act & Assert
        with pytest.raises(ConflictError):
            await service.create(user_data)