Юнит-тесты с node:test и Vitest

Встроенный раннер: node:test и node:assert

Прежде чем тянуться к стороннему раннеру, спроси: а что уже есть? С Node 18 (стабильно с Node 20) встроенный раннер закрывает весь цикл юнит-тестирования без единой установки — и это важно, когда дорожишь чистотой зависимостей библиотеки или скоростью холодного CI.

С Node 20 раннер тестов стабилен и встроен — без зависимостей, без конфига. Тесты пишешь через test() (или describe() / it()), проверяешь через node:assert и запускаешь через node --test, который находит файлы вида *.test.js, *-test.js и файлы в каталогах test/. Добавь --watch для перезапуска при изменении и --experimental-test-coverage для сводки покрытия. Сабтесты вкладываются через await t.test(...), а хуки (before, after, beforeEach, afterEach) поднимают и сносят состояние.

import { test, describe, it, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { Cart } from "./cart.js";

describe("Cart", () => {
  let cart;
  beforeEach(() => { cart = new Cart(); }); // свежее состояние на каждый тест

  it("totals line items", () => {
    cart.add({ price: 10, qty: 2 });
    assert.strictEqual(cart.total(), 20);
  });

  it("rejects a negative quantity", () => {
    assert.throws(() => cart.add({ price: 10, qty: -1 }), /quantity/);
  });
});

Ключевое с node:assert — импортировать строгий вариант (node:assert/strict), чтобы assert.equal означал ===, а не нестрогий ==, который тихо считает "2" и 2 равными. assert.strictEqual сравнивает примитивы; assert.deepStrictEqual обходит объекты и массивы структурно; assert.match проверяет строку против регулярки. Сбои, которые ты ожидаешь, проверяй напрямую: assert.throws(fn, /pattern/) для синхронных throw и await assert.rejects(promise, /pattern/) для зареджекченных промисов — тест, который проверяет отсутствие ошибки там, где она должна сработать, проходит по неправильной причине.

Мокаем на границах

Юнит-тест должен прогонять твою логику, поэтому ты заменяешь медленные или недетерминированные вещи на её краях — сеть, файловую систему, часы — а собственный код оставляешь настоящим. node:test даёт mock.fn() для отдельных шпионов, t.mock.method(obj, "name") для замены метода (автовосстановление по завершении теста) и t.mock.module() для подмены целого модуля. Шпион записывает каждый вызов: mock.calls хранит аргументы, возвращаемые значения и число вызовов, так что ты ассертишь как был использован коллаборатор.

import { test, mock } from "node:test";
import assert from "node:assert/strict";

test("charges the gateway once with the order total", () => {
  const gateway = { charge: mock.fn(() => ({ id: "ch_1" })) };
  const order = { total: 4200, gateway };

  checkout(order);

  assert.strictEqual(gateway.charge.mock.callCount(), 1);
  assert.deepStrictEqual(gateway.charge.mock.calls[0].arguments, [4200]);
});

Дисциплина, которая важна: мокай границу, а не собственную логику. Если замокать тестируемую функцию, тест ассертит твой мок, а не твой код. Заглуши HTTP-вызов платёжного шлюза; не заглушай checkout(), который ты пытаешься проверить.

Выбор раннера: node:test vs Vitest vs Jest

node:test — верный дефолт для библиотеки или бэкенда с небольшим числом зависимостей: ставить нечего, быстрейший старт, и он говорит на core API. Бери Vitest, когда нужна эргономика в стиле Jest — цепочечные матчеры expect, инлайн-снапшоты, vi.mock, среда jsdom/happy-dom для кода, трогающего DOM, TypeScript без лишнего конфига и шустрый watch на HMR, перезапускающий только затронутые тесты. Vitest почти полностью совместим с Jest (vi.fn вместо jest.fn, vi.mock вместо jest.mock), так что это ещё и стандартный путь сбежать от медленной настройки Jest. Сам Jest бери в основном тогда, когда у тебя уже есть сюита Jest и плагины, которые не хочется мигрировать.

Принципы, которые держат тесты честными

Когда видишь, как тест помечают skip вместо того чтобы починить, почти всегда нарушено одно из трёх правил. Три правила отделяют сюиту, которой доверяешь, от той, что заглушают. Тестируй поведение, а не реализацию: ассерти наблюдаемый исход (возвращаемое значение, вызов коллаборатора), а не приватные внутренности, чтобы рефакторинг, сохраняющий поведение, не красил сюиту. Тест, ломающийся при каждом переименовании приватного метода, тестирует не то. Arrange-Act-Assert: подготовь входы, выполни одно действие, проверь один исход — один логический ассерт на тест делает место сбоя точным. Держи каждый тест независимым: без разделяемого изменяемого состояния, без опоры на порядок прогона. Сбрасывай состояние в beforeEach; если тест B проходит лишь потому, что тест A отработал первым и оставил строку в массиве уровня модуля, у тебя порядко-зависимая сюита, которая флакнет в тот же миг, когда раннер распараллелит или перемешает.

// ❌ зависит от порядка: состояние уровня модуля течёт между тестами
const users = [];
test("a: adds a user", () => { users.push({ id: 1 }); assert.strictEqual(users.length, 1); });
test("b: starts empty", () => { assert.strictEqual(users.length, 0); }); // ПАДАЕТ после a

// ✅ независимо: свежее состояние каждый раз
let store;
beforeEach(() => { store = new UserStore(); });