Как писать аннотацию к функции?

В контексте тестирования под «аннотацией к функции» я понимаю строку документации (docstring) для тестовой функции или метода. Она критически важна для понимания цели теста другими членами команды.

Мой стандартный формат (использую стиль Google):

import pytest

def test_calculate_discount_for_premium_customer():
    """
    Проверяет, что система корректно применяет скидку 10% для премиум-клиента.

    Тестовый сценарий:
        - Клиент с ID=42 имеет статус 'premium' в моке репозитория.
        - Исходная сумма заказа 1000 рублей.

    Ожидаемый результат:
        - Финальная сумма после скидки равна 900 рублей.
    """
    # Arrange
    mock_repo = Mock()
    mock_repo.get_customer_tier.return_value = "premium"
    service = OrderService(mock_repo)

    # Act
    result = service.apply_discount(1000, customer_id=42)

    # Assert
    assert result == 900

Что я всегда включаю в docstring теста:

1. Краткая цель: Что именно проверяет этот тест.
2. Контекст/предусловия: Какие данные или моки настроены (например, «пользователь заблокирован», «кеш пуст»).
3. Ожидаемый результат: Не только итоговое значение, но и иногда побочные эффекты (например, «вызывается метод отправки email»).

Почему это важно для QA: Хорошая документация теста упрощает его поддержку, помогает в отладке при падении и служит живой спецификацией поведения системы для новых разработчиков.