Testcontainers в Node.js: настоящие сервисы в тестах — мастерская и 8 задач
Настоящие PostgreSQL и HTTP в тестах: порты, готовность, SQL, rollback, сбои и очистка. Восемь задач, мастерская и исходники Windows/Linux.

Testcontainers: проверить приложение с настоящим сервисом
Функция прошла тесты, но после запуска приложения запрос к PostgreSQL падает: имя колонки отличается, ограничение таблицы отклоняет значение, транзакция оставляет частичное изменение или клиент подключается не к тому порту. Подмена базы внутри unit-теста могла вернуть ожидаемый объект и не заметить ни одной из этих проблем.
Testcontainers позволяет создавать нужный сервис из кода теста. В нашем проекте Node.js поднимает настоящий PostgreSQL в Docker, получает адрес подключения, создаёт таблицу, выполняет SQL и удаляет контейнер. Каждый сценарий работает с учебными данными и собственными ресурсами. Не нужно заранее заводить общую тестовую базу и вручную возвращать её в исходное состояние после каждого эксперимента.
В статье восемь практических тем и девять записей выполнения. Можно изучить запуск, случайные порты, HTTP readiness, CRUD, ограничения, откат транзакции, ошибки подключения, параллельную изоляцию и очистку при исключении. Исходники предназначены для самостоятельного запуска в Windows и Linux; на странице доступна мастерская с результатами настоящих проверок.
Где применять: API, импорт, очереди и изменения схемы
В API интеграционный тест полезен для репозитория, который читает и записывает данные. Он проверяет реальный SQL и ограничения выбранной СУБД. В импорте — для преобразования входной строки в запись с уникальным ключом. В фоновой обработке — для подтверждения сообщения, повтора и сохранения результата. При изменении схемы — для совместимости миграции и запросов приложения.
Начать лучше с места, где ошибка уже случалась: некорректная транзакция, апостроф в имени, дублирующий внешний идентификатор или случайный конфликт тестовых данных. Такой сценарий даёт понятный результат. После исправления тест должен воспроизводить прежнюю проблему и подтверждать новое поведение на настоящем сервисе, а не только на подготовленном ответе подмены.
У библиотеки есть модули для разных сервисов, но эта мастерская сосредоточена на PostgreSQL и небольшом HTTP-приложении. Это позволяет подробно разобрать жизненный цикл и границы проверки. Освоенные приёмы затем можно перенести на брокер, кеш или другой сервис, добавив его реальные команды, ожидание готовности и собственные проверки отказа.
Unit, интеграционный и сквозной тест решают разные задачи
Unit-тест удобен для чистого вычисления, преобразования данных или правила, которое не требует процесса базы. Он быстро показывает, какая ветка логики сломалась. Интеграционный тест добавляет настоящий драйвер, сетевое соединение и сервис. За это приходится платить временем запуска и более сложной средой, зато становятся видны ошибки на границе компонентов.
Сквозной тест браузерного интерфейса проверяет ещё более длинный путь: человек нажимает кнопку, форма отправляет запрос, сервер меняет данные и страница показывает результат. Testcontainers может подготовить инфраструктуру для такого сценария, но сам по себе не нажимает кнопки и не проверяет верстку. В нашей статье браузер показывает записи Node-тестов, а не полноценный пользовательский заказ.
Не стоит переносить в Docker каждую проверку сложения двух чисел. Выберите небольшой набор операций, где важны конкретная база, формат протокола, ограничения и совместимость версий. Быстрые unit-тесты оставьте рядом. Вместе эти уровни помогают находить причину сбоя, а не просто увеличивать число зелёных строк в отчёте.
Как устроен стенд: Node управляет Docker, сервис живёт отдельно
Есть три участника: процесс Node с тестом, Docker engine и созданный контейнер PostgreSQL. Node вызывает API Docker, получает готовый контейнер и подключается к базе через pg. Сам PostgreSQL действительно исполняет запросы, применяет CHECK и UNIQUE, выполняет COMMIT или ROLLBACK. Поэтому результат отличается от проверки заранее заданного JSON.
Windows-вариант использует локальный Node и Docker Desktop с Linux engine. Linux-вариант запускает Node-клиент в отдельном контейнере, который обращается к тому же учебному Docker через socket. PostgreSQL в обоих случаях работает в Linux-контейнере. Это не проверка PostgreSQL, установленного нативно в Windows, и не независимый production-кластер.
Мастерская сайта не получает API Docker и не запускает контейнеры для посетителя. В неё попадают только сохранённые результаты и исходники. Для самостоятельного выполнения нужен доверенный локальный Docker. Подключать публичный сайт к административному socket ради красивой кнопки запуска здесь не требуется и в проекте не предусмотрено.
Версии, lock-файл и закреплённые образы
Проект использует Testcontainers 12.2.1, модуль @testcontainers/postgresql 12.2.1, драйвер pg 8.23.1 и Node 24. Версии проверены при подготовке 16 ноября 2026 года. Package-lock.json закрепляет полный набор npm-пакетов, а src/images.json — образы PostgreSQL и Node по digest. Повторяемый образ важен, когда поведение сервиса является частью теста.
В зависимостях есть два явных overrides для glob и minimatch: они заменяют старую транзитивную цепочку, на которую npm audit сообщил moderate advisories. Закреплённый набор прошёл сценарии этой мастерской. Это не обещание, что любое произвольное применение Testcontainers совместимо с такой заменой; при обновлении проекта повторяйте проверки и оценивайте изменения lock.
Для повторения используйте npm ci. Команда npm update относится к обновлению зависимостей, а изменение тега образа может сменить версию базы. Не смешивайте результат старой записи с новым исходным проектом. Хеши файлов в записях позволяют обнаружить такое расхождение и заново выполнить нужный запуск.
{
"name": "aen-testcontainers-node-workshop",
"version": "1.0.0",
"private": true,
"type": "module",
"license": "MIT",
"engines": {
"node": ">=24.15"
},
"scripts": {
"test": "node tools/record.mjs",
"start": "node tools/serve.mjs",
"prepare-public": "node tools/prepare-public.mjs"
},
"dependencies": {
"testcontainers": "12.2.1",
"@testcontainers/postgresql": "12.2.1",
"pg": "8.23.1",
"dockerode": "5.0.1"
},
"overrides": {
"glob": "14.0.6",
"minimatch": "11.0.8"
}
}
Мини-мастерская: посмотреть события настоящего запуска
Выберите среду Node-клиента и задачу. В теме ошибок подключения доступны два варианта: неверный пароль и уже остановленный сервис. Каждая карточка объясняет, что проверить в результате. Кнопка следующего события подсвечивает очередную строку сохранённой последовательности; «Показать все» раскрывает весь путь, а «Сначала» возвращает просмотр к началу.
Подсветка не повторяет запрос к базе и не управляет Docker. Время около события записано при настоящем выполнении; оно включает особенности этого локального запуска. Сравнивать по нему производительность Windows и Linux некорректно: кеш образов, порядок запуска, диск и фоновые процессы могли отличаться. Главное здесь — последовательность и проверяемый результат.
Ниже виден фактический JSON, который можно скачать. Исходный файл выбранной задачи открывается в просмотрщике; доступны README, инфраструктурные оболочки, SQL и инструкции Linux/CI. В записях нет приватных паролей и connection URI. Для своих таблиц и запросов скачайте архив и изменяйте проект в отдельной учебной среде.
Опыт 1. Поднять PostgreSQL и получить настоящий ответ
Первый сценарий создаёт PostgreSQL через специальный модуль, задаёт учебную базу и случайный пароль, ждёт готовности и подключается драйвером pg. Запрос SELECT 42 возвращает число 42. Дополнительный запрос version() показывает, что ответ дал сервер PostgreSQL, а не локальный объект JavaScript.
После выполнения функция закрывает pg.Client и удаляет собственный контейнер. Удаление дополнительно проверяется через API Docker: обращение к точному созданному ID должно вернуть 404. Такая проверка относится только к ресурсу этого запуска. Она не выполняет обход и удаление неизвестных контейнеров пользователя.
Для первого знакомства полезно проследить весь путь: start, получение адреса, connect, query, end, stop. Если тест завис, становится понятно, на каком этапе искать причину. Загрузка образа и ожидание базы отличаются от выполнения самого SQL; смешивать их в одно неопределённое «тест не работает» неудобно.
const c=await new BoundPostgres(images.postgres).withDatabase('workshop').withUsername('demo').withPassword(randomBytes(18).toString('hex')).withLabels(labels).start();
created.push(c.getId());return c;
}
Случайные порты: 5432 внутри не означает 5432 снаружи
Внутри PostgreSQL-контейнера используется обычный порт 5432. Внешний порт выделяет Docker, чтобы несколько тестов не занимали один и тот же адрес. Код получает mappedPort после запуска. В мастерской показаны обе стороны, поэтому можно увидеть разницу, не читая Docker inspect вручную.
Нельзя заранее записать localhost:5432 в репозиторий приложения и ожидать, что он подключится к только что созданному контейнеру. Адрес и порт передаются из объекта запущенного контейнера. Точно так же в контейнере Linux-клиента localhost относится к самому клиенту, а не к хосту Docker; этот случай разобран отдельно ниже.
Наш небольшой lifecycle extension задаёт HostIp для тестовых сервисов: loopback 127.0.0.1 для обоих проверенных способов запуска. Номер порта остаётся случайным. Это локальная обёртка закреплённой версии библиотеки, которую нужно перепроверять при её обновлении, а не универсальная настройка любого Docker runtime.
// Lifecycle extension of pinned Testcontainers 12.2.1. Never bind to a public interface.
const ip='127.0.0.1';
for(const entries of Object.values(owner.hostConfig.PortBindings||{}))for(const entry of entries)entry.HostIp=ip;
}
Опыт 2. Дождаться готовности приложения, а не просто сокета
HTTP-фикстура сразу открывает порт, но первые 900 миллисекунд отвечает на /health статусом 503. Затем состояние ready становится true и ответ меняется на 200. Такой небольшой сервис показывает распространённую ситуацию: процесс уже слушает TCP, но приложение ещё не готово обслуживать полезный запрос.
Testcontainers использует Wait.forHttp с ожидаемым 200. После завершения ожидания сценарий делает ещё один самостоятельный запрос и проверяет тело ответа. В результате ready=true, а счётчик healthRequests показывает обращения к endpoint. Тест не делает фиксированный sleep перед рабочим запросом: задержка находится внутри учебного сервиса и нужна для демонстрации различия.
Для своей системы выберите сигнал, который действительно означает готовность. Открытый порт, строка в журнале и успешный HTTP health-check проверяют разные свойства. Не делайте readiness зависимым от случайной внешней системы без понятного таймаута: тогда запуск теста станет непредсказуемым. Варианты ожидания описаны в официальной документации.
import {createServer} from 'node:http';
let ready=false,healthRequests=0;
setTimeout(()=>{ready=true;},900);
createServer((req,res)=>{
if(req.url==='/health'){
healthRequests++;
res.writeHead(ready?200:503,{'Content-Type':'application/json'});
res.end(JSON.stringify({ready,healthRequests}));return;
}
res.writeHead(404).end();
}).listen(3000,'0.0.0.0',()=>console.log('HTTP socket open; readiness follows separately'));
Настроить ожидание и ограничить время старта
В readyService задаётся конкретный endpoint, внутренний порт и код статуса. Startup timeout ограничивает ожидание. Если приложение никогда не перейдёт в ready, тест должен завершиться ошибкой, а не ждать бесконечно. Время старта включает реальную работу Docker и сервиса, поэтому разумный предел зависит от размера образа и условий CI.
Не увеличивайте timeout автоматически после каждого падения. Сначала посмотрите, стартует ли контейнер, доступен ли адрес и что отвечает /health. Неверный путь, неправильный порт или постоянный 500 не исправляются дополнительной минутой ожидания. Увеличение полезно только тогда, когда нормальная проверенная инициализация действительно занимает больше времени.
В этом проекте отдельная HTTP-фикстура копируется в контейнер через API. Ей не нужен bind mount с путём Windows внутри Linux. Это упрощает повторение в разных средах и сохраняет небольшую границу: в контейнер передаётся только авторский учебный файл, а не весь рабочий каталог пользователя.
const content=await readFile(new URL('../services/ready.mjs',import.meta.url),'utf8');
const c=await new BoundGeneric(images.node).withLabels(labels).withExposedPorts(3000).withCopyContentToContainer([{content,target:'/ready.mjs'}]).withCommand(['node','/ready.mjs']).withWaitStrategy(Wait.forHttp('/health',3000).forStatusCode(200)).withStartupTimeout(30000).start();
created.push(c.getId());return c;
}
Опыт 3. Создать схему и пройти CRUD
Сценарий создаёт таблицу orders, вставляет заказ, читает его, меняет сумму и удаляет строку. В записи видны результат вставки, состояние после UPDATE и пустой список после DELETE. Это небольшая законченная проверка доступа к данным, которую можно адаптировать к репозиторию собственного API.
Таблица содержит первичный ключ, обязательные поля, ограничение положительной суммы и уникальный reference. Эти правила выполняет сама база. Если код приложения передаст неверные данные, тест увидит настоящий SQLSTATE. Подмена pg.query, возвращающая заранее подготовленную строку, такого поведения без отдельного ручного моделирования не покажет.
В реальном проекте вместо учебного migrate вызывайте тот же механизм миграций, который готовит схему приложения. Иначе тест может проверять одну таблицу, а deployment создавать другую. Для большой схемы выделяйте осмысленный набор миграций и фикстур, сохраняя связь с реальной версией кода.
await client.query(`CREATE TABLE orders (
id integer PRIMARY KEY,
customer text NOT NULL,
amount integer NOT NULL CHECK (amount > 0),
reference text NOT NULL UNIQUE
)`);
}
Параметризованный запрос и значение с апострофом
В заказе используется имя Анна O’Neil с апострофом. Оно передаётся отдельным параметром, а не вставляется в SQL строковой склейкой. После записи тест проверяет, что значение сохранилось без искажения. Это простой пример, который помогает обнаружить неправильную сборку запроса ещё до появления необычного имени в рабочей базе.
Параметры решают задачу передачи значений. Имена таблиц и колонок не превращаются автоматически в безопасные параметры $1. В мастерской SQL-структура фиксирована кодом, а данные передаются через массив. Если приложение строит динамический ORDER BY или выбирает таблицу, отдельно ограничивайте допустимые идентификаторы.
Суммы здесь представлены целыми учебными числами, а ключи заданы явно. Статья не моделирует полноценную денежную систему, конкурентное резервирование товара или генерацию бизнес-номера. Для таких требований понадобятся дополнительные сценарии. Принцип безопасной передачи значений объяснён в документации node-postgres.
return (await client.query('INSERT INTO orders(id,customer,amount,reference) VALUES($1,$2,$3,$4) RETURNING id,customer,amount,reference',[order.id,order.customer,order.amount,order.reference])).rows[0];
}
Опыт 4. Проверить откат после частично выполненной работы
Сначала в таблицу записывается заказ с суммой 100. В транзакции код меняет сумму на 999, затем пытается добавить другой заказ с уже занятым reference. PostgreSQL возвращает SQLSTATE 23505. Оболочка transaction выполняет ROLLBACK, и итоговая запись снова содержит сумму 100.
Тест проверяет одновременно причину отказа, возвращённое значение и отсутствие второй строки. Проверка только класса исключения была бы слабее: операция могла бросить ошибку, но оставить частичное изменение. Для бизнес-процесса важен именно итог состояния. Это особенно заметно при переводах между счетами, создании заказа и связанных строках документа.
Все команды транзакции выполняются через один и тот же pg.Client. При использовании пула сначала получите конкретный клиент и работайте через него до COMMIT или ROLLBACK. Несвязанные pool.query могут попадать на разные соединения. В проекте этот риск исключён простой явной передачей client в операцию.
export async function transaction(client,action){
await client.query('BEGIN');
try{const result=await action();await client.query('COMMIT');return result;}
catch(error){await client.query('ROLLBACK');throw error;}
}
Опыт 5. Ограничение базы и восстановление после отказа
В следующем сценарии отрицательная сумма нарушает CHECK. База возвращает 23514, а список заказов остаётся пустым. После этого корректная вставка проходит через то же соединение. Такой опыт показывает и отказ, и возможность продолжить работу после конкретной ошибки вне открытой транзакции.
Нельзя переносить это поведение бездумно на ошибку внутри транзакции: там до восстановления обычно требуется ROLLBACK. Поэтому сценарии CHECK и rollback разделены. Читатель видит, что одинаковое слово «ошибка SQL» не описывает всё состояние соединения и данных. Контекст выполнения важен для правильной обработки.
Ограничения базы дополняют проверку формы и API. Даже если браузер запретил отрицательное число, данные могут прийти из импорта или другой версии сервиса. Тест реального CHECK полезен именно на этой границе. При изменении правила сначала согласуйте миграцию и обработку ожидаемого SQLSTATE в приложении.
// Фрагмент массива scenarios
{id:'constraints',title:'Ограничения самой базы',source:'src/repository.mjs',async run(t){
return await withDatabase(async(client)=>{await migrate(client);let code;try{await insertOrder(client,{id:1,customer:'Неверная сумма',amount:-10,reference:'DEMO-X'});}catch(e){code=e.code;}t.check('CHECK constraint rejects',code==='23514');const rows=await listOrders(client);t.check('No bad row',rows.length===0);await insertOrder(client,{id:1,customer:'Исправлено',amount:300,reference:'DEMO-OK'});t.check('Recovery without reconnect',(await listOrders(client)).length===1);t.event('CHECK отказал, следующий корректный INSERT прошёл');return {expectedSqlState:code,invalidRows:rows,afterRecovery:await listOrders(client)};});
}},
Опыт 6. Неверный пароль — это не недоступный сервер
В варианте wrong-password контейнер успешно создан и готов, но отдельный pg.Client получает намеренно неправильный пароль. PostgreSQL отвечает SQLSTATE 28P01. Значит, сеть и сервер доступны достаточно для попытки аутентификации; искать причину только в закрытом порту было бы ошибкой.
Правильный пароль генерируется случайно в памяти для конкретного контейнера. В публичный JSON не попадают ни он, ни connection URI. Сохранён только безопасный результат: подключение не установлено, код отказа подтверждён. Указанный в исходнике неправильный пароль — вымышленная отрицательная фикстура, которая не открывает никакую рабочую систему.
Для своего приложения различайте отказ авторизации, сетевую недоступность и таймаут. Они могут требовать разных сообщений в журнале и разных действий оператора. Не повторяйте бесконечно запрос с ошибочными credentials, выдавая это за временную сетевую проблему. Сам retry должен иметь ограничение и понятную причину.
// Фрагмент массива scenarios
{id:'wrong-password',title:'Отказ аутентификации',source:'src/scenarios.mjs',async run(t){
const c=await postgres();const client=new pg.Client({...config(c),password:'intentionally-wrong-demo-password'});client.on('error',()=>{});let code;try{try{await client.connect();}catch(e){code=e.code;}t.check('Authentication rejected',code==='28P01');t.event('Доступ отклонён самим PostgreSQL');return {expectedSqlState:code,connected:false,passwordPublished:false};}finally{await client.end();await stop(c);}
}},
Остановленный сервис: новый запрос действительно не подключается
Вариант stopped-service сначала поднимает PostgreSQL, сохраняет параметры соединения и удаляет контейнер. API Docker подтверждает отсутствие точного ID. Только после этого создаётся новый клиент. Его подключение завершается сетевой ошибкой, которая фиксируется в результате.
Это контролируемый тест недоступности после остановки, а не имитация отказа диска или сложного сетевого разделения. Код ошибки может зависеть от ОС и сетевой среды; проект проверяет сам факт отказа и подтверждённое удаление сервиса. Нельзя объявлять по этому примеру проверенной автоматическую отказоустойчивость production-базы.
Такой сценарий полезен, чтобы увидеть, как приложение ограничивает время подключения и не оставляет зависший запрос. Дальнейшие проверки могут включать повтор после восстановления, понятный ответ API и отсутствие частично сохранённого результата. Добавляйте их под конкретный контракт сервиса, а не под абстрактное обещание пережить любую аварию.
// Фрагмент массива scenarios
{id:'stopped-service',title:'Подключение после остановки',source:'src/scenarios.mjs',async run(t){
const c=await postgres();const settings=config(c);await stop(c);t.event('Контейнер удалён, API Docker подтвердил 404');const client=new pg.Client(settings);client.on('error',()=>{});let code;try{try{await client.connect();}catch(e){code=e.code||e.name;}t.check('Connection rejected',!!code);t.check('Removed container recorded',removed.includes(c.getId()));t.event('Новое подключение завершилось ошибкой');return {errorCode:code,connected:false,removed:true};}finally{await client.end();}
}},
Опыт 7. Параллельные тесты не делят одну таблицу
Две функции запускаются одновременно и получают отдельные PostgreSQL-контейнеры. В обеих базах создаётся orders и записывается id=1 с одинаковым reference. В левой базе customer равен «Левая база», в правой — «Правая база». Разные mappedPort и результаты подтверждают, что данные не пересеклись.
Такое разделение устраняет распространённый источник случайных падений: один тест удалил строку, которую в этот момент проверял другой. Но отдельный контейнер для каждой мелкой операции может оказаться слишком дорогим. В рабочем наборе разумно выбирать границу изоляции: suite, отдельная база или схема, иногда транзакция с откатом. Каждый вариант требует своих ограничений.
В проекте используется Promise.allSettled, чтобы дождаться обеих ветвей даже при ошибке одной. Их finally успевают закрыть клиентов и удалить ресурсы. Простой ранний выход после первого rejected без внимания к другой ветви мог бы оставить незавершённую работу. Параллелизм полезен только вместе с понятным временем жизни каждого ресурса.
// Фрагмент массива scenarios
{id:'parallel',title:'Два независимых теста одновременно',source:'src/scenarios.mjs',async run(t){
const settled=await Promise.allSettled(['Левая база','Правая база'].map(name=>withDatabase(async(client,c)=>{await migrate(client);await insertOrder(client,{id:1,customer:name,amount:100,reference:'SAME-ID'});return {endpoint:endpoint(c),rows:await listOrders(client)};})));const failure=settled.find(x=>x.status==='rejected');if(failure)throw failure.reason;const results=settled.map(x=>x.value);t.check('Different mapped ports',results[0].endpoint.mappedPort!==results[1].endpoint.mappedPort);t.check('Left data isolated',results[0].rows[0].customer==='Левая база');t.check('Right data isolated',results[1].rows[0].customer==='Правая база');t.check('One row per database',results.every(x=>x.rows.length===1));t.event('Одинаковые id/reference существуют независимо');return {databases:results};
}},
Опыт 8. Намеренное исключение и обязательная очистка
Последний опыт выполняет SELECT 1, затем специально бросает EXPECTED_DEMO_FAILURE. Обёртка проходит finally: закрывает клиент, удаляет контейнер и проверяет Docker404 для его ID. Сценарий затем убеждается, что ресурс действительно удалён и список с label текущего запуска пуст.
Это важная проверка самого тестового стенда. Зелёный рабочий запрос ещё не означает, что после него не остались процессы, volumes или порты. Если каждый запуск оставляет ресурс, через некоторое время тесты начнут падать по причинам, которые не связаны с приложением: нехватка диска, память или неожиданные старые данные.
Очистка должна быть узкой. В исходниках нет system prune, удаления всех контейнеров или поиска чужих имён по приблизительной подстроке. Используются объекты, которые создал текущий запуск, и точная метка runId. Это позволяет выполнять проект рядом с другими учебными сервисами, сохраняя границы владения ресурсами.
await c.stop({remove:true,removeVolumes:true});
try{await docker.getContainer(c.getId()).inspect();throw Error('Own container still exists');}catch(e){if(e.statusCode!==404)throw e;}
removed.push(c.getId());
}
export async function withDatabase(action){
const c=await postgres();let client;
try{client=await connect(c);return await action(client,c);}finally{try{if(client)await client.end();}finally{await stop(c);}}
}
Ryuk — страховка, а finally остаётся основным путём
Testcontainers использует вспомогательный механизм очистки ресурсов. В проекте он оставлен включённым. При нормальном завершении основные контейнеры останавливаются явно, а отсутствие собственных ID проверяется отдельно. Не нужно отключать автоматическую очистку только ради того, чтобы увидеть контейнер в интерфейсе Docker подольше.
Если процесс теста аварийно завершается, поведение зависит от доступности Docker и вспомогательного механизма. Наш опыт проверяет управляемое исключение внутри работающего Node-процесса. Он не подтверждает очистку после внезапного выключения компьютера или недоступного daemon. Эти границы лучше указать прямо, чем считать любое слово cleanup полной гарантией.
Для диагностики можно посмотреть контейнеры с собственным label, изучить их состояние и журнал. Удаление должно относиться к конкретному тестовому запуску. В общей среде CI особенно опасны команды, которые чистят всё на хосте, поскольку там могут выполняться задачи других пользователей или параллельные jobs.
Windows: Docker Desktop, Node и первый запуск
В Windows нужен работающий Docker Desktop в режиме Linux-контейнеров и подходящий Node. Перед тестом проверьте текущий Docker context и OSType. Если context указывает на удалённый рабочий сервер, не запускайте учебный проект до выбора собственной среды. Команда docker info должна успешно обращаться к daemon, а не только показывать наличие CLI.
В распакованной папке выполните npm ci, затем npm test. Первый запуск может дольше загружать образы; последующие используют кеш. Сообщения сценариев помогают видеть продвижение. Итоговая запись появляется в public/records/windows.json. Случайные порты и времена в новом запуске будут отличаться от опубликованной записи — это ожидаемо.
Для одной лишь мастерской Docker не нужен: npm start раздаёт готовую статическую папку на loopback. Эта команда не повторяет интеграционные тесты. Такое разделение удобно для читателя, который сначала хочет изучить результат, а затем подготовить окружение для самостоятельного запуска.
node --version
docker context show
docker info --format '{{.OSType}}'
npm ci --ignore-scripts
npm test
Linux: запуск непосредственно на хосте
На отдельном Linux-хосте с Node и Docker команды почти те же. Приложение теста обращается к локальному engine, а PostgreSQL доступен через назначенный loopback-порт. Исходники и package-lock переносятся как файлы проекта; node_modules из Windows копировать не нужно. Установку зависимостей повторяет npm ci в своей среде.
Наличие доступа к Docker socket — существенная часть возможностей процесса. Не выдавайте его публичному веб-приложению или недоверенному коду только ради запуска теста. Для CI используйте выделенный runner, а для изучения — собственную локальную среду. Поддерживаемые runtime и особенности описаны в документации Testcontainers.
Если Docker не отвечает, сначала выясните состояние daemon, context и права текущего пользователя. Ошибка запуска Testcontainers не обязательно означает проблему npm-пакета. Не исправляйте её отключением защит или открытием незащищённого TCP API. Настройка среды должна сохранять границу между тестовыми ресурсами и рабочими сервисами.
node --version
docker context show
docker info --format '{{.OSType}}'
npm ci --ignore-scripts
npm test
Linux-клиент в контейнере: socket и правильный адрес хоста
Для дополнительной проверки Node запускается внутри Linux-контейнера. Он управляет соседними контейнерами через socket собственного Docker. Это не отдельный вложенный daemon. Поэтому localhost из Node-контейнера не ведёт к опубликованному порту PostgreSQL на хосте: для проверенного Docker Desktop используется специальный адрес host.docker.internal.
В инструкции Docker Desktop адрес host.docker.internal передаётся как TESTCONTAINERS_HOST_OVERRIDE. Тестовые сервисы продолжают слушать только loopback хоста. Это проверенный механизм Docker Desktop, а не универсальный рецепт для обычного Linux engine или Docker-in-Docker. На обычном Linux/VPS запускайте Node непосредственно на хосте либо отдельно проектируйте изолированную сеть runner.
Такой способ нужен именно для испытания Linux Node-клиента. На обычном Linux runner проще выполнить npm test непосредственно. Подключение socket даёт контейнеру административные возможности в рамках Docker-хоста, поэтому этот рецепт предназначен только для доверенного кода и отдельной учебной или CI-среды.
docker build -t aen-testcontainers-client .
docker run --rm --name aen-testcontainers-client-run \
--mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
--mount type=bind,src="$(pwd)/public/records",dst=/app/public/records \
-e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
aen-testcontainers-client
CI: повторяемая среда и полезные артефакты
В CI выполняются установка по lock, проверка доступности Docker, тесты и сохранение отчёта. Лимит job должен учитывать загрузку образов и инициализацию сервисов. Ошибка отдельной проверки завершает процесс ненулевым кодом, поэтому следующий этап deployment не должен продолжаться как будто всё прошло успешно.
Сохраняйте артефакты, которые помогают диагностировать причину: название сценария, версии, безопасные параметры endpoint, SQLSTATE, результат и факт очистки. Не публикуйте пароли, production connection strings и клиентские выгрузки. В нашей записи используются вымышленные заказы и не сохраняется правильный пароль PostgreSQL.
Недоверенный pull request нельзя бездумно запускать на runner с Docker socket, секретами deployment и доступом к рабочей сети. Используйте изолированное окружение и отдельную политику доверия. Успешный интеграционный тест полезен как этап доставки, но он не отменяет контроль доступа самого CI и границы полномочий запускаемого кода.
set -eu
npm ci --ignore-scripts
docker info --format '{{.OSType}}'
npm test
npm run prepare-public
VPS: где выполняются тесты и где размещается мастерская
На VPS можно выделить отдельную среду для интеграционных тестов или использовать CI runner. Она не должна подключаться к production-базе вместо временного PostgreSQL. Успешное создание пустой таблицы не гарантирует безопасную миграцию большой существующей базы с данными, индексами и параллельными запросами пользователей.
Публичной мастерской достаточно статической папки public, которую раздаёт Nginx или Caddy. Ей не нужен Docker socket, постоянная база или Node-процесс для выполнения тестов посетителей. Кнопки работают с JSON-записями, а полный проект скачивается отдельно. Благодаря этому публикация остаётся обычным безопасным статическим материалом сайта.
Для развёртывания собственных сервисов полезны наши материалы о Docker Compose, Nginx и Caddy. Здесь же задача — проверить взаимодействие приложения с зависимостью до её подключения к рабочей среде.
Фикстуры и границы достоверности теста
Учебная база содержит маленькую таблицу и несколько специально выбранных значений. Апостроф проверяет передачу параметра, одинаковый reference создаёт конфликт UNIQUE, отрицательная сумма нарушает CHECK. Такие компактные фикстуры помогают понять причину результата без большого массива случайных данных.
Для своего приложения дополните их характерными граничными случаями: пустым обязательным полем, необычным Unicode, несколькими связанными строками, повторной командой и конфликтом конкурентных операций. Не заменяйте эти сценарии одной большой production-выгрузкой: она может содержать лишние личные данные и затруднять воспроизведение конкретной ошибки.
Контейнер помогает получить настоящий сервис, но реалистичность проверки определяется самим сценарием. Здесь нет HA, репликации, TLS PostgreSQL, нагрузочного профиля или аварии диска. Эти свойства требуют отдельных стендов и утверждений. Полезный тест точно говорит, что подтвердил, и не обещает заодно всё поведение production-системы.
Что подтверждено выполнением проекта
Проект создаёт десять собственных контейнеров на один полный запуск и удаляет их. Девять записей покрывают восемь тем, потому что ошибки подключения разделены на два варианта. Проверки подтверждают реальные ответы PostgreSQL и HTTP, содержимое строк после операций, SQLSTATE, разные порты параллельных баз и отсутствие ресурсов текущего runId в конце.
Выполняются Windows и Linux Node-клиенты против локального Linux Docker engine. Источники связаны с записью через SHA-256. Случайные mappedPort, длительности и некоторые сетевые коды могут отличаться между запусками. Поэтому сравниваются осмысленные результаты, а не побайтовое равенство всего отчёта с временем и динамическими адресами.
Браузерная мастерская проверяется отдельно: чтение записей, переключение задач, подсветка событий, скачивание JSON, просмотр исходников и мобильная ширина. Успешный Node-тест сам по себе не доказывает удобство страницы. Аналогично красивый интерфейс с записью не заменяет фактический запуск контейнеров и проверку исходного проекта.
Скачать проект и добавить свой первый интеграционный тест
В архиве находятся npm lock, образы по digest, SQL-репозиторий, сценарии, оболочки запуска и очистки, Dockerfile Linux-клиента, готовая мастерская и инструкции Windows/Linux/CI. Авторский код распространяется по MIT. Список сторонних лицензий находится рядом со статической страницей; node_modules устанавливается через npm ci и не включается в архив.
Выберите одну важную операцию своего приложения и сформулируйте ожидаемый итог данных. Подготовьте минимальную схему, успешный случай и один характерный отказ. Подключите реальный сервис, передайте адрес из Testcontainers и завершите сценарий проверкой очистки. Затем повторите запуск из чистого checkout на другой среде, чтобы найти скрытые зависимости от вашего компьютера.
Первичные источники: первый запуск, модуль PostgreSQL, контейнеры и жизненный цикл, сети, транзакции pg. Сопоставляйте документацию с закреплённой версией и обновляйте исходники вместе с проверками.


