Отладка упавших тестов

Logs — первый инструмент, и у него приятное свойство: Docker хранит вывод процесса даже после его смерти, пока контейнер не удалён. Сигнатура короткая — Logs(ctx) возвращает io.ReadCloser и ошибку; внутри библиотека запрашивает у демона сразу и stdout, и stderr, а заодно разбирает мультиплексированный формат, в котором Docker склеивает потоки, если у образа не включён TTY. Дальше дело теста: io.ReadAll — и весь журнал в памяти. Логи читаются и у контейнера, упавшего прямо во время wait-стратегии: GenericContainer вернёт ошибку вида wait until ready, обернув причину, но сам контейнер ещё не удалён — это окно для чтения. Снимайте показания в этом окне: контейнер доживёт до уборки, но не дольше, а хвост ценнее целого — причина почти всегда в последних строках перед смертью процесса. Привычка, которая экономит часы: поднимать уровень логов сервиса в тестовом окружении через Env — дорожка улик станет длиннее уже на первом прогоне. Тонкость: журнал живёт в демоне, а не в тестовом процессе, поэтому снять его можно в любой момент жизни контейнера — и до, и после смерти процесса.

Если контейнер жив, но ведёт себя странно, Exec — ваш ssh внутрь. Сигнатура: Exec(ctx, cmd []string, options ...ProcessOption), и три результата — код выхода int, io.Reader с выводом и ошибка. Ошибка означает проблему механизма: например, exec невозможен, потому что процесс контейнера уже умер. Код выхода — ответ самой команды: cat вернёт 1 на отсутствующем файле, ps отработает с нулём. Нулевой код тоже не гарантия правды: команда могла отработать, но не над тем файлом — вывод читайте вместе с кодом. Опции настраивают процесс: WithUser меняет пользователя, WithWorkingDir — рабочий каталог, WithEnv дописывает переменные окружения. Классическая связка для диагностики: ps aux, чтобы увидеть, какие процессы вообще живут и кто держит порт, и cat конфига — убедиться, что файл внутрь попал с тем содержимым, каким задумано. В библиотеке есть готовая обёртка RequireContainerExec: она выполняет команду, требует нулевой код выхода и возвращает вывод строкой — удобно для быстрых проверок. Момент, который легко упустить: минимальные образы не кладут ни ps, ни curl — отсутствующая команда вернётся ошибкой или кодом 127.

State(ctx) — обёртка над docker inspect: возвращает *container.State, структуру демона с фактами о жизни процесса. Самое полезное поле — ExitCode: код, с которым завершился процесс. Ноль — чистый выход, 137 — SIGKILL, часто по памяти, 125 — ошибка самого демона при запуске, 127 — команда не найдена: эти числа мгновенно сужают круг подозреваемых. Рядом живёт Error — сообщение, которое демон записал для контейнера, и OOMKilled — флаг смерти из-за нехватки памяти. Status и Running дают строку и булев снимок состояния: running, exited, created. А вот IsRunning — не живая проверка: метод возвращает кэшированный атомарный флаг, который библиотека обновляет на собственных Start, Stop и Terminate, и молчит, когда процесс умирает сам. Живое состояние дают State и Inspect — полный ответ демона, где рядом со статусом лежат порты и сети; Inspect — тот самый docker inspect, только типизированный в InspectResponse. Ошибка из State — повод для отдельного assert'а: демон недоступен или контейнер исчез раньше времени, и это тоже улика.

Красный тест без улик — потерянное время CI: прогон придётся повторять, чтобы просто увидеть симптом. Правило — успеть снять показания до уборки. Сообщения t.Fatalf пишите содержательно: имя образа, код выхода, ключевая строка журнала — деталь, которая позволит понять провал, не запуская прогон второй раз. Хвост логов дампите в двух местах: перед каждым t.Fatalf после старта и в Cleanup с проверкой t.Failed — Cleanup выполняется при любом исходе, флаг покажет, красный ли тест, и логи уйдут в отчёт только при провале. Подводный камень: CleanupContainer стоит вызывать первым — сразу после Run и до проверки ошибки; он регистрирует Terminate в Cleanup, и контейнер удаляется даже при красном тесте. Поведение правильное, но улики после него недоступны: docker logs по удалённому контейнеру не работает. На помощь приходит порядок Cleanup: функции исполняются в обратном порядке, поэтому дамп, зарегистрированный позже уборки, сработает раньше Terminate — по ещё живому контейнеру. Такой дамп превращает отчёт CI в самодостаточный протокол: причина видна без повторного прогона и без доступа к машине.

Когда улик из отчёта мало, контейнер стоит осмотреть руками — уже не из теста, а из терминала. Схема локальная: задайте контейнеру фиксированное имя — Name: billing-debug — и выключите уборщика сессии: TESTCONTAINERS_RYUK_DISABLED=true, переменная сравнивается со строкой true буквально. Имя делает контейнер находным: docker ps --filter name=billing-debug, дальше docker logs и docker exec -it billing-debug sh — живая диагностика руками. Пока идёт осмотр, контейнер в вашем распоряжении: открытые порты, запущенные процессы и файлы видны изнутри — всё то, что тесту показывать незачем. Здесь нужна честность о двух уборках. Первая — ваша: Terminate из t.Cleanup или CleanupContainer удаляет контейнер при штатном конце теста, красном или зелёном, и выключенный Ryuk этому не мешает; для ручного осмотра на время отладки закомментируйте уборку. Вторая — супервизор сессии: он подметает за процессами, умершими без уборки — kill, os.Exit, упавшая джоба; именно его выключение оставляет мусор в покое. Отладили — верните уборку и уберите имя: фиксированные имена конфликтуют при параллельных прогонах, а устройство уборщика разобрано в восемнадцатом уроке.