Сети: несколько контейнеров вместе

У теста и у контейнеров разные позиции в сети, и инструменты у них разные. Тест — процесс на хосте: он видит контейнер только через публикацию портов, поэтому его маршрут — ExposedPorts в декларации, затем Host и MappedPort после старта. Контейнеры между собой ходят иначе: внутри пользовательской сети Docker резолвит алиасы во внутренние адреса, и трафик идёт напрямую, минуя хост. Сценарий «testcontainers network» и построен на этом разделении: то, что раньше выглядело как «публикуй все порты подряд», распадается на две честные модели — наружу публикуется то, к чему прикасается тест, внутрь сети уходит всё остальное. Выигрыш мгновенный: база без публикации недостижима с хоста и от соседних прогонов, но прекрасно видна сервису по алиасу; у сервиса при этом один опубликованный порт вместо россыпи. Заодно исчезает целый класс флейков: прогон, публикующий всё подряд, борется за порты хоста, а сетевые адреса Docker раздаёт без ставок и конфликтов.

Сеть делает одна функция — network.New из пакета network: принимает контекст и вариативные опции, возвращает *DockerNetwork и ошибку. По умолчанию создаётся мост с драйвером bridge и случайным именем: библиотека генерирует его сама, вручную имя задать нельзя — читайте поле Name из ответа. Рядом лежат поля ID и Driver: идентификатор нужен Docker-командам и уборке, драйвер — диагностике, когда тест ведёт себя по-разному на разных хостах. Метки уборщика проставляются автоматически: сеть несёт те же служебные метки сессии, что и контейнеры, поэтому супервизор зачистит её даже при смерти процесса теста. Опции меняют поведение точечно: WithDriver задаёт драйвер, WithInternal делает сеть полностью внутренней, WithLabels добавляет свои метки поверх служебных, WithIPAM настраивает адресацию, WithEnableIPv6 включает шестую версию протокола. В исходниках рядом живёт и старый путь — метод провайдера CreateNetwork с декларацией NetworkRequest, помеченный как deprecated в пользу network.New: новый вызов короче, а имена сетей придумывать не нужно.

Контейнер подключается к сети парой полей декларации: Networks — список имён сетей, NetworkAliases — карта «сеть → список алиасов». Оба поля доступны и в ContainerRequest внутри GenericContainer, и через опции: network.WithNetwork(aliases, net) дописывает сеть и выставляет алиасы одним вызовом, WithNewNetwork создаёт сеть на месте и сразу подключает контейнер, WithBridgeNetwork присоединяет дефолтный мост без алиасов. Нюанс, который ловит почти каждый: алиасы живут только в пользовательских сетях. Попросите алиас в дефолтной bridge — опция вернёт ошибку ещё до обращения к Docker: сетевые алиасы поддерживаются только там, где сеть создана явно. Контейнер может стоять в нескольких сетях сразу: первая подключается при создании, остальные Docker прикрепляет по одной, каждая со своим списком алиасов; сколько сетей — столько и адресов, их отдают ContainerIP и ContainerIPs. Опции читаются линейно, как список аргументов docker run, а карта NetworkAliases требует помнить имя сети — на длинных декларациях опция обычно нагляднее. Поля и опции ведут к одному результату — выбирайте по стилю стенда из урока про GenericContainer.

Классический стенд: сервис и его база в одном тесте. Базе — алиас db и ни одного опубликованного порта: с хоста она недостижима, и это фича, а не недосмотр. Сервис получает адрес базы через окружение: DB_HOST со значением db — тем самым алиасом, который Docker резолвит внутри сети. Приложению не важно, что на другом конце контейнер: конфигурация выглядит как в развёрнутой среде, где сервис тоже ходит в базу по имени. Тест при этом общается только с сервисом: один ExposedPorts, один MappedPort, запрос к /health. Готовность у стенда двухуровневая: база дожидается своей стратегии до возврата GenericContainer, сервис — своей, и лишь затем тест стучится в /health. Если тесту нужен прямой доступ к базе — сеять данные или сверять состояние SQL-запросами, пригодится и курс про pgx, — опубликуйте порт базе осознанно: каждый опубликованный порт — потенциальное пересечение в параллельном прогоне. Фиксированные адреса и общая сеть на весь пакет не нужны: сеть у каждого теста своя, имена внутри — свои.

Сеть — такой же ресурс прогона, как контейнер, и уборка у неё двухслойная. Первый слой ваш: net.Remove(ctx) в t.Cleanup или готовая обёртка testcontainers.CleanupNetwork(t, net), которая делает ту же регистрацию за вас; внутри Remove сигналит уборщику и просит Docker удалить сеть по идентификатору. Второй слой страховочный: метки сессии, проставленные network.New, позволяют супервизору зачистить сеть, если процесс теста умер. Убирать сразу — не педантизм: сети расходуют адресное пространство Docker, и скопление неубранных сетей к концу пакета бьёт по следующим тестам. На CI это заметнее всего: длинный пакет, где сети заводятся на каждый тест без уборки, упирается в лимиты адресации раньше, чем в лимиты памяти. Взамен вы получаете главную награду урока — изоляцию: своя сеть на тест означает, что два параллельных прогона с одинаковыми алиасами db и web не видят друг друга в упор, и никакой тест не достучится до чужой базы. Изоляция через сети дополняет изоляцию через случайные порты — вместе они делают параллельность скучной в хорошем смысле.