GenericContainer: любой Docker-образ

Сигнатура короткая: GenericContainer принимает контекст и GenericContainerRequest, возвращает пару — контейнер и ошибку. Тип результата принципиален: не конкретная структура, а интерфейс testcontainers.Container, одинаковый для любого образа. В интерфейсе собрано всё, что нужно тесту: Host и MappedPort дают адрес, Logs отдаёт поток логов для разбора упавшего старта, Exec запускает команду внутри, CopyFileToContainer кладёт файл, Terminate прибирает. Переход от модуля к произвольному образу не меняет клиентский код: методы те же. Связка «genericcontainer go» ценна именно этим: сценарий «testcontainers любой образ» — nginx, minio, файловый прокси, внутренний демон — закрывается одним вызовом без поиска подходящего модуля и без лишней зависимости в go.mod. Ошибка возвращается на руки вместе с контейнером, если тот успел создаться: вызывающему оставляют шанс прибрать за собой — к этому моменту мы вернёмся отдельно. Интерфейс шире, чем нужно одному тесту: Inspect возвращает сырой инспект Docker, State отличает бегущий контейнер от остановленного, а SessionID отдаёт идентификатор сессии, по которому уборщик находит ресурсы прогона.

Запрос к GenericContainer — обёртка с вложенной декларацией. Внутри — знакомый ContainerRequest: Image, Env, ExposedPorts, Cmd, Labels, Files, WaitingFor; полный разбор полей — в третьем уроке. Для произвольного образа обычно хватает четырёх: Image, Env, ExposedPorts и WaitingFor, а Cmd нужен, когда демон требует аргументов запуска. Снаружи — политика запуска, у которой четыре собственных поля. Started включает автостарт: true — create, start и ожидание готовности внутри вызова, false — только create. ProviderType выбирает провайдера: нулевое значение — автодетект по переменной DOCKER_HOST, а набор провайдеров ограничен Docker и Podman. Logger подменяет логгер для этого контейнера — спасает, когда общий вывод тонет в логах параллельного прогона. Reuse включает режим переиспользования: библиотека найдёт живой контейнер с тем же Name или создаст новый, а при пустом имени вернёт ошибку ErrReuseEmptyName — поле Name нельзя оставлять незаполненным. Перед обращением к демону декларацию проверяет Validate: попытка указать одновременно Image и контекст сборки отсекается до docker create, а пустая декларация без образа и контекста отвергается с требованием указать хоть что-то — забыть Image и получить загадочный контейнер не выйдет, тест упадёт на валидации с внятной ошибкой.

Started: true — путь по умолчанию: GenericContainer сам создаёт, стартует и ждёт готовности, возвращая сервис, с которого сразу можно брать адрес и слать запросы. Started: false возвращает созданный, но не запущенный контейнер, и момент старта переезжает в тест: ctr.Start(ctx) вызывается в выбранной вами точке. Ручной старт нужен, когда между созданием и запуском должно что-то случиться: скопировать конфиг внутрь уже созданного контейнера, дождаться соседа по стенду, подключить сеть; или когда тестируется сам запуск — команда из Cmd обязана поднять процесс, а не уронить его мгновенно. Важная деталь механики: при ошибке старта GenericContainer возвращает и ошибку, и контейнер — тот уже создан, а значит, его можно прибрать и прочитать логи. Проверка «а что, если сервис не стартует» пишется честно: Start вернул ошибку — assert на неё, Terminate в Cleanup — как обычно. Ещё одна тонкость автостарта: Started: true не перезапускает уже работающий контейнер — перед Start библиотека проверяет IsRunning и пропускает запуск, если процесс жив. Для переиспользуемых контейнеров это критично: второй вызов с тем же Name не упадёт, а тихо вернёт существующий сервис.

Адрес сервиса собирается из двух вызовов. Host возвращает адрес, на котором демон выставил порт: при локальном docker это localhost, на удалённом демоне CI-раннера — его хост, поэтому адрес всегда берут из вызова, а не хардкодят. MappedPort принимает пару «порт/протокол» — например, 80/tcp — и возвращает наружный порт, который Docker назначил из свободных при старте; именно поэтому порт нельзя угадать заранее и нельзя зафиксировать декларацией. Кто не хочет склеивать адрес вручную, берёт готовое: PortEndpoint вернёт строку вида proto://host:port по заданному порту и протоколу, а Endpoint — то же для самого низкого выставленного порта. Нюанс сетевого режима host: маппинга нет, порт контейнера равен порту хоста, и MappedPort вернёт его как есть. Готовность к моменту возврата гарантирует wait-стратегия: без WaitingFor библиотека вернёт контейнер сразу после поднятия процесса, и первый запрос может прийти к сервису, который ещё не слушает порт. Каталог стратегий — порт, лог, HTTP-проба, команда — разобран в уроке про ожидания. Порт возвращается строкой, так что склейка адреса не требует конвертаций: port.Port() отдаёт готовое значение, и fmt.Sprintf собирает адрес за один вызов. Для образов с единственным портом удобен Endpoint: он берёт самый низкий выставленный порт, который почти всегда и есть рабочий.

Универсальный контейнер убирается по тем же правилам, что и модульный. Стандарт — t.Cleanup(func() { _ = ctr.Terminate(ctx) }): Cleanup-функции выполняются в обратном порядке и всегда — при провале assert'ов и при панике. Контекст для уборки — context.Background: если в теле теста вы пользовались t.Context(), к моменту Cleanup он уже отменён, и Terminate с мёртвым контекстом не успеет договориться с демоном. Удобнее готовая обёртка CleanupContainer(t, ctr): она регистрирует Terminate в Cleanup за вас, зовётся сразу после GenericContainer — до проверки ошибки — и молчит на nil. Для мест, где testing.TB недоступен, есть TerminateContainer(ctr). Ошибку уборки возвращайте тесту, а не глотайте: молчаливый провал Terminate вылезет исчерпанными портами в следующем прогоне. Страховка на случай смерти процесса — работа уборщика-супервизора, его разбор живёт в уроке про Ryuk; здесь достаточно привычки: создал контейнер — зарегистрируй уборку. Cleanup-функции исполняются в обратном порядке регистрации: если тест поднимает цепочку сервисов, последний созданный гаснет первым — порядок зависимостей соблюдается без ручного управления.