Інструменти та стандарти середовища

Note

Які інструменти ми використовуємо, чому саме вони, як узгоджуємо версії й середовища, щоб тести були стабільними у всіх розробників та CI

Тест-раннер — Vitest

Чому Vitest:

• Єдиний стандарт для всіх типів проєктів. Vitest однаково добре працює в - Next.js, Astro, Nest.js, Hono, Vanilla / jQuery.

• Повна сумісність із Node.js. Vitest працює поверх Node runtime, без симуляцій або несумісностей. Це гарантує, що поведінка коду у тестах = поведінка у продакшні (на відміну від Bun, який має свій runtime).

• Висока швидкість. Vitest використовує архітектуру Vite:

  • запуск в ESM середовищі без транспайлерів;
  • кешування результатів;
  • миттєвий watch-режим;

У більшості проєктів швидкість виконання тестів у 2–5 разів вища за Jest.

• Нативна підтримка TypeScript і JSX. Жодних ts-jest, Babel чи SWC-конфігів. Vitest напряму компілює TypeScript і JSX через Vite.

• Універсальне середовище тестування.
  Можна обрати environment: 'node' для бекенду (Nest.js, Hono) або environment: 'jsdom' для UI-тестів (Next.js, Astro, jQuery)

• Вбудовані репорти для CI/CD. Vitest підтримує:

  • JUnit для GitLab / Jenkins / GitHub Actions;
  • Coverage (Istanbul) з текстовими, HTML, LCOV звітами;
  • Exit code management (pipeline падає при фейлах);
  • Мінімальні пороги coverage прямо в конфігу;

• Моки, сніпшоти, таймери — усе з коробки. Немає потреби ставити sinon чи chai. Vitest має:

• vi.fn(), vi.spyOn(), vi.mock() — для моків;

• vi.useFakeTimers() — для таймерів;

• expect(...).toMatchSnapshot() — для snapshot-тестів;

Повний набір можливостей без зайвих залежностей.

• Сильна екосистема і спільнота. Vitest — частина екосистеми Vite, яку активно підтримують Evan You (Vue), Anthony Fu (UnoCSS, Slidev) та інші топ-розробники. Постійні оновлення, сумісність із найновішими версіями Node, TS і фреймворків.

• Простота онбордингу. API і синтаксис повністю сумісні з Jest (describe, it, expect), тому:

• легко мігрувати старі тести;

• нові розробники миттєво розуміють структуру;

• Мінімальний maintenance.

• Не потребує Babel чи додаткових трансформерів.

• Легко оновлюється, не ламає конфіги при мажорних апдейтах.

• Працює з будь-яким package manager’ом (pnpm, yarn, npm).

---

Стандартна версія:

• vitest >=4.0
• vite >=6.0
• середовище Node.js ≥ 22.x (LTS)
• pnpm як package manager

Тестова бібліотека

Testing Library

Призначення

Надає API для перевірки поведінки користувача, а не реалізації компонента. Ми дотримуємося її філософії: “The more your tests resemble the way your software is used, the more confidence they can give you.”

Основні модулі:

• @testing-library/react — рендеринг компонентів і пошук елементів за ролями, текстами тощо.
• @testing-library/user-event — симуляція взаємодій (кліки, введення, таби, клавіатура).
• @testing-library/jest-dom/vitest — набір розширених матчів (toBeInTheDocument, toHaveTextContent, toBeDisabled тощо).

Моки мережі — MSW

MSW - Mock Service Worker

Це інструмент для перехоплення HTTP-запитів і імітації відповідей без зміни реального коду. Може працювати у двох середовищах - браузер (Service Worker), Node.js (Використовує внутрішній intercept fetch / http / https для серверних тестів)

Навіщо: для симуляції API-відповідей у тестах без реального бекенду.

• Працює в jsdom як “in-memory” HTTP-інтерцептор.
• Дозволяє створювати обробники (handlers) для REST або GraphQL-запитів.
• Повністю відтворює очікувану поведінку: заголовки, статуси, таймаути.
• Забезпечує однакові тести локально, у CI та в браузері.

Типові сценарії:

• UI-компоненти, що викликають API;
• хуки, які фетчать дані (useQuery, useFetchData);
• тестування поведінки при 404 / 500 статусах.

Використання з Vitest

У тестах використовуємо Node-версію — setupServer.

Створюємо інтерсептори

src/mocks/handlers.ts

import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/user', () => {
    return HttpResponse.json({ id: 1, name: 'Some Name' })
  }),
}),
...
]

Налаштовуємо Vitest

test/setup.ts

import { setupServer } from 'msw/node'
import { handlers } from '../src/mocks/handlers'

export const server = setupServer(...handlers)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

Середовище виконання

Vitest підтримує два основних середовища:

Середовище	Призначення	Коли використовувати
jsdom	емуляція браузера	для React-компонентів, хуків із DOM-ефектами
node	нативне Node-оточення	для утиліт, SDK, API-клієнтів, скриптів

У нашій політиці:

• jsdom використовується за замовчуванням (environment: 'jsdom');
• файли *.node.test.ts автоматично запускаються у node-режимі (див. vitest.config.ts).

vitest.config.ts

import { defineConfig } from 'vitest/config'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
plugins: [tsconfigPaths()],
test: {
  globals: true,
  include: ['**/*.test.{ts,tsx}'], // базова маска
  environment: 'jsdom',
  setupFiles: ['./setupTests.ts'],
},
// окремі проекти з власним середовищем
projects: [
  // 1. jsdom (за замовчуванням — для React, UI)
  {
    test: {
      name: 'jsdom',
      environment: 'jsdom',
      include: ['**/*.test.{ts,tsx}'],
      exclude: ['**/*.node.test.{ts,tsx}'],
    },
  },
  // 2. node (для SDK, утиліт, API)
  {
    test: {
      name: 'node',
      environment: 'node',
      include: ['**/*.node.test.{ts,tsx}'],
    },
  },
],
})

Глобальні налаштування

setupTests.ts Цей файл виконується перед кожним тестом і:

• реєструє матчери (@testing-library/jest-dom/vitest);
• очищає DOM після кожного тесту (cleanup());
• додає моки для відсутніх у jsdom API (matchMedia, ResizeObserver, IntersectionObserver…);
• налаштовує поведінку console.error/console.warn (щоб тест падав, якщо компонент викидає помилку);
• підключає MSW-сервер;

Звіти та покриття

• Покриття генерується за допомогою V8 Coverage Provider (coverage.provider: 'v8').
• Формати репортів: text, html, lcov, json-summary, cobertura.
• Звіти зберігаються у reports/coverage і передаються у CI як артефакти.
• Для GitLab використовується junit-репортер (reports/junit-unit.xml) — дані автоматично потрапляють у Merge Request.

Менеджер пакетів

Стандарти:

• pnpm >=10.x — швидкий, ізольований, з кращим кешуванням node_modules.
• Алиаси @/ мають бути синхронізовані з tsconfig.json через плагін vite-tsconfig-paths.

Інші рекомендовані пакети

Пакет	Призначення
whatwg-fetch	поліфіл fetch у jsdom
faker-js/faker	генерація фіктивних даних
@anatine/zod-mock	автоматичні фікстури зі схем Zod
msw/node	емуляція мережі у Node-середовищі
vitest-axe	a11y-перевірки через axe-core (опціонально)

Стандарти середовища

Щоб тести працювали однаково у всіх середовищах (локально, CI, staging):

Параметр	Значення	Примітка
Node.js	≥ 22.x	однакова версія у локальних та CI-середовищах
Timezone	UTC	фіксований, щоб уникнути розбіжностей у датах
Locale	en-US	стабільна локаль для форматів чисел/дат
Browser API mocks	однакові у всіх (через setupTests.ts)	matchMedia, ResizeObserver, IntersectionObserver
ENV	.env.test	ізольований набір змінних (жодних продакшн-ключів)

Основний принцип

Тестове середовище має бути максимально схожим на реальне, але повністю детермінованим.

Тобто — ми тестуємо поведінку браузера, але контролюємо всі залежності - час, API-відповіді, випадковість, конфігурації.