Навигация

Тестирование Node-приложений

Тесты в Node-сервисе появляются поздно: сначала кажется, что быстрее проверить руками, а через полгода любой рефакторинг превращается в лотерею. При этом плохие тесты хуже их отсутствия — они зелёные, ничего не проверяют и создают ложное спокойствие. Разберём, как собрать набор тестов Node-приложения: от node:test и supertest до testcontainers, моков времени и борьбы с флейками.

Содержание

  1. Зачем сервису тесты
  2. Пирамида: unit, интеграционные, e2e
  3. Раннер: node:test, Vitest, Jest
  4. Первый тест и изоляция
  5. Приложение как фабрика
  6. HTTP-тесты без порта: supertest
  7. Тестовые двойники
  8. Моки модулей и внешнего HTTP
  9. Время, случайность и таймеры
  10. Интеграционные тесты с базой
  11. Как тестировать ошибки
  12. E2E и что в нём проверять
  13. Покрытие и его пределы
  14. Флейки и скорость набора
  15. Практика: TaskFlow
  16. Частые ошибки
  17. Ключевые тезисы для интервью
  18. Заключение
  19. Полезные ссылки

Зачем сервису тесты

У тестов три разные работы, и путать их дорого:

  • Защита от регрессий. Тест фиксирует поведение, которое уже нужно бизнесу, и падает, когда кто-то его ломает. Это единственная причина, по которой тест стоит держать в репозитории.
  • Документация. Хорошо названный тест читается как список требований: «нельзя переместить задачу в чужой проект», «повторный вебхук не создаёт второй платёж».
  • Дизайн. Код, который трудно протестировать, обычно плохо развязан: жёстко зашитые зависимости, побочные эффекты в конструкторе, состояние в модуле. Боль от написания теста — ранний сигнал о проблемах архитектуры.

Что тест не делает: не доказывает отсутствие багов и не заменяет проверку в проде. Он покрывает только те сценарии, о которых автор подумал, — а инциденты приходят из тех, о которых он не подумал.

Отсюда практическое правило: тест должен быть быстрым, детерминированным и падать по одной понятной причине. Если тест падает через раз или требует ручной подготовки, его перестают запускать, и он превращается в мёртвый код.


Пирамида: unit, интеграционные, e2e

Уровни различаются тем, сколько настоящего кода выполняется и сколько стоит прогон.

УровеньЧто реальноЧто подмененоСкоростьЧто ловит
Unitодна функция или модульвсё внешнеемиллисекундылогика, ветки, граничные случаи
Интеграционныйнесколько слоёв сервисавнешний мир, иногда БДдесятки–сотни мссвязки слоёв, контракты, SQL
E2Eвесь сервис и его зависимостиничегосекундысценарии пользователя, конфигурация

Для Node-бэкенда полезна не классическая «пирамида», а её вариант с толстым средним слоем: юнит-тестов много, интеграционных почти столько же, e2e — единицы. Причина в том, что главные ошибки бэкенда живут на стыках: маршрут не пробросил ошибку, middleware не поставил заголовок, репозиторий перепутал порядок параметров, схема базы не совпала с кодом. Юнит-тесты такие стыки не видят по определению.

Практическое распределение для сервиса на десять эндпоинтов:

  • Unit — бизнес-правила: расчёт прав, переходы статусов, парсинг и форматирование, чистые функции.
  • Интеграционные — каждый маршрут хотя бы одним успешным и одним ошибочным запросом, плюс запросы к реальной базе.
  • E2E — два-три сквозных сценария: регистрация и вход, основной happy path, критичная операция с деньгами или правами.

Обратная крайность — тестировать всё только через HTTP. Такой набор медленный, а при падении теста непонятно, что сломалось: маршрут, валидация или SQL. Если ошибка воспроизводится на уровне функции, её и надо ловить на уровне функции.


Раннер: node:test, Vitest, Jest

Начиная с Node 18 встроенный модуль node:test даёт полноценный раннер без зависимостей: test, describe, before/after, mock, покрытие и экспериментальные снапшоты.

node:testVitestJest
Запускnode --testvitestjest
ESMнативнонативнонужна конфигурация
Моки модулейmock.module (экспериментальный)vi.mockjest.mock
Фейковые таймерыt.mock.timersvi.useFakeTimersjest.useFakeTimers
Покрытие--experimental-test-coveragev8 или istanbulistanbul
Сильная сторонаноль зависимостей, тот же рантаймскорость, DX, TypeScriptэкосистема и плагины

Когда что выбирать:

  • node:test — библиотеки, CLI, небольшие сервисы и всё, где не хочется тянуть тестовый стек в прод-зависимости. Запуск совпадает с продовым рантаймом, поэтому «работает в тестах, падает в Node» почти не случается.
  • Vitest — TypeScript, ESM и фронтенд рядом с бэкендом в одном монорепо: конфигурация минимальна, watch-режим быстрый, моки модулей удобные.
  • Jest — существующий проект, где он уже настроен, или специфические плагины. Для нового ESM-сервиса на Node 22+ обычно нет причин начинать с него.

Встроенный раннер ищет файлы по шаблонам **/*.test.js, **/test-*.js и в каталогах test/, а явные пути и glob’ы принимает аргументом:

{
  "scripts": {
    "test": "node --test",
    "test:unit": "node --test tests/unit",
    "test:watch": "node --test --watch",
    "test:coverage": "node --test --experimental-test-coverage"
  }
}

Полезные флаги: --test-concurrency=1 для тестов с общей базой, --test-timeout=60000 для медленных контейнеров, --test-reporter=spec для читаемого вывода в терминале и --test-reporter=junit для CI.


Первый тест и изоляция

Минимальный тест на node:test выглядит так:

// tests/unit/tasks.service.test.js
import test from 'node:test';
import assert from 'node:assert/strict';
import { createTasksService } from '../../src/services/tasks.js';

test('create() trims the title and marks the task as not done', async () => {
  const service = createTasksService({ repo: createFakeRepo() });

  const task = await service.create({ ownerId: 'u1', title: '  write tests  ' });

  assert.equal(task.title, 'write tests');
  assert.equal(task.done, false);
});

Изоляция — главное свойство, которое отличает работающий набор от набора, который «иногда падает». Требования простые:

  • Никакого состояния между тестами. Каждый тест сам создаёт нужные объекты. Общая переменная в модуле — прямой путь к зависимости от порядка запуска.
  • Уникальные данные. Идентификаторы и имена генерируют внутри теста (randomUUID()), а не берут из заранее засеянной строки, которую другой тест может удалить.
  • Очистка в after/t.after. Контейнеры, серверы, таймеры и подписки закрываются даже при падении теста.
  • Один смысл на тест. Если в названии есть «и», скорее всего, это два теста.

Именно на этом ломается пример из статьи «Express и middleware»: массив tasks объявлен в модуле роутера, поэтому второй тест видит задачи первого. Тест проходит в одиночку и падает в общем прогоне — классическая флейка, которую потом «лечат» ретраями.


Приложение как фабрика

Чтобы тестировать HTTP-слой, приложение должно собираться без побочных эффектов. server.js с app.listen() для этого не годится: он занимает порт, ставит обработчики сигналов и не даёт подставить зависимости.

Разделение уже описано в статье «Express и middleware», но для тестов одного разделения мало — нужна фабрика:

// src/app.js
import express from 'express';
import { createTasksService } from './services/tasks.js';
import { createTasksRouter } from './routes/tasks.js';

export function createApp({ repo, logger = console } = {}) {
  const tasks = createTasksService({ repo });
  const app = express();

  app.disable('x-powered-by');
  app.use(express.json({ limit: '16kb' }));
  app.get('/health', (req, res) => res.json({ ok: true }));
  app.use('/tasks', createTasksRouter({ tasks }));

  app.use((req, res) => {
    res.status(404).json({ error: 'not found' });
  });

  app.use((err, req, res, next) => {
    if (res.headersSent) return next(err);

    const status = err.status ?? 500;
    if (status >= 500) logger.error({ err }, 'request failed');

    res.status(status).json({
      error: status >= 500 ? 'internal error' : err.message,
    });
  });

  return app;
}
// src/server.js
import { createApp } from './app.js';
import { pool } from './db/pool.js';
import { createPgTasksRepo } from './repositories/tasks.js';

const app = createApp({ repo: createPgTasksRepo(pool) });
app.listen(3000);

Фабрика даёт три вещи: тест подставляет фейковый репозиторий, тест на реальной базе — настоящий, а прод — тот, что нужен. Плюс createApp() можно вызывать сколько угодно раз в одном процессе, и каждый экземпляр будет независимым.

Ту же идею полезно применить шире: зависимости (часы, генератор id, HTTP-клиент, логгер) передаются аргументами или создаются в композиционном корне. Чем меньше модуль знает о конкретных реализациях, тем дешевле тест.


HTTP-тесты без порта: supertest

supertest берёт приложение (функцию (req, res) или http.Server), сам поднимает его на свободном порту, отправляет запрос и закрывает сервер. Тесту не нужны ни фиксированный порт, ни ручной listen.

// tests/integration/tasks.api.test.js
import test from 'node:test';
import assert from 'node:assert/strict';
import request from 'supertest';
import { createApp } from '../../src/app.js';
import { createMemoryRepo } from '../helpers/memory-repo.js';

test('POST /tasks creates a task', async () => {
  const app = createApp({ repo: createMemoryRepo() });

  const res = await request(app)
    .post('/tasks')
    .send({ title: 'Write tests' })
    .expect(201);

  assert.equal(res.body.title, 'Write tests');
  assert.equal(res.body.done, false);
});

test('POST /tasks rejects an empty title', async () => {
  const app = createApp({ repo: createMemoryRepo() });

  const res = await request(app)
    .post('/tasks')
    .send({ title: '   ' })
    .expect(422);

  assert.equal(res.body.error, 'title is required');
});

Что даёт такой тест:

  • проверяется весь HTTP-слой: разбор тела, валидация из статьи «Конфигурация и валидация», маршрут, сериализация ответа;
  • ошибки маршрута проходят через error middleware, поэтому проверяется и формат { error };
  • заголовки доступны через res.headers, а сырое тело — через res.text, что нужно для content-type, ETag и потоковых ответов.

Без зависимости то же самое делается вручную:

import { once } from 'node:events';

const server = app.listen(0);
await once(server, 'listening');
const { port } = server.address();

try {
  const res = await fetch(`http://127.0.0.1:${port}/tasks`);
  assert.equal(res.status, 200);
} finally {
  await new Promise((resolve) => server.close(resolve));
}

listen(0) просит у ОС свободный порт, поэтому параллельные прогоны не конфликтуют. Именно этого не умеет server.js с зашитым 3000, и именно поэтому приложение импортируют из app.js.

Отдельно проверяют то, что легко пропустить: неизвестный маршрут (404), неверный content-type (415), тело больше лимита (413), битый JSON (400). Это дешёвые тесты, которые ловят регрессии в middleware.


Тестовые двойники

Термины, которые на интервью спрашивают именно в этом виде:

ТипЧто делает
Stubвозвращает заранее заданный ответ
Spyзаписывает вызовы, но выполняет настоящий код
Fakeрабочая упрощённая реализация (in-memory репозиторий)
Mockобъект с ожиданиями: «этот вызов должен произойти»

Правило выбора простое: подменяйте то, чем не управляете, и не подменяйте то, что тестируете. Сеть, время, случайность, файловая система, платёжный SDK, очередь — кандидаты на двойника. Свои сервисы и репозитории — нет, если тест как раз про их связку.

Фейк предпочтительнее мока, потому что не привязан к последовательности вызовов:

// tests/helpers/memory-repo.js
export function createMemoryRepo(initial = []) {
  const rows = [...initial];

  return {
    rows,
    async listByOwner(ownerId) {
      return rows.filter((task) => task.ownerId === ownerId);
    },
    async findById(id) {
      return rows.find((task) => task.id === id) ?? null;
    },
    async insert(task) {
      rows.push(task);
      return task;
    },
  };
}

Тест с таким фейком переживёт рефакторинг сервиса: если внутри появится лишний findById, тест не упадёт, а поведение останется проверенным. Мок с toHaveBeenCalledTimes(1) упал бы, хотя контракт не изменился.

Обратная сторона — фейк может разойтись с реальной реализацией. Поэтому поведение, которое важно (уникальность, сортировка, фильтры), дополнительно проверяют интеграционным тестом на настоящей базе.

В node:test шпионы и подмены делаются через t.mock:

test('create() writes an audit entry', async (t) => {
  const audit = { log: async () => {} };
  const spy = t.mock.method(audit, 'log');
  const service = createTasksService({ repo: createFakeRepo(), audit });

  await service.create({ ownerId: 'u1', title: 'Task' });

  assert.equal(spy.mock.callCount(), 1);
  assert.equal(spy.mock.calls[0].arguments[0].type, 'task.created');
});

t.mock.method подменяет метод на время теста и восстанавливает его автоматически. Аналоги в Vitest — vi.spyOn и vi.fn.


Моки модулей и внешнего HTTP

Мок модуля подменяет импорт целиком:

// Vitest
import { vi, test, expect } from 'vitest';

vi.mock('../src/lib/mailer.js', () => ({
  sendMail: vi.fn(async () => ({ id: 'stub' })),
}));

В node:test для этого есть mock.module(), но он экспериментальный и требует флага --experimental-test-module-mocks. Обе конструкции — инструмент последней необходимости: они связывают тест с путём импорта и ломаются при любом рефакторинге файлов. Если зависимость можно передать параметром, передавайте параметром.

Внешний HTTP удобнее подменять на уровне транспорта, а не модуля: тогда реально выполняются сериализация, разбор ответа, обработка статусов и таймаутов. У fetch в Node под капотом undici, поэтому работает MockAgent:

// tests/integration/users.client.test.js
import test, { after, before } from 'node:test';
import assert from 'node:assert/strict';
import { MockAgent, setGlobalDispatcher } from 'undici';
import { getUser } from '../../src/clients/users.js';

const agent = new MockAgent();
agent.disableNetConnect();

before(() => setGlobalDispatcher(agent));
after(() => agent.close());

test('getUser maps the profile response', async () => {
  agent
    .get('https://api.example.com')
    .intercept({ path: '/users/1', method: 'GET' })
    .reply(200, { id: 1, name: 'Ada' }, { headers: { 'content-type': 'application/json' } });

  const user = await getUser('1');

  assert.equal(user.name, 'Ada');
  agent.assertNoPendingInterceptors();
});

disableNetConnect() — важная часть: если код сходит по адресу, который не замокан, тест упадёт, а не отправит настоящий запрос. Так же проверяют поведение на 500, на пустом теле, на таймауте и на неверном JSON.

Альтернатива — msw/node, который перехватывает запросы на уровне fetch и умеет переиспользовать одни и те же обработчики в тестах и в dev-режиме. Как устроены сами клиенты, таймауты и ретраи — в статье «HTTP-клиенты в Node.js».


Время, случайность и таймеры

Код, зависящий от Date.now() или setTimeout, без подготовки тестируется плохо: тест либо ждёт реальные секунды, либо проверяет неточно.

Первый способ — внедрить зависимость:

// src/services/tasks.js
import { randomUUID } from 'node:crypto';

export function createTasksService({ repo, now = () => new Date(), newId = randomUUID }) {
  return {
    async create({ ownerId, title }) {
      const task = {
        id: newId(),
        ownerId,
        title: title.trim(),
        done: false,
        createdAt: now().toISOString(),
      };
      return repo.insert(task);
    },
  };
}
test('create() sets createdAt from the clock', async () => {
  const service = createTasksService({
    repo: createFakeRepo(),
    now: () => new Date('2026-01-01T00:00:00Z'),
  });

  const task = await service.create({ ownerId: 'u1', title: 'Task' });

  assert.equal(task.createdAt, '2026-01-01T00:00:00.000Z');
});

Тот же приём работает для ретраев: если sleep — параметр, backoff проверяется мгновенно и точно:

const delays = [];

await retry(flaky, {
  retries: 2,
  baseDelay: 100,
  sleep: async (ms) => delays.push(ms),
});

assert.deepEqual(delays, [100, 200]);

Второй способ нужен, когда таймеры внутри библиотеки или кода, который менять не хочется. У node:test это t.mock.timers:

test('cache entry expires after ttl', (t) => {
  t.mock.timers.enable({ apis: ['Date'], now: 0 });
  const cache = createCache({ ttl: 1000 });

  cache.set('key', 'value');
  t.mock.timers.tick(1001);

  assert.equal(cache.get('key'), undefined);
});

Подвох фейковых таймеров — микрозадачи. tick() синхронно двигает время и запускает колбэки, но промисы внутри них разрешаются позже, поэтому после tick() иногда нужен await Promise.resolve() (в Vitest — await vi.advanceTimersByTimeAsync(ms)). Если тест «иногда» падает после фейковых таймеров, почти всегда причина в этом.

Случайность лечится так же: randomUUID и генераторы данных внедряют, а у faker фиксируют seed — тогда падение воспроизводится на тех же данных.


Интеграционные тесты с базой

Мок репозитория не проверяет SQL. Опечатка в имени колонки, неверный порядок $1/$2, отсутствующее ограничение, несовпадение типов — всё это видно только на настоящей базе.

Вариантов поднять базу три:

ВариантПлюсыМинусы
Общий стенд (dev/staging БД)ничего не настраиватьданные и схема чужие, тесты мешают друг другу
docker compose в CIпредсказуемая версия, знакомый инструментнужен wait-for-it, очистка руками
testcontainersконтейнер на прогон, случайный порт, автозакрытиенужен Docker, старт 5–20 секунд

testcontainers — самый надёжный вариант для CI, потому что каждый прогон получает чистую базу известной версии:

// tests/helpers/db.js
import { PostgreSqlContainer } from '@testcontainers/postgresql';
import { Pool } from 'pg';
import { readdir, readFile } from 'node:fs/promises';
import path from 'node:path';

let container;
let pool;

export async function startDb() {
  container = await new PostgreSqlContainer('postgres:16-alpine').start();
  pool = new Pool({ connectionString: container.getConnectionUri(), max: 4 });

  const dir = path.resolve('migrations');
  for (const file of (await readdir(dir)).sort()) {
    await pool.query(await readFile(path.join(dir, file), 'utf8'));
  }

  return pool;
}

export async function resetDb() {
  await pool.query('truncate tasks, projects cascade');
}

export async function stopDb() {
  await pool?.end();
  await container?.stop();
}
// tests/integration/tasks.repo.test.js
import test, { after, before, beforeEach } from 'node:test';
import assert from 'node:assert/strict';
import { startDb, resetDb, stopDb } from '../helpers/db.js';
import { createPgTasksRepo } from '../../src/repositories/tasks.js';

let pool;
let repo;

before(async () => {
  pool = await startDb();
  repo = createPgTasksRepo(pool);
}, { timeout: 60_000 });

beforeEach(resetDb);
after(stopDb);

test('listByOwner returns only the owner tasks, newest first', async () => {
  await repo.insert({ id: 'a', ownerId: 'u1', title: 'first', createdAt: '2026-01-01' });
  await repo.insert({ id: 'b', ownerId: 'u1', title: 'second', createdAt: '2026-01-02' });
  await repo.insert({ id: 'c', ownerId: 'u2', title: 'other', createdAt: '2026-01-03' });

  const tasks = await repo.listByOwner('u1');

  assert.deepEqual(tasks.map((task) => task.id), ['b', 'a']);
});

Ключевые решения:

  • Миграции выполняются один раз на прогон, а не перед каждым тестом: это медленно и не даёт ничего нового.
  • Очистка между тестами — truncate ... cascade или откат транзакции. Транзакция быстрее, но не работает, если код сам управляет транзакциями, поэтому truncate проще и предсказуемее.
  • Изоляция файлов. Тесты из разных файлов не должны видеть данные друг друга: либо --test-concurrency=1, либо отдельная схема/база на файл. Параллельный truncate в общем каталоге — источник флейков.
  • Пул маленький. Тест не должен открывать десятки соединений: контейнер и так ограничен.

Про пул, транзакции и параметризованные запросы, которые здесь проверяются, — статья «Доступ к базам данных».

Иногда полноценный PostgreSQL избыточен: для тестов на sqlite или pglite прогон дешевле. Но помните, что это другая база: другой SQL-диалект, другие типы, другие коды ошибок. Если прод на PostgreSQL, критические запросы проверяют на PostgreSQL.


Как тестировать ошибки

Ошибочные пути — то, что в проде стоит дороже всего, и то, что чаще всего не покрыто. Тестировать их нужно на двух уровнях.

Уровень маппинга. Ошибка драйвера подставляется фейком, и проверяется ответ API:

test('POST /projects returns 409 on a unique violation', async () => {
  const app = createApp({
    repo: {
      async insert() {
        throw Object.assign(new Error('duplicate key'), {
          code: '23505',
          constraint: 'projects_name_key',
        });
      },
    },
  });

  const res = await request(app)
    .post('/projects')
    .send({ name: 'inbox' })
    .expect(409);

  assert.equal(res.body.error, 'already exists');
  assert.equal(res.body.detail, undefined);
});

Здесь проверяются три вещи сразу: code из «Доступ к базам данных» превращается в 409, наружу не уходит текст базы, а ответ остаётся в формате error middleware.

Уровень контракта. Реальный дубль в реальной базе подтверждает, что ограничение вообще существует и даёт ожидаемый код:

test('projects.name is unique in the schema', async () => {
  await pool.query("insert into projects (id, name) values ('p1', 'inbox')");

  await assert.rejects(
    pool.query("insert into projects (id, name) values ('p2', 'inbox')"),
    (error) => error.code === '23505',
  );
});

Без второго теста можно годами держать зелёный набор и не знать, что миграция с unique не применилась.

Что ещё стоит проверить явно:

  • Таймаут запроса. set local statement_timeout = '50ms' и select pg_sleep(1) дают 57014, который приложение должно превратить в 503, а не в 500.
  • Обрыв соединения. select pg_terminate_backend(pid) или остановка контейнера — проверка, что сервис отвечает ошибкой, а не зависает.
  • Ошибка внешнего сервиса. MockAgent с reply(500) — клиент не должен молча возвращать пустоту.
  • Необработанный rejection. unhandledRejection в тесте должен валить процесс, иначе ошибка пройдёт незамеченной. Подробнее — в статье «Асинхронность в Node.js».

Проверять надо не только статус, но и то, чего в ответе быть не должно: стека, SQL, error.detail с персональными данными. Такой тест дешевле любого аудита.


E2E и что в нём проверять

E2E запускает сервис так, как он работает в проде: настоящий процесс, настоящий порт, настоящие база и Redis, настоящие переменные окружения. Это единственный уровень, который ловит ошибки конфигурации: забыт PORT, не подхватился .env, миграция не применилась, health check смотрит не туда.

import test from 'node:test';
import assert from 'node:assert/strict';
import { spawn } from 'node:child_process';

test('user can register and create a task', async (t) => {
  const server = spawn(process.execPath, ['src/server.js'], {
    env: { ...process.env, PORT: '0', DATABASE_URL: process.env.TEST_DATABASE_URL },
  });

  t.after(() => server.kill('SIGTERM'));
  const { port } = await readPort(server); // парсит фактический порт из stdout сервера

  const health = await fetch(`http://127.0.0.1:${port}/health`);
  assert.equal(health.status, 200);

  const register = await fetch(`http://127.0.0.1:${port}/auth/register`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ email: 'e2e@example.com', password: 'secret123' }),
  });
  assert.equal(register.status, 201);
});

Правила для e2e:

  • Мало сценариев, только критичные. Регистрация и вход, основной путь, операция с деньгами или правами.
  • Ожидание готовности, а не sleep. Сервис опрашивает /health с таймаутом; фиксированная пауза на медленном CI превращается во флейк.
  • Свой экземпляр зависимостей. E2E не должен работать на базе, где лежат данные других тестов.
  • Проверка остановки. SIGTERM завершает процесс без обрыва текущих запросов — это уже тест надёжности, о которой говорит статья «Таймауты, ретраи и graceful shutdown».
  • Прогон на PR или ночью. E2E добавляет минуты, поэтому его не гоняют на каждое сохранение файла.

Покрытие и его пределы

Покрытие считают по строкам, веткам, функциям и утверждениям. Для Node это либо встроенный --experimental-test-coverage, либо c8, либо покрытие раннера (vitest --coverage).

Что покрытие действительно показывает:

  • код, который не выполнился ни разу, — там точно нет проверок;
  • непокрытые ветки: catch, if (!user), обработку 4xx;
  • общий тренд: покрытие падает, когда добавляют функциональность без тестов.

Чего оно не показывает:

  • качество утверждений. Тест, который вызывает функцию и ничего не проверяет, даёт 100% строк и ноль защиты;
  • граничные случаи. Строка выполнена один раз с одним значением — про остальные неизвестно;
  • интеграционные ошибки. Все файлы покрыты по отдельности, а вместе сервис не работает.

Поэтому порог покрытия ставят как ratchet, а не как цель: например, «не ниже текущего минус один процент». Абсолютные 100% обычно достигаются тестами ради покрытия и /* c8 ignore */ в неудобных местах.

Честнее измерить, ловят ли тесты ошибки, позволяет mutation testing (Stryker): инструмент меняет > на >=, убирает вызов, инвертирует условие — и смотрит, упадут ли тесты. Выжившая мутация означает место, где тест зелёный независимо от поведения. На большом наборе это дорого, поэтому мутации гоняют точечно — по критичным модулям.


Флейки и скорость набора

Флейк — тест, который иногда падает при неизменном коде. Каждый флейк обесценивает весь набор: после третьего «перезапусти, пройдёт» люди перестают верить и красным прогонам.

Типичные причины и лечение:

ПричинаКак выглядитЛечение
Общее состояниепадает только в полном прогонефабрики, beforeEach, уникальные данные
Реальное времяпадает под нагрузкой CIвнедрённые часы, фейковые таймеры
sleep вместо ожидания«иногда не успевает»опрос условия с таймаутом, once на события
Необработанный промисошибка в другом тестевсегда await, t.after для очистки
Порт занятEADDRINUSElisten(0), supertest
Параллельная работа с БДконфликт truncate--test-concurrency=1 для db-тестов, своя схема на файл
Локаль и часовой поясразные даты на машинахTZ=UTC, LANG=en_US.UTF-8, явные Intl-опции
Случайные данныевоспроизводится через разфиксированный seed, данные из фабрик

Ретраи в конфигурации CI допустимы только как диагностика: они дают время починить, но если тест зелёный со второго раза — это баг теста, а не повод оставить ретрай навсегда.

Скорость набора складывается из трёх вещей:

  • Параллельность. node --test и Vitest запускают файлы параллельно; медленные тесты с общим ресурсом выносят в отдельный прогон.
  • Дорогие зависимости один раз на прогон. Контейнер, миграции и сервер поднимаются в before, а не в каждом тесте.
  • Быстрый отклик локально. node --test --watch или watch-режим Vitest запускает только затронутые файлы; полный набор с БД — перед коммитом.

Целевой ориентир: юнит-тесты — секунды, весь набор с интеграционными — единицы минут. Если набор идёт дольше, его перестают запускать локально, и он начинает ловить ошибки только в CI, то есть поздно.


Практика: TaskFlow

Соберём тесты для API из статей «Express и middleware», «Конфигурация и валидация» и «Доступ к базам данных».

1. Структура. Уровни разнесены по каталогам, чтобы их можно было запускать отдельно:

tests/
  unit/
    tasks.service.test.js
  integration/
    tasks.api.test.js
    tasks.repo.test.js
    projects.errors.test.js
  e2e/
    auth-flow.test.js
  helpers/
    db.js
    memory-repo.js
    fixtures.js

2. Сервис без HTTP и базы. Бизнес-правила проверяются на фейковом репозитории и внедрённых часах:

test('move() rejects a project of another owner', async () => {
  const repo = createMemoryRepo([{ id: 't1', ownerId: 'u1', projectId: 'p1' }]);
  const service = createTasksService({ repo, projects: createProjectsStub({ p2: 'u2' }) });

  await assert.rejects(
    service.move({ taskId: 't1', projectId: 'p2', ownerId: 'u1' }),
    (error) => error.status === 403,
  );
});

3. API-контракт. Каждый маршрут — успешный и ошибочный запрос на приложении с in-memory репозиторием:

test('GET /tasks/:id returns 404 for a missing task', async () => {
  const app = createApp({ repo: createMemoryRepo() });

  const res = await request(app).get('/tasks/missing').expect(404);

  assert.equal(res.body.error, 'task not found');
});

4. SQL на настоящей базе. Репозиторий проверяется через testcontainers и миграции: фильтры, сортировка, limit, уникальность, null в project_id.

5. Ошибки. Маппинг 23505 → 409 проверяется фейком, а существование ограничения — интеграционным тестом. Отдельный тест подтверждает, что error.detail не попадает в ответ.

6. Скрипты. Разделение по уровням делает обратную связь быстрее:

{
  "scripts": {
    "test": "node --test",
    "test:unit": "node --test tests/unit",
    "test:integration": "node --test --test-concurrency=1 tests/integration",
    "test:coverage": "node --test --experimental-test-coverage",
    "test:watch": "node --test --watch tests/unit"
  }
}

Что закрыто: бизнес-правила проверяются без базы и HTTP; каждый маршрут имеет тест на успех и на ошибку; SQL, ограничения и коды ошибок проверены на реальном PostgreSQL; ошибки не протекают наружу; набор изолирован и воспроизводим.

Что добавляют дальше: нагрузочные тесты против золотых метрик (статья «Производительность и память»), проверки безопасности вроде отсутствия лишних заголовков и ограничения частоты (статья «Безопасность Node API»), а также e2e-прогон в CI после деплоя на стейдж.


Частые ошибки

  • Тест без await. Промис не дождались, тест зелёный, ошибка всплывает в другом месте.
  • Общий массив в модуле. Состояние переезжает между тестами, порядок запуска начинает влиять на результат.
  • app.listen(3000) в тестах. Порт занят, тесты не идут параллельно, а server.js тянет сигналы и побочные эффекты.
  • Мок вместо фейка на каждом слое. Тест проверяет моки, а не поведение; реальная связка не выполняется ни разу.
  • vi.mock пути, который потом переименовали. Тест падает или, хуже, мокает не тот модуль и остаётся зелёным.
  • sleep(1000) вместо ожидания. Медленно локально и недостаточно на CI.
  • Тест на реальной базе без очистки. Данные копятся, второй прогон падает на уникальности.
  • truncate в параллельных файлах. Один тест удаляет данные другого.
  • Проверка только status === 200. Тело, заголовки и побочные эффекты остаются непроверенными.
  • expect(res.body).toBeTruthy() вместо контракта. Покрытие растёт, защита — нет.
  • Молчаливый catch в тесте. Ошибка проглатывается, тест проходит всегда.
  • E2E на все сценарии. Прогон занимает полчаса, а диагностика падения — ещё столько же.
  • Ретрай вместо исправления флейка. Проблема остаётся и маскируется.
  • Порог покрытия как цель. Появляются тесты без утверждений и ignore-комментарии.

Ключевые тезисы для интервью

  • Уровни тестов различаются долей настоящего кода: unit проверяет логику, интеграционный — стыки слоёв, e2e — конфигурацию и пользовательский сценарий; для бэкенда важен толстый средний слой, потому что основные ошибки живут на стыках.
  • Приложение должно собираться фабрикой createApp({ repo, logger }): server.js только вызывает listen(), а тесты импортируют app.js и не занимают порт. Supertest сам поднимает эфемерный сервер и закрывает его после ответа.
  • Мокают то, чем не управляют — сеть, время, случайность, сторонний SDK. Подмена репозитория, сервиса и HTTP-слоя одновременно означает, что тест проверяет моки, а не поведение.
  • Время и таймеры делают детерминированными через внедрение зависимостей (now, sleep, newId), а фейковые таймеры раннера применяют к чужому коду, помня про микрозадачи после tick().
  • SQL проверяется только на настоящей базе: testcontainers даёт чистый PostgreSQL на прогон, миграции идут один раз, а между тестами данные очищаются truncate или откатом транзакции.
  • Ошибки тестируют на двух уровнях: фейк с полем code проверяет маппинг в 4xx/5xx, а реальное нарушение ограничения — что схема действительно даёт 23505; отдельно проверяют, что error.detail и стек не уходят клиенту.
  • Покрытие измеряет выполненные строки, а не качество проверок: 100% достижимы тестами без утверждений, поэтому порог держат как ratchet, а реальную силу тестов показывает mutation testing.

Заключение

Тесты — это не отчётность, а инструмент изменения кода: набор, которому доверяют, позволяет рефакторить без страха. Работает он только при двух условиях — тесты изолированы и быстры, а проверяют поведение, а не реализацию. Всё остальное — supertest поверх фабрики приложения, testcontainers вместо мока базы, внедрённые часы вместо sleep — служит этим двум условиям.

Практический минимум для Node-сервиса: node:test или Vitest, createApp() без listen(), supertest на каждый маршрут, фейки на границах вместо тотальных моков, настоящий PostgreSQL в CI, тесты на 4xx/5xx и отсутствие утечек в ответе, покрытие как тренд. E2E оставляют для критичных сценариев и конфигурации.

Дальше логично перейти к безопасности: часть проверок из этой статьи — отсутствие лишних заголовков, ограничение частоты, защита от инъекций — превращается там в отдельный слой защиты.

Полезные ссылки