Перевірки відповіді: статус, тіло, заголовки, схема

Що ви перевіряєте у відповіді API?

Відповідь — не «зелений кружечок», а кілька незалежних шарів контракту, і перевіряти їх варто від найзагальнішого до найдетальнішого. Мій чек-лист: статус-код саме той, що очікує сценарій; заголовки, насамперед Content-Type; тіло реально парситься як JSON, а не HTML-сторінка помилки; форма тіла за схемою (обов'язкові поля, типи, відсутність зайвих); конкретні значення відповідають тому, що надсилали чи сідили; і час відповіді в межах розумного. Порядок не косметичний: якщо впала перша перевірка, решту запускати немає сенсу, а номер шару вже локалізує проблему. Слабка відповідь на цьому питанні — «дивлюсь, щоб JSON був»; сильна — саме структурований список шарів.

Прийшов 200 OK. Тест зелений?

Ні, статусу самого по собі недостатньо. 200 OK описує лише транспортний рівень — «запит дійшов, сервер його обробив і сформував відповідь», але що саме в тій відповіді, код не гарантує. Багато старих або погано спроєктованих API на будь-який результат повертають 200, а справжній результат кладуть у тіло: { "success": false, "error": "INSUFFICIENT_FUNDS" }. Транспортом усе гаразд, а бізнес-операція провалилася — і тест, що перевіряє лише expect(res.status()).toBe(200), тут зелений і пропускає баг. Тому перевірка статусу майже ніколи не самодостатня: за нею завжди має йти перевірка тіла.

Чому статус і тіло треба перевіряти разом, а не окремо?

Бо вони описують різні речі й ловлять різні класи багів. Статус — це транспорт («запит опрацьовано»), тіло — результат бізнес-операції. Класична пастка в один бік: 200 із "success": false чи порожнім масивом замість даних, і тест на самий статус його не бачить. Дзеркальна пастка в інший бік: сервіс повертає 500, але з осмисленим тілом помилки — тест, що дивиться лише в тіло, проґавить, що замість очікуваного 400 Bad Request користувач отримав внутрішню помилку сервера. Крайній випадок першого патерну — GraphQL: він майже завжди відповідає 200, а помилки складає в масив errors поруч із частковими даними.

Навіщо перевіряти Content-Type окремо, перед тим як парсити тіло?

Бо тіло — це завжди байти, і щоб перетворити їх на структуру, клієнт має знати формат, який оголошує саме Content-Type. Уявіть, що бекенд через помилку конфігурації віддав HTML-сторінку 502 Bad Gateway від проксі, а тест наосліп викликав .json(). Ви отримаєте не зрозумілий фейл, а падіння парсера на Unexpected token '<' — і півгодини дебагу не туди. Тому дисципліна така: спершу переконатися, що Content-Type — саме application/json, і лише потім парсити тіло. Заголовки в HTTP регістронезалежні, тож назви перевіряють без урахування регістру (клієнти зазвичай віддають їх у нижньому).

Що таке серіалізація й десеріалізація і які баги виникають на цьому стику?

Серіалізація — це перетворення внутрішнього об'єкта сервера на текст для передачі, десеріалізація — зворотний бік у клієнта. На цьому стику живе окремий клас багів. Найтиповіший — число, що серіалізувалося як рядок: "price": "19.99" замість "price": 19.99; обидва «виглядають як 19.99», але тип різний, і споживач, який чекає число, зламається. Далі — Content-Type: application/json, а всередині насправді не-JSON: обрізаний потік або зайвий BOM на початку. І кодування: сервер оголосив charset=utf-8, а віддав дані, скажімо, у windows-1251 — кирилиця перетвориться на «кракозябри». Усе це проходить повз тест, який дивиться лише статус.

Що таке JSON Schema і навіщо вона в тестах?

JSON Schema — стандарт, що декларативно описує структуру JSON-документа: набір полів і їхні типи. Коли важлива саме форма відповіді, а не конкретні значення, перевіряти кожне поле руками марудно й крихко — схема робить це одним викликом валідатора. Це той самий контракт, лише машиночитний. Три ключові поняття, які варто розуміти: type — очікуваний тип значення (string, number, integer, boolean, object, array, null), саме він ловить класику «число прийшло рядком»; required — масив імен полів, які обов'язково мають бути присутні; additionalProperties — чи дозволені поля, яких немає в схемі. У JS/TS схему перевіряють валідатором, найчастіше ajv.

Що робить additionalProperties: false і навіщо це на практиці?

Робить схему суворою: будь-яке несподіване поле, якого немає в схемі, — фейл валідації. За замовчуванням additionalProperties дорівнює true, тобто зайві поля дозволені, і слабка схема пропускає баг, коли бекенд випадково почав віддавати щось зайве. Найболючіший приклад — passwordHash у публічному профілі: це вже не просто зайве поле, а витік чутливих даних. Сувора схема з additionalProperties: false ловить таке одразу, тоді як точкові асерти на очікувані поля цього не помітять — вони перевіряють наявність потрібного, а не відсутність зайвого. Тому для перевірки на витоки й «дрейф контракту» сувора схема цінна.

У чому різниця між null, відсутнім полем і порожнім рядком?

Це три різні контракти, які виглядають схоже, а означають різне. Відсутнє поле (ключа взагалі немає) — «про це нічого не сказано». null ("middleName": null) — «значення явно відоме й воно порожнє або невідоме». Порожній рядок ("middleName": "") — «значення є, і це рядок нульової довжини». Болить це так: клієнт, який робить user.middleName.length, впаде на відсутньому полі й на null (у них немає .length), але спокійно поверне 0 на порожньому рядку. Валідація «поле обов'язкове» зазвичай пропустить null, але зачепиться за "" — або навпаки, залежно від реалізації. Практичний висновок: для кожного поля свідомо виріши, який стан валідний, і перевіряй саме його; expect(body.x).toBe(null) і expect(body).not.toHaveProperty('x') — дві різні перевірки.

Чому required у JSON Schema не гарантує, що значення осмислене?

Бо required перевіряє лише наявність ключа, а не те, що значення не null. Поле зі значенням null для required вважається присутнім — умова виконана. Тому логіка «поле є в схемі, required його вимагає, отже, значення точно осмислене» хибна: схема пройде, а споживач, який очікував рядок, отримає null і зламається. Щоб схема відбивала реальний контракт, тип для поля, яке дійсно може бути порожнім, задають явно — type: ['string', 'null'] дозволяє null, а type: 'string' без null його заборонить. Це часте питання-пастка на співбесіді, бо на ньому плутаються навіть мідли.

Які пастки чатують на тести з датами й таймзонами?

Канонічний формат обміну — ISO 8601 (його інтернет-профіль — RFC 3339), наприклад 2026-07-17T09:30:00Z, де Z означає UTC. Перша пастка — дата без зони (2026-07-17T09:30:00): незрозуміло, у якому поясі, і порівняння з очікуваним стає ненадійним. Друга — тест, що жорстко чекає локальний час: зелений удень і червоний уночі, бо перетнув межу доби в іншій таймзоні. Третя, найпідступніша — різні представлення одного моменту: ...T09:30:00Z і ...T12:30:00+03:00 це той самий момент, але різні рядки, тож побайтове порівняння рядків збреше. Лікування — порівнювати час в UTC або з допуском, а не як рядки.

Чому серйозні API віддають великі id рядком, а не числом?

Бо JavaScript зберігає всі числа як 64-бітний float (IEEE 754), і цілі, більші за Number.MAX_SAFE_INTEGER (це 9007199254740991), у JS втрачають точність — останні цифри «пливуть». Тому великі ідентифікатори (id замовлення, snowflake-id від Twitter/Discord) серйозні API серіалізують саме рядком, щоб клієнт на JS не зіпсував їх при десеріалізації. Пастка для тесту: «id прийшов, усе гаразд», а насправді число вже втратило точність, і подальше порівняння чи повторний запит за цим id підуть не туди. Якщо API документує id як рядок, а віддає числом (або навпаки) — це знахідка для звіту.

Чому не можна порівнювати гроші через звичайну рівність float?

Бо у float 0.1 + 0.2 не дорівнює рівно 0.3 — це фундаментальна властивість IEEE 754, а не баг мови. Тому асерт на точну рівність дробових грошових сум «іноді» падає без реальної проблеми в даних. Два робочі підходи: порівнювати з допуском (toBeCloseTo чи явна дельта) або тримати гроші в мінімальних одиницях — копійках/центах — цілим числом, і тоді арифметика точна. Разом із проблемою великих id це два боки однієї медалі: JSON не обмежує точність чисел, а JS обмежує, тож на числових полях завжди варто питати, чи не постраждає точність.

Що перевіряти в unicode-даних?

Текст їде в UTF-8, і тут кілька окремих речей. Кирилиця й діакритика — щоб не було «кракозябр», які є ознакою збитого кодування. Емодзі та інші символи поза базовою площиною — вони займають дві кодові одиниці в JS, тож "😀".length === 2, і перевірки довжини поля можуть брехати. Нормалізація — один і той самий на вигляд символ (наприклад, é) буває записаний одним кодпоінтом (NFC) або як «e + комбінований акцент» (NFD); рядки при цьому різні, і порівняння через === їх не зрівняє, поки не нормалізувати. Не варто забувати й про порожній рядок та пробіли на краях як окремі тестові дані.

Відповідь — масив із 50 записів. Що перевіряти?

Тут додається окремий пласт перевірок поверх схеми. Перше — порядок: чи він гарантований контрактом. Якщо API обіцяє сортування (?sort=createdAt) — порядок частина контракту й його перевіряють; якщо не обіцяє — прив'язуватися до порядку небезпечно, бо після зміни індексу база віддасть ті самі дані інакше, і тест «раптом» червоний; тоді перевіряють склад множини, а не послідовність. Друге — дублікати: масив може містити той самий елемент двічі через баг у джойні на бекенді, і кількість унікальних id має дорівнювати довжині масиву. Третє — пагінація: межі, узгодженість total, відсутність пропусків і перекриттів між сторінками.

Як перевірити масив на дублікати?

Порівняти кількість унікальних значень ключа з довжиною масиву. Класична причина дублів — JOIN на бекенді, який розмножує рядки, і візуально масив «містить усі потрібні записи», просто деякі двічі. Перевірка коротка, але її часто забувають:

const ids = (await res.json()).map((u) => u.id);
expect(new Set(ids).size).toBe(ids.length);

Set викидає повтори, тож якщо його розмір менший за довжину масиву — є дублікати. Ця ж ідея працює для будь-якого поля-ідентифікатора, не лише id.

Що конкретно перевіряти в пагінації?

Сторінка описується не лише масивом data, а й метаданими: total, page, pageSize, посилання next/prev або курсор. Перевіряю: data.length не перевищує pageSize; total узгоджений із реальною кількістю (сума по сторінках дорівнює total); і головний ризик — між сторінками немає дублікатів і пропусків. Останнє особливо болить у offset-пагінації, коли дані додаються паралельно з читанням: вставка нового запису зсуває offset, і на межі сторінок один запис або двоїться, або губиться. Обов'язково крайові сторінки: перша, остання і сторінка за межами діапазону — там очікується порожня data, а не помилка чи 500.

Точна чи часткова перевірка тіла — коли яка?

Це рішення для кожної асерції, і обидві крайнощі мають ціну. Точна перевірка (toEqual на весь об'єкт) ловить будь-яку несподівану зміну, зокрема появу зайвих полів, але вона крихка: досить одного «леткого» поля — згенерованого id, createdAt, поточного часу — і тест червоніє на кожному прогоні без реального бага, після чого команда починає його ігнорувати. Часткова перевірка звіряє лише те, що важливо для сценарію, і не зважає на решту. Розумний баланс: схема стереже форму й типи всієї відповіді, а точкові асерти перевіряють конкретні значення тих кількох полів, які цей тест справді валідує. Так тест і стабільний, і не сліпий.

Як перевірити відповідь, де є id і createdAt, які щоразу нові?

Не через toEqual на все тіло — воно червонітиме на кожному прогоні через ці летючі поля. Правильно розділити: схема (JSON Schema) стереже форму й типи всієї відповіді, а конкретні значення перевіряють частково — toMatchObject плюс асиметричні матчери для летких полів:

expect(await res.json()).toMatchObject({
  status: 'active',
  email: 'user@example.com',
  id: expect.any(Number),        // важливий тип, не значення
  createdAt: expect.any(String), // летке поле — не прив'язуємось
});

Так летке не ламає тест даремно, а важливі значення (status, email) під контролем. Це і є та часткова перевірка, якої чекають на співбесіді у відповідь на це питання.

Чому надто часткова перевірка — це антитест?

Бо перевірка на кшталт «аби 200 і поле id існувало» зелена завжди й не ловить нічого змістовного. Часткова перевірка корисна, коли звіряє те, що справді важливо для сценарію, і свідомо ігнорує летке. Але якщо звести її до мінімуму, тест перестає бути оракулом: бекенд може повернути порожні дані, неправильний статус активності, зайве поле з витоком — тест усе одно зелений. Тому баланс критичний: схема бере на себе форму й типи всієї відповіді, а точкові асерти — конкретні важливі значення. Надто точна перевірка крихка й швидко ігнорується, надто часткова нічого не ловить; хороший тест сидить між ними.

Три кейси, де перевірка вирішує, ловить тест баг чи спить зеленим: пошарова перевірка відповіді проти пастки «200 OK з помилкою в тілі», JSON Schema як контракт форми з ajv (типи, required, суворість, null), і стабільна перевірка колекції з леткими полями — часткові асерти плюс контроль дублікатів і межі пагінації. Скрізь код на Playwright і що саме дивитися.

Кейс 1. Пошарова перевірка: статус це ще не успіх

Ендпоінт списання коштів повертає 200, тест зелений, а гроші не списалися. Причина класична: сервіс на будь-який результат віддає 200, а справжній результат кладе в тіло. Перевіряти треба шарами — і зупинятися на першому, що впав.

HTTP/1.1 200 OK
Content-Type: application/json

{ "success": false, "error": "INSUFFICIENT_FUNDS", "data": null }

Тест, що перевіряє лише статус, тут сліпий. Правильна перевірка йде по шарах:

import { test, expect } from '@playwright/test';

test('списання: статус, формат і бізнес-результат — разом', async ({ request }) => {
  const res = await request.post('/api/payments', {
    data: { amount: 100, account: 'acc-1' },
  });

  // шар 1: транспорт
  expect(res.status()).toBe(200);

  // шар 2: формат — ДО парсингу тіла
  expect(res.headers()['content-type']).toContain('application/json');

  // шар 3: тіло парситься і бізнес-операція справді успішна
  const body = await res.json();
  expect(body.success, JSON.stringify(body)).toBe(true);
  expect(body.data).not.toBeNull();
});

Що дивитися і чому:

• Статус і тіло — різні шари контракту. 200 каже лише «запит опрацьовано», а не «операція вдалася». Асерт на body.success ловить саме той баг, який expect(status).toBe(200) пропускає.
• Content-Type перевіряють перед .json(). Якщо проксі поверне HTML-сторінку 502, викликаний наосліп .json() впаде на Unexpected token '<' — і півгодинний дебаг піде не туди. Перевірка формату дає зрозумілий фейл замість падіння парсера.
• Друга половина повідомлення в асерті — не косметика. JSON.stringify(body) у expect(..., msg) показує реальне тіло прямо у фейлі, тож не треба перезапускати тест із логами, щоб побачити error: "INSUFFICIENT_FUNDS".
• Дзеркальний випадок теж вартий тесту. Негативний сценарій має перевіряти, що при нестачі коштів приходить осмислена помилка (4xx або документований success: false), а не 500 з падінням на бекенді.

Кейс 2. JSON Schema як контракт форми

Перевіряти кожне поле руками — марудно й крихко. Коли важлива саме форма відповіді (набір полів і типи), контракт описують схемою й валідують ajv. Ця схема ловить одразу кілька класів багів: число, що приїхало рядком, зайве поле й неправильний тип.

import { test, expect } from '@playwright/test';
import Ajv from 'ajv';

const ajv = new Ajv();

const userSchema = {
  type: 'object',
  required: ['id', 'email'],
  additionalProperties: false, // будь-яке зайве поле — фейл
  properties: {
    id: { type: 'integer' },
    email: { type: 'string' },
    name: { type: ['string', 'null'] }, // null дозволено явно
  },
};

test('GET /users/1 — відповідь відповідає контракту форми', async ({ request }) => {
  const res = await request.get('/api/users/1');
  expect(res.headers()['content-type']).toContain('application/json');

  const valid = ajv.validate(userSchema, await res.json());
  expect(valid, JSON.stringify(ajv.errors)).toBe(true);
});

Що дивитися і чому:

• type ловить «число рядком». Якщо бекенд віддасть "id": "1" замість "id": 1, схема з type: 'integer' червоніє — руками таку підміну легко проґавити, бо в JSON вона «виглядає майже однаково».
• additionalProperties: false стереже від дрейфу контракту. Найнебезпечніший приклад — випадковий passwordHash у публічному профілі: точкові асерти на очікувані поля його не бачать, а сувора схема падає одразу. Це перевірка не лише форми, а й на витік.
• required гарантує ключ, не значення. Поле зі значенням null схема вважає присутнім. Тому null дозволяють свідомо через type: ['string', 'null']; якщо name за контрактом не може бути порожнім — null зі списку прибирають, і тоді null стане фейлом.
• ajv.errors у повідомленні асерту. Без нього фейл каже лише «valid === false»; з ним видно конкретне поле і причину (must be integer, must NOT have additional properties) — діагноз замість здогадки.

Кейс 3. Стабільна перевірка колекції з леткими полями

Відповідь — сторінка списку, де в кожного запису свій згенерований id і createdAt. toEqual на все тіло тут червонітиме на кожному прогоні без реального бага. Правильно розділити: форму стереже схема, конкретні значення перевіряють частково, а поверх — інваріанти колекції.

import { test, expect } from '@playwright/test';

test('список замовлень: часткова перевірка + інваріанти колекції', async ({ request }) => {
  const res = await request.get('/api/orders?page=1&pageSize=20&sort=createdAt');
  expect(res.status()).toBe(200);
  const body = await res.json();

  // конкретні поля — точково, летке — через матчер типу
  expect(body.data[0]).toMatchObject({
    status: 'new',
    id: expect.any(Number),        // важливий тип, не значення
    createdAt: expect.any(String), // летке — не прив'язуємось
  });

  // інваріанти колекції
  const ids = body.data.map((o: { id: number }) => o.id);
  expect(new Set(ids).size).toBe(ids.length);      // немає дублікатів
  expect(body.data.length).toBeLessThanOrEqual(20); // не більше pageSize
});

Окремим тестом варто накрити межу пагінації — сторінку за діапазоном:

test('сторінка за межами діапазону — порожня data, а не 500', async ({ request }) => {
  const res = await request.get('/api/orders?page=9999&pageSize=20');
  expect(res.status()).toBe(200);
  expect((await res.json()).data).toEqual([]);
});

Що дивитися і чому:

• toMatchObject + expect.any замість toEqual. Летке поле (id, createdAt, поточний час) не ламає тест даремно, а важливе (status) під контролем. toEqual на все тіло тут — «сувора там, де є летке», тобто перевірка, яку команда швидко вимкне.
• Дублікати ловить Set. JOIN, що розмножує рядки, дає масив, який «містить усі потрібні записи», просто деякі двічі. new Set(ids).size === ids.length — коротка перевірка, яку часто забувають.
• Порядок перевіряємо, лише коли він у контракті. Запит із ?sort=createdAt обіцяє сортування, тож порядок можна асертити. Без явного sort прив'язка до послідовності — джерело флаку: після зміни індексу база віддасть ті самі дані інакше.
• Крайова сторінка — окремий кейс. Головний ризик пагінації — пропуски й дублі на межі та поведінка за діапазоном. Правильна відповідь на неіснуючу сторінку — порожня data, а не помилка чи 500.

Шари відповіді й порядок перевірок

• Можу назвати шари від найзагальнішого до найдетальнішого — статус → заголовки → тіло парситься → форма (схема) → значення → час — і чому перший шар, що впав, локалізує проблему.
• Знаю, що перевірка статусу майже ніколи не самодостатня — за нею завжди йде перевірка тіла.

Статус vs тіло

• Розумію, що 200 OK описує лише транспорт, а не успіх бізнес-операції, тож статус і тіло перевіряють разом.
• Можу навести пастку «200 з "success": false», дзеркальну «500 з осмисленим тілом замість 400» і GraphQL, що майже завжди відповідає 200 з помилками в масиві errors.

Заголовки й серіалізація

• Знаю, чому Content-Type перевіряють ДО парсингу тіла (інакше .json() падає на HTML-помилці з Unexpected token '<'), і що назви заголовків перевіряють без урахування регістру.
• Розумію серіалізацію/десеріалізацію і клас багів на стику: число як рядок ("19.99" замість 19.99), обрізаний потік, BOM, збите кодування (utf-8 проти windows-1251 = «кракозябри»).

JSON Schema як контракт форми

• Розумію, коли брати схему замість ручних асертів: коли важлива форма (набір полів і типи), а не конкретні значення.
• Знаю три ключові слова: type (ловить «число рядком»), required (наявність ключа), additionalProperties (false робить схему суворою й ловить зайве поле — аж до витоку passwordHash).
• Знаю, що схему валідують бібліотекою (ajv), а null дозволяють явно через type: ['string', 'null'].

null, відсутнє поле, порожній рядок

• Розрізняю три стани як три різні контракти (ключа немає / null / "") і наслідок для споживача: .length падає на відсутньому й null, але дає 0 на порожньому рядку.
• Пам'ятаю ключовий нюанс: required вважає поле зі значенням null присутнім — гарантує ключ, не осмислене значення.
• Знаю, що toBe(null) і not.toHaveProperty(...) — дві різні перевірки для двох різних контрактів.

Дати, числа, unicode

• Знаю канонічний формат обміну — ISO 8601 / RFC 3339 з Z для UTC; порівнюю час в UTC або з допуском, бо ...T09:30Z і ...T12:30+03:00 — один момент, різні рядки.
• Можу пояснити, чому великі id віддають рядком (Number.MAX_SAFE_INTEGER, втрата точності float), і чому гроші не порівнюють звичайним float (0.1 + 0.2 !== 0.3) — допуск або цілі копійки.
• Пам'ятаю пастки unicode: "😀".length === 2, «кракозябри» від збитого кодування, нормалізація NFC vs NFD.

Колекції

• Розумію різницю «склад множини vs порядок» і коли порядок є частиною контракту (є ?sort=), а коли ні.
• Знаю перевірку на дублікати: new Set(ids).size === ids.length, і що причина дублів — розмноження рядків у JOIN.
• Можу перелічити, що перевіряти в пагінації: data.length ≤ pageSize, узгодженість total, відсутність пропусків/перекриттів (offset зсувається при паралельному записі), крайові сторінки.

Точна vs часткова перевірка

• Розумію ціну обох крайнощів: toEqual на все тіло крихкий на летких полях, а надто часткова перевірка («аби 200 і поле id») нічого не ловить; баланс — схема стереже форму й типи, точкові асерти — конкретні важливі значення.
• Можу перевірити відповідь із летким id/createdAt через toMatchObject + expect.any(...), а не toEqual.