Integration tests:
тестирование полных пайплайнов

Почему юнитов недостаточно

Классическая иллюзия: «все юнит-тесты зелёные → система работает». Для агента это особенно обманчиво, потому что его суть — в потоке данных через много компонентов, а юнит-тест каждый из них изолирует и кормит идеальными входами. Баги живут ровно там, куда юнит не смотрит: на границах между компонентами.

Типичные интеграционные баги агента, которые юниты пропускают:

• Несовпадение контракта. Компонент A отдаёт {"result": ...}, компонент B ждёт {"data": ...}. Каждый по отдельности «правильный», вместе — сломаны.
• Потеря состояния. В LangGraph-графе узел не так обновил State, и следующий узел получил пустоту (модуль 03: reducers).
• Неверная маршрутизация. Роутер и обработчики по отдельности ок, но conditional edge ведёт не туда на реальном выходе LLM.
• Реальный формат tool-вызова. Модель зовёт инструмент чуть иначе, чем ты замокал в юните, — и цепочка рвётся.

Что тестировать интеграционно

Интеграционный тест берёт кусок пайплайна из нескольких компонентов (или весь) и проверяет, что вход на одном конце даёт корректный поток к другому. Уровни укрупнения:

Что стоит покрывать интеграционно у агента:

• Связка «LLM → инструмент → LLM». Полный tool-цикл: модель решает вызвать инструмент, тот отрабатывает, результат возвращается в модель. Самый частый источник стыковых багов.
• Прохождение состояния через граф (LangGraph): State корректно обновляется и доходит от узла к узлу через реальные reducers.
• Ветвление на реальных выходах. Conditional edges выбирают верную ветку на настоящем (или записанном) ответе модели, а не на идеализированном моке.
• RAG-пайплайн целиком: retriever → сборка контекста → генерация — форматы стыкуются на всём пути.

Главный вопрос: что мокать

Сердце интеграционного тестирования агента — граница мока: что оставить настоящим, а что подменить. Слишком много моков — тест ничего не проверяет (по сути юнит); слишком мало — тест медленный, дорогой и флапающий. Разумный дефолт:

Записанные ответы (VCR / cassettes)

Как совместить «реальный формат LLM/API» с «детерминизмом и скоростью»? Популярный приём — record-and-replay (VCR, «кассеты»): один раз вызываешь настоящую LLM/API, записываешь ответ в файл, а в тестах воспроизводишь запись вместо реального вызова.

Первый прогон (record):  тест → РЕАЛЬНАЯ LLM/API → ответ сохраняется в cassette.yaml
Дальнейшие прогоны (replay): тест → cassette.yaml (реальный формат, 0 токенов, мс)

  ✓ детерминизм (тот же записанный ответ каждый раз)
  ✓ реальный формат обмена (записан с настоящего вызова)
  ✓ быстро и бесплатно в CI (сеть не дёргается)
  ⚠️ запись «протухает» — при смене модели/API перезаписать кассету

import pytest

# фейковая LLM: отдаёт РЕАЛЬНЫЙ формат tool_call, потом финальный ответ
class FakeLLM:
    def __init__(self, scripted): self.scripted = list(scripted); self.i = 0
    def invoke(self, messages):
        resp = self.scripted[self.i]; self.i += 1
        return resp   # тот же формат, что настоящая модель (tool_calls / content)

def test_agent_tool_cycle_end_to_end():
    fake = FakeLLM([
        # шаг 1: модель решает вызвать инструмент (РЕАЛЬНЫЙ формат tool_call)
        ToolCallMessage(tool="search", args={"query": "погода Москва"}),
        # шаг 2: получив результат инструмента, формулирует ответ
        AIMessage(content="В Москве сейчас +18°C."),
    ])
    # СВОИ компоненты — реальные: граф, ToolNode, настоящий search-инструмент
    agent = build_agent(llm=fake, tools=[real_search_tool])

    result = agent.invoke({"input": "какая погода в Москве?"})

    # проверяем СКВОЗНОЙ поток, а не отдельный узел:
    assert result["tool_calls"][0].tool == "search"     # стык LLM→tool сработал
    assert "18" in result["output"]                     # результат дошёл до ответа
    assert result["state"]["step"] == "done"            # состояние прошло через граф

Что делать с недетерминизмом LLM

Иногда всё же нужен интеграционный тест с реальной LLM (проверить, что настоящая модель на данном промпте вызывает нужный инструмент). Но реальная модель недетерминирована — строгий assert output == "..." будет флапать. Приёмы, чтобы такой тест был стабильным:

• Проверяй свойства, а не точный текст. Не == "В Москве +18", а «вызван инструмент search», «в ответе есть число», «нет исключений», «дошли до финального узла».
• temperature=0 — снижает (не убирает) разброс, делает поведение стабильнее.
• Проверяй траекторию/структуру, а не формулировку: какие узлы посетил, какие инструменты вызвал, в каком порядке (это отдельная большая тема — урок про trajectory evaluation).
• Изолируй «живые» тесты. Помечай их (@pytest.mark.llm), гоняй реже (не на каждый PR, а ночью/перед релизом) — они медленные и стоят токенов.

Место в CI

Интеграционные тесты — средний слой пирамиды: их меньше юнитов, они медленнее, но и они должны быть достаточно быстрыми для CI. Практичное разделение по стоимости:

На КАЖДЫЙ PR (быстро, детерминированно):
  unit-тесты (LLM замокана)  +  integration с ЗАПИСАННЫМИ ответами (VCR)
  → нет сети, нет токенов, зелёный за секунды

Реже (ночью / перед релизом, помечены @pytest.mark.llm):
  integration с РЕАЛЬНОЙ LLM/API  +  e2e/eval прогоны
  → ловят «протухшие» кассеты и реальные регрессии формата

Правило: быстрые детерминированные тесты — на каждый коммит,
         медленные «живые» — по расписанию, отдельным джобом.

Типичные ошибки

Шпаргалка

INTEGRATION = компоненты ВМЕСТЕ, проверка СТЫКОВ и потока данных (не изоляция)
  unit: «работает ли компонент?» · integration: «работают ли вместе?»
  баги на ГРАНИЦАХ: несовпадение контракта · потеря state · роутинг · формат tool_call

ЧТО ПОКРЫВАТЬ: связка LLM→tool→LLM (главное!) · прохождение State через граф ·
  ветвление на реальных выходах · RAG-пайплайн целиком
  уровни: пара компонентов → подграф → весь агент e2e

ГРАНИЦА МОКА (что реальное / что мок):
  свои компоненты (tools/парсеры/граф) → РЕАЛЬНЫЕ (их стыки и проверяем)
  LLM → записанный/фейковый ответ, но РЕАЛЬНЫЙ ФОРМАТ (не убирай стык!)
  внешние API → мок/запись · БД → тестовый инстанс · сеть в CI → избегать
  ⚠️ замокал всё → потерял интеграцию (это юнит)

VCR / КАССЕТЫ (record-and-replay):
  record: 1 раз реальный вызов → сохранить · replay: из файла (детерм., 0 токенов, мс)
  ⚠️ кассеты ПРОТУХАЮТ при смене модели/API → перезаписывать по расписанию

НЕДЕТЕРМИНИЗМ реальной LLM:
  НЕ == текста! проверяй СВОЙСТВА/ПОВЕДЕНИЕ (вызван tool, есть число, дошёл до конца)
  temperature=0 · проверять траекторию/структуру · @pytest.mark.llm, гонять реже

CI: PR → unit + integration(VCR) (быстро/детерм.) · ночь/релиз → real LLM + e2e
ЗАЩИТА = unit (компоненты) + integration (стыки) + eval (качество)

ГРАБЛИ: замокать всё · сеть в CI на PR · == с реальной LLM · протухшие кассеты

Практическое задание

Что дальше

И юнит-, и интеграционные тесты опираются на тест-кейсы: наборы входов и ожиданий. Где их брать, как собирать репрезентативные наборы (синтетические и ручные) и поддерживать их — отдельная тема. Следующий урок — evaluation datasets: как строить датасеты для тестирования и оценки агента.