Жизненный цикл контейнера в тесте

Вся будущая жизнь контейнера описывается одной структурой — ContainerRequest из пакета testcontainers: образ, переменные окружения, порты, команда, метки, файлы, стратегия готовности. Структуру ContainerRequest Go применяет внутри GenericContainer, когда тест передаёт ему GenericContainerRequest: в этой обёртке рядом с вложенной декларацией живут свои поля — Started, провайдер, логгер, режим Reuse. Дизайн осмысленный: декларация отвечает на вопрос «что запустить», обёртка — на вопрос «как ведёт себя тест». До обращения к Docker декларацию проверяет Validate: он отсекает недопустимые комбинации, например образ одновременно с контекстом сборки. В момент создания провайдер дописывает к вашим меткам служебные — семейство org.testcontainers с языком, версией и идентификатором сессии, — и именно по ним уборщик в конце прогона находит ресурсы, которые создал тест. Декларацию удобно читать как docker run, записанный типами: одно поле — один флаг запуска, и ничего из теста в образ не просачивается. Когда модуль базы в четвёртом уроке подставит декларацию поверх вашей, вы уже будете знать, что именно он дописывает.

Env — главный канал конфигурации сервиса: большинство образов читает настройки из переменных окружения, и тест подставляет свои значения вместо продакшен-конфига, не пересобирая образ. Cmd — аргументы, которые дописываются к точке входа образа: уровень логов, режим работы, адрес порта. ExposedPorts объявляет, какие порты контейнера тест хочет видеть снаружи, вместе с протоколом — 8080/tcp; маппнутый порт хоста вы узнаёте уже после старта через MappedPort, потому что Docker назначает его из свободных. Объявляйте ровно те порты, с которыми тест реально работает: каждый лишний порт замедляет старт и проверку готовности. Files копирует файлы внутрь при старте: каждый элемент — ContainerFile с путём на хосте или готовым Reader, путём внутри контейнера и правами FileMode; это идеальный канал для конфигов — точный снимок содержимого на момент прогона. Mounts решает другую задачу: он подключает каталоги и тома насквозь, и изменения видны в обе стороны, пока контейнер жив. Конфиг — Files, живые данные — Mounts, и путать их не стоит.

Labels — карта строковых меток, ложащихся на контейнер как docker-лейблы. Тесту они дают группировку и фильтрацию: помечайте прогон командой, фичей или билдом — потом один docker ps --filter label=suite=integration покажет, кто остался висеть. Библиотека складывает ваши метки со своими: служебные метки сессии обязательны, и уборщик находит ресурсы прогона именно по ним, так что ваши метки просто мержатся поверх. Name задаёт контейнеру фиксированное имя вместо сгенерированного. Звучит безобидно, но в параллельном мире это мина: два теста с одним именем на одной машине — это два create, и второй упадёт с конфликтом. Имя оправдано, когда оно нужно протоколу: режим Reuse требует имени, а отладочный docker logs приятнее с говорящим. AutoRemove перекладывает удаление на сам Docker: контейнер стирается сразу при останове, и Terminate уже не найдёт, что убирать. Поле в структуре есть, но исходники помечают его Deprecated в пользу HostConfigModifier — современный путь конфигурирует то же самое через хост-настройки, а гарантированную уборку всё равно держит Terminate.

Started в обёртке GenericContainerRequest — выключатель политики запуска. При true GenericContainer создаёт контейнер и сам же стартует его: вызов не вернётся, пока процесс не поднят и wait-стратегия не пройдена — тест принимает готовый сервис. При false возвращается созданный, но не запущенный контейнер, и момент старта становится вашим: ctr.Start(ctx) вызывается руками в выбранной точке. Зачем это нужно: проверить поведение сервиса, начавшего жить без зависимости, — состояние created вместо running; подправить файлы или окружение после создания, но до запуска; испытать сам старт — что Cmd поднимает процесс, а не роняет его мгновенно. Отдельный сценарий — проверка ошибки запуска: битая команда вернётся из Start, и тест фиксирует причину assert'ом, а не гадает по зелёному экрану. Механика честная: Start исполняет хуки, поднимает процесс и только после запуска ждёт готовности — ранняя смерть процесса вернётся ошибкой из Start, и у теста остаются логи для разбора. Забыли Start? Тест пройдёт зелёным, а контейнер-зомби будет ждать Terminate из Cleanup — или уборщика.

Terminate — единственный штатный выход из жизни контейнера: сигнатура Terminate(ctx, opts...) принимает контекст и опции, а внутри делает две вещи — останавливает контейнер (с таймаутом, после которого Docker убьёт процесс силой) и удаляет его вместе с томами. Ошибку уборки Terminate возвращает на руки: логируйте её, а не глотайте. Регистрация в t.Cleanup — стандарт: Cleanup-функции выполняются в обратном порядке и всегда — при провале assert'ов и при панике тоже. У библиотеки есть и готовая обёртка: testcontainers.CleanupContainer(t, ctr) регистрирует Terminate в Cleanup за вас — её даже зовут до проверки ошибки создания, потому что nil-контейнер она игнорирует. Контекст для уборки — отдельная тонкость. context.Background живёт до конца процесса: честный, но грубый вариант. t.Context() из Go 1.24 точнее — отменяется вместе с тестом и гасит висящие на нём операции, — но именно поэтому внутри Cleanup он уже отменён, и Terminate там зовут со свежим context.Background. Наконец, Terminate после ручного Stop не ошибка: библиотека считает безобидными ситуации «уже остановлен» и «удаление уже идёт» и всё равно доводит удаление до конца, поэтому дублировать уборку безопасно, а пропустить — нет.