Netpulse_SasS/web/TESTING.md

# Тести вебу

```bash
npm test              # vitest run — один прогін
npm run test:watch    # у режимі спостереження
npm run check         # типи + тести + збірка
sh ../scripts/check.sh web   # те саме, але тим самим шляхом, що й CI
```

Раннер — **vitest**, а не jest: проєкт на Vite, і `vitest.config.ts` зроблено
через `mergeConfig(viteConfig, …)`. Тобто тести проходять ТУ САМУ трансформацію,
що й збірка. З jest вийшло б два різні конвеєри, і розбіжність між ними
знаходили б не тестом, а на стенді.

Середовище — jsdom. Тести лежать у `src/test/`.

---

## Головне про цей файл

Сьогодні на проєкті сталося ось що: перед зміною ролі БД прогнали ретельний тест
ізоляції, він був зелений — і пропустив поломку, бо перевіряв «чи не видно
чужого», а зламалось «чи видно своє».

**Зелена перевірка доводить рівно те, що вона перевіряє.** Тому нижче спершу йде
перелік того, чого тести НЕ покривають. Він важливіший за перелік покритого:
доки він тут і чесний, зелений прогін не можна прийняти за доказ справності.

---

## Чого тести НЕ покривають

### Мапа: перетягування вузлів і все, що робить d3-drag

`MapCanvas` тягне вузли через React Flow, а той — через **d3-drag**. d3-drag не
запускається синтетичними подіями jsdom: він читає `pointerId`, `PointerEvent`,
`elementFromPoint` і матрицю перетворення SVG, а jsdom нічого з цього не рахує.
Наслідок практичний: **тесту на перетягування немає й не буде** без справжнього
браузера.

Що саме через це лишається неперевіреним:

- запис нової позиції вузла після перетягування (`MapCanvas.tsx`, порівняння
  `Math.round(x/y)` з попереднім і рішення «слати чи ні»);
- групове перетягування виділених вузлів;
- малювання нового звʼязку мишею від порту до порту;
- вибір бока підключення при перетягуванні (`autoSides` перевірено як функція,
  але не перевірено, що полотно взагалі її кличе й із тими координатами).

### Усе, що вимагає справжнього рушія

- **Мінікарта конфігу (`Minimap.tsx`)** — перевірено лише `buildShape`. Саме
  малювання йде в `<canvas>`, а jsdom не має 2D-контексту: `getContext('2d')`
  повертає `null`, і всі три шари мовчки нічого не роблять. Тобто **розкладка
  й вигляд мінікарти не перевірені ніяк**: помилка в `yOfRow`, `rowAtY`, у
  межах вікна прокрутки або в колонці щільності позначок пройде зеленою.
- **Точка підпису на кривій (`pointsOnPath` у `mapStyle.ts`)** — код сам
  повертає `[]` під jsdom, бо `SVGPathElement.getTotalLength` там не
  реалізовано. Гілка з реальними вимірами не виконується жодного разу.
- **Ширина символа (`useCharWidth`)** і будь-яка залежність від
  `getBoundingClientRect`: у jsdom усі розміри нульові. Віртуальна прокрутка
  `ConfigViewer` перевірена лише в арифметичній частині (`rowAt`,
  `uniformOffsets`), не в тій, що читає реальні розміри.
- **Медіазапити Tailwind.** `DataTable` малює кожен рядок ДВІЧІ — таблицею для
  десктопа й карткою для телефона, — а ховає зайве CSS. У тесті видно обидві
  копії; який саме варіант побачить людина на 375 px, тест не знає.
- **`ResizeObserver`** підмінено заглушкою в `src/test/setup.ts`. Логіка, що
  залежить від зміни розміру, не спрацьовує.

### Мережа й живі дані

Мережевий шар тепер покритий (див. «Що покрито»), але покритий він **проти
підставного `fetch`**, а не проти сервера. Тому лишається непокритим:

- **Жодного тесту зі справжнім сервером.** Підставні відповіді написані за
  `server/API.md` і за обробниками `server/internal/httpapi/`, і звірка ця
  зроблена **очима, один раз**. Ніщо не тримає її актуальною: якщо сервер
  перейменує поле, тести лишаться зеленими на старій формі. Розбіжність між
  `types.ts` і реальною відповіддю API тут не ловиться в принципі — так само,
  як і раніше.
- **Справжній `WebSocket` не бере участі.** Перевірено логіку
  `LiveConnection` проти підставного сокета: рукостискання, підпротоколи,
  поведінка проксі, `bufferedAmount`, порядок подій у реальному браузері — ні.
- **Черга подій під навантаженням.** Що буде, коли сервер надішле тисячі
  повідомлень за секунду, тест не знає: усі перевірки — на одиницях подій.
- **Ротація refresh-токена в часі.** Перевірено, що обмін ОДИН на сплеск
  запитів; що буде, коли access-токен протухне рівно між `fetch` і читанням
  тіла, — не перевірено.
- **Режим кіоска (`VITE_API_TOKEN`).** `staticTokenPresent` читається з
  `import.meta.env` під час імпорту модуля, тому в тестах він завжди
  порожній: жодна перевірка цієї гілки не виконується (див. «знайдене» у
  звіті — там про неї є що сказати).

### Сторінки

Покрито п’ять сторінок із двадцяти семи (`AuditPage`, `DevicesPage`,
`TeamPage`, `RolesPage`, `AlertsPage`) і два вікна незворотних дій.
**Решта двадцять дві не покриті нічим:** `MapPage`, `DevicePage`,
`ConfigsPage`, `CommandsPage`, `RulesPage`, `TemplatesPage`, `TrapsPage`,
`StoragePage`, `QueuesPage`, `MetricsPage`, `DashboardPage`, `GroupsPage`,
`CredentialsPage`, `ProfilesPage`, `CompliancePage`, `MirrorPage`,
`ChannelsPage`, `EscalationsPage`, `AgentsPage`, `ServerFilesPage`,
`ProfilePage`, `TvPage`. Для них не перевірено ні права, ні форми, ні фільтри.

Окремо про те, чого немає навіть на покритих сторінках:

- **Фільтри в адресі перевірені лише в `AuditPage`.** `DevicesPage` тримає
  свої фільтри в стані компонента, а не в адресі, — тобто відфільтрований
  перелік хостів колезі не перешлеш. Це не поломка тесту, це властивість
  продукту, і тест її не покриває, бо покривати нічого.
- **`DeviceFilterPanel` і фільтри метрик** — перевірено лише чисті функції
  (`filters.test.ts`), не зв’язку «панель → запит».
- **Створення хоста, шаблона, правила, каналу** — форми не покриті.
  Перевірено лише те, що кнопка створення з’являється за правом.
- **Порядок і кількість запитів при монтуванні сторінки** перевірено лише
  там, де це саме предмет тесту (зонди на `DevicesPage`). Зайвий запит на
  решті сторінок пройде зеленим.

### Права доступу

Перевірено пари «є право / немає права» для хостів, користувачів, ролей і
алертів. **Не перевірено:**

- **звуження групами доступу** (`writable`, `access: read|write` на мапі):
  тести працюють із хостами, у яких `writable: true`;
- **розбіжність між тим, що ховає клієнт, і тим, що відхиляє сервер.**
  Клієнтський `session.can()` і серверний `requirePerm()` — два різні
  переліки, і ніщо не звіряє їх між собою. Право, яке сервер уже вимагає, а
  клієнт ще ні (або навпаки), пройде зеленим по обидва боки;
- **право, що змінилось під час роботи вкладки.** Сервер перечитує членство
  при кожній ротації токена, клієнт — при `session.set`. Що бачить людина в
  проміжку, не перевірено.

### Доступність і клавіатура

- **Модальне вікно не переносить фокус усередину й не тримає його там.** Тесту
  на це немає, бо й поведінки немає (див. «знайдене» нижче). Перевірено лише
  закриття: Esc, клік повз панель, хрестик.
- Порядок обходу Tab, читачі з екрана, контраст — не перевірено ніяк.

### Дрібне, але варте згадки

- `download()` (збереження конфігу файлом) — не покрито: `URL.createObjectURL`
  у jsdom існує, але завантаження не відбувається.
- Часові пояси: `RollbackDialog.fmtDate` і `AuditPage.fmt*` користуються
  `toLocaleString('uk-UA')`, результат залежить від пояса машини. Тестів немає
  саме тому — вони були б зелені локально й червоні в CI.
- `MetricChart.build` (розрахунок меж осей, накопичення, розриви) — не покрито.
  Покрито лише `fmtValue` і `seriesLabel`.

---

## Знайдене, але не закріплене тестом

Правило 3 нижче забороняє закріплювати ваду зеленим `expect`. Це знайдено під
час написання тестів мережевого шару й сторінок; тестів на це навмисно немає —
або вони були б червоні, або зафіксували б неправильну поведінку.

1. **«Будь-який машинний токен» у журналі аудиту їде не тим параметром.**
   `AuditPage` кладе значення `-` у `filter.tokens`, звідки `api.audit()`
   надсилає `token=-`. Сервер шукає `-` серед `actor`
   (`httpapi/audit.go`, гілка `f.AnyToken`), а `token` кладе в
   `ActorTokenIDs` — і той іде в SQL як `actor_token_id = ANY(...)` по
   стовпцю `uuid` (`migrations/0001_core.sql:215`). Тобто вибір цієї
   позначки дає не «рядки без людини», а помилку розбору UUID.
   Показово: коментар у `types.ts` над `AuditFilter.actors` описує
   ПРАВИЛЬНУ поведінку — `-` мав лежати серед `actors`.

2. **Режим кіоска нікому нічого не показує.** При заданому
   `VITE_API_TOKEN` `App` пропускає відновлення сесії, тож
   `session.me()` лишається `null` назавжди — а `session.can()` без `me`
   повертає `false` на будь-яке право. Наслідок: бічне меню порожнє, а
   кожен маршрут показує «Розділ недоступний». `api.me()` у клієнті є, але
   не викликається звідки-небудь жодного разу.

3. **`api.logout()` кидає помилку в порожнечу.** `AppShell` кличе його як
   `void api.logout()`; сесія чиститься в `finally`, але відмова сервера
   стає необробленим відхиленням промісу.

Тестів на п.1 і п.2 немає навмисно: вони були б червоні, а червоний тест у
`check.sh` зупиняє роботу всім.

---

## Що покрито

### Чиста логіка

| Файл тесту | Що саме |
|---|---|
| `format.test.ts` | `plural`, `ago`, `humanInterval`, `fmtBytes`, `formatBps`, `fmtValue`, `fmtBps`, `uniq` — межі одиниць, знак, дати з майбутнього |
| `linediff.test.ts` | `splitLines`, `diffSegs`, `buildDiff`, `wordDiff` |
| `configview.test.ts` | `rowAt`, `uniformOffsets`, `maxLen`, `gutterWidth`, `safeName`, `buildShape` |
| `map.test.ts` | `autoSides`, `autoLabelPositions`, `labelCandidates`, `estimateLabelBox`, `edgeState` |
| `labelLayout.test.ts` | жадібна розкладка підписів: зсув, невміщення, пріоритет, масштаб, звільнення місця |
| `filters.test.ts` | `matchesMetricQuery`, `matchesMetricFilter`, `defaultsFromSchema` |

Найважливіше тут — **порівняння конфігів**. Воно перевіряється не прикладами, а
інваріантами на 500 випадкових парах із детермінованим генератором: із ділянок
має точно відновлюватись і стара версія, і нова; нумерація обох колонок має йти
без пропусків і повторів; текст у рядку має відповідати своєму номеру. Приклади
ловлять те, про що встиг подумати автор тесту; інваріант ловить те, про що не
подумав ніхто. Окремо перевірено розрахунковий випадок Myers — один змінений
рядок серед 30 000.

### Поведінка компонентів

| Файл тесту | Що саме |
|---|---|
| `modal.test.tsx` | Esc (у т.ч. коли фокус у полі), клік повз панель, виділення тексту за край вікна НЕ закриває, зняття слухача при розмонтуванні, `role=dialog`/`aria-modal` |
| `confirm.test.tsx` | подвійний клік не шле другий запит, помилка сервера НЕ закриває вікно, Esc = скасувати, підпис кнопки |
| `datatable.test.tsx` | порожній стан, подвійна відмальовка рядків, `hideOnMobile`, `Toggle` |

### Мережевий шар

| Файл тесту | Що саме |
|---|---|
| `apiclient.test.ts` | заголовок `Bearer`, `credentials: same-origin`, 204 без тіла, розбір `{"error":{code,message}}`, `isConflict`/`isPlanLimit`/`isForbidden` **і навпаки**, тихий обмін на `401 token_expired`, відсутність обміну на `no_session` і `403`, один обмін на десять паралельних запитів, `restore()` один на завантаження, `logout` чистить сесію навіть при відмові сервера, `session.can`, `meFromLogin` |
| `ws.test.ts` | адреса й токен у підпротоколі, читання токена **заново** після реконекту, `connecting/online/offline`, затримка 1→2→4→8→15 с зі стелею й скиданням, `stop()` зупиняє реконект і забуває підписку, повторна підписка на мапу після кожного розриву, пошкоджене повідомлення, слухач, що впав |
| `hooks.test.tsx` | злиття сплеску подій в один перечит, перечит після паузи, чужі повідомлення ігноруються, розмонтування скасовує заплановане, `useAlerts` без `alerts:read` не питає нічого |

Найважливіше тут — **негативні половини**. «Обмін відбувся» нічого не варте
без «на `no_session` не відбувся»; «реконект стався» — без «після `stop()` не
стався». Саме асиметрична перевірка й пропустила зламаний вхід у тесті
ізоляції RLS.

### Сторінки

| Файл тесту | Що саме |
|---|---|
| `routing.test.tsx` | неавторизований на закритій адресі бачить вхід і сторінка **даних не питає**; після входу відкривається та сама адреса; `Guard` без права не малює сторінку й не робить запиту; домівка залежить від ролі; пункт меню без права відсутній; вихід повертає до входу й **розриває сокет** |
| `pagepermissions.test.tsx` | пари «є право / немає права» для хостів, користувачів, ролей, алертів; себе й власника прибрати не можна; право, якого немає в тебе, не можна віддати ролі; зміна ролі шле **лише те, що змінилось**; порожня правка запиту не робить; подвійний клік не шле двох PATCH; `409 shared_user` лишає вікно з набраним |
| `auditfilter.test.tsx` | фільтр із посилання й той самий фільтр, обраний руками, дають **однаковий** запит і однакову адресу; типовий період в адресу не пишеться; скидання чистить і адресу, і запит; гортання йде у вікні, яке зібрав сервер |
| `destructive.test.tsx` | видалення хоста: набір звіряється з сервером, повне видалення заблоковане до підтвердження втрати, без зібраного галочки немає, типово — повне, підпис кнопки називає режим, подвійний клік не дублює запит, помилка не закриває вікно; відкат конфігу: план, непідтримуваний профіль, ручні рядки, `plan_hash`, збережена причина після відмови |

Підставні відповіді написані не «схоже», а за формою сервера: помилка — з
`writeError()` (`httpapi/server.go`), вхід і `refresh` — з `API.md`, масові
дії над хостами — з `devices_bulk.go` і `store.BulkDeviceTarget`, журнал — з
`handleListAudit`. Спільні підпори лежать у `src/test/support.ts` — щоб
розбіжність із сервером правилась в одному місці й ламала всі тести одразу.

Обрано саме ці два вікна не випадково: `Modal` — єдине місце, де самовільне
закриття зʼїдає набране в довгій формі, а `ConfirmDialog` — останній екран перед
незворотною дією, і його дві тихі поломки (другий запит на видалення; закриття
після невдачі, яке читається як «виконано») коштують найдорожче.

---

## Правила для нових тестів

1. **Перевіряй те, що ламається, а не те, що легко перевірити.** Відсоток
   покриття тут не рахується навмисно: він винагороджує тести на гетери.
2. **Назва тесту — це твердження про поведінку**, а не про виклик функції.
   «нумерація обох колонок іде без пропусків і без повторів», а не «buildDiff
   works».
3. **Не закріплюй ваду зеленим тестом.** Якщо поведінка неправильна — місце їй
   у розділі «знайдене» звіту або в цьому файлі, а не в `expect`. Виняток —
   коли поточне правило треба зафіксувати свідомо (як сортування `uniq` кодами
   символів); тоді це має бути сказано в коментарі.
4. **Випадкові дані — лише з детермінованим генератором.** Тест, що падає раз
   на сто прогонів і не відтворюється, гірший за відсутність тесту: у нього
   перестають вірити й починають перезапускати CI, доки не позеленіє.
5. **Модульний стан прибирай за собою** (див. `labelLayout.test.ts`): інакше
   падатиме не той тест, що зламався.