GraphQL: особливості тестування

Чим тестування GraphQL відрізняється від REST?

Головна відмінність — де живе оракул успіху. У REST кожен ресурс має свій URL і метод, а статус-код відповіді каже долю запиту: 200 — успіх, 404 — не знайшли, 400 — крива форма. У GraphQL є один ендпоінт (зазвичай POST /graphql), а що саме робити описано в тілі запиту; у легасі-режимі application/json транспортний статус лишається 200, навіть коли всередині помилка. Тому головні перевірки переїжджають у тіло відповіді: долю запиту читаємо з полів data й errors. Плюс до цього схема (schema) стає вбудованим контрактом, а over-/under-fetching зникає, бо клієнт сам перелічує потрібні поля. Відбутися фразою «це теж API поверх HTTP» не вийде — інтерв'юер чекає саме цих чотирьох відмінностей.

GraphQL повернув 200 — тест пройшов?

Ні, 200 каже лише, що запит доїхав до сервера й той його опрацював, а не що операція вдалася. У легасі-режимі з медіа-типом application/json GraphQL відповідає 200 навіть на «поле не знайдено» чи «резолвер упав» — бізнес-помилка приїжджає в тілі, у полі errors. (Сервер, що відповідає GraphQL over HTTP, поводиться інакше: без запису data він мусить віддати 4xx/5xx, а на заборонений запит цілком — 401, 403 або подібний код.) Тому асерт expect(res.status()).toBe(200) перевіряє, що сервер живий, а не що все спрацювало. Успіх засвідчує тіло: errors немає, а очікувані data на місці. Асерт лише на статус зелений за будь-якого результату — тобто не перевіряє нічого.

Що таке конверт відповіді GraphQL і які поля він містить?

Конверт (envelope) — це верхній рівень JSON-відповіді: поля data і errors, до яких сервер за специфікацією може додати опційний extensions зі своїми метаданими. У data лежить результат тієї ж форми, що й запит; у errors — масив бізнес-помилок, кожна зі своїм message, path, locations і, можливо, extensions. Ключова ідея — транспорт (HTTP) відповідає лише за доставку, а сенс операції читається саме з цих двох полів. Тому будь-яка перевірка GraphQL-відповіді починається з розбору конверта, а не зі статус-коду.

Що таке часткові дані і чому data й errors можуть бути разом?

Часткові дані (partial data) — це коли у відповіді одночасно присутні й data, і errors. Причина в моделі виконання: кожне поле обробляє свій резолвер (resolver), і провал одного з них не скасовує решту. Проблемне поле перетворюється на null, у errors додається запис про причину, а виконання інших полів триває. У підсумку та сама відповідь несе водночас робочі дані й перелік поламаного: наприклад, user.id резолвнувся, а user.email став null через відмову в доступі. Правило для QA: у кожній перевірці заглядай у errors, хай навіть data на вигляд повне. Тест, що зупинився на data.user.id, не помітить, як email тихо перетворився на null через помилку.

Тест бачить null у полі. Як зрозуміти, це реальна відсутність значення чи помилка резолвера?

null у data буває з двох різних причин: значення справді немає (порожнє поле) або резолвер цього поля впав. Розводить їх масив errors: якщо в ньому є запис із path, що вказує саме на це поле, — значить, поле зламалося, а не було порожнім. path називає конкретне місце провалу, наприклад ["user", "email"], тож здогадуватися про причину дірки не доводиться. Практичний висновок: побачив null — перевір, чи немає для цього шляху запису в errors. Саме тому перевіряти data й errors завжди треба разом, а не окремо.

Навіщо тестувальнику поля errors[].path і extensions.code?

path — найкорисніше поле помилки для локалізації: воно веде просто до поля, що впало (["user", "email"]), і проблемне місце видно одразу, без гадання. extensions.code — машиночитний код помилки (FORBIDDEN, NOT_FOUND); саме на нього варто спиратися в асертах замість message, бо формулювання тексту змінюється без попередження, а коди команди тримають незмінними. Тому асерт варто будувати на коді, а не на рядку повідомлення, який зламає тест від будь-якого переформулювання. Одне застереження: extensions — це розширення, не гарантоване специфікацією, тож перш ніж на ньому будувати перевірки, треба переконатися, що ваш сервер його заповнює.

Яка різниця між помилкою валідації та помилкою виконання резолвера?

Це найважливіша межа теми. До виконання запит проходить два фільтри: парсинг (синтаксична коректність GraphQL) і валідацію за схемою (існування полів, типи аргументів, обов'язковість). Запит, що не пройшов фільтри, до резолверів не потрапляє взагалі: у відповіді є errors, а data немає зовсім (не null, а відсутнє). Помилка виконання (execution error) — інша: запит валідний, резолвери запустилися, але один із них кинув помилку (не знайшов запис, відмова в доступі, впав на БД), і тоді отримуємо часткові дані — data з дірками плюс errors. На практиці ця межа розводить два класи багів: валідація — це зазвичай проблема клієнта чи контракту (фронт шле застаріле поле), виконання — проблема бекенду чи даних (резолвер не впорався). Плутати їх у баг-репортах не можна.

Запит просить поле, якого немає у схемі. Що буде у відповіді?

Це помилка валідації, тож запит навіть не почне виконуватися. Сервер відхилить його на етапі валідації за схемою з повідомленням на кшталт Cannot query field, у відповіді буде errors, а data буде відсутнє повністю — не null, а взагалі немає ключа. Це важливо для асерту: перевіряти треба одночасно наявність errors і те, що data відсутнє (expect(body.data).toBeUndefined()), бо саме відсутність data відрізняє провал валідації від провалу резолвера. Такий негативний тест підтверджує, що схема реально відбиває криві запити, а не пропускає їх до виконання.

data дорівнює null цілком, а не окреме поле. Що це означає?

Це сигнал, що під час виконання сталася помилка, яка завадила сформувати валідну відповідь. Найчастіший шлях туди — провал у non-null полі: поставити туди null не можна, тож помилка пропагується батьківськими рівнями аж до кореня. Логіка nullability така: якщо резолвер non-null поля кинув помилку, GraphQL не може поставити туди null, тож пропагує провал на батьківський рівень — і так далі, доки не натрапить на поле, що null дозволяє, або не дійде до самого data. Для негативних сценаріїв це штатний результат, а не аномалія. Головне — перевіряти data й errors разом: сам по собі data: null без погляду на errors не скаже, що саме зламалося.

Що таке схема і SDL і чому це контракт?

Схема (schema) — це опис усіх типів, полів і операцій API мовою опису схем (Schema Definition Language, SDL). Наприклад, type User { id: ID! email: String orders: [Order!]! } каже, що id — обов'язкове (non-null) поле типу ID, а orders — масив, який сам не буває null і не містить null-елементів. На відміну від REST, де контрактом зазвичай є окрема OpenAPI-специфікація, у GraphQL контракт вбудований у сам сервіс. Ця типізація вже тестована: якщо за схемою orders не буває null, а сервер його повернув, — маємо розходження контракту з реальністю, тобто повноцінний баг. Тому схема — не документація «для довідки», а джерело перевірюваних інваріантів про форму, типи й nullability.

Що таке інтроспекція і чому її можуть вимикати на проді?

Інтроспекція (introspection) — можливість запитати саму схему в рантаймі через мета-поля __schema і __type: повний машиночитний опис API дістається без жодної окремої документації. Саме через неї працюють GraphiQL, автодоповнення в IDE, генерація типів клієнтів і автоматичне звіряння реальної схеми з очікуваною — фактично полегшене контрактне тестування, що ловить breaking changes між білдами. Але на проді інтроспекцію часто глушать: схема, видима будь-кому, — подарунок зловмиснику для розвідки API. Практичний наслідок: інструмент, що будує тести зі схеми через інтроспекцію, працює на dev/staging, а на проді несподівано зустрічає «introspection is disabled». Це не баг тестів, а свідоме рішення бекенду; його треба закладати в стратегію — наприклад, тримати SDL-файл схеми в репозиторії як еталон.

Схема каже, що запит валідний. Це гарантує коректність результату?

Ні. Схема відповідає лише за форму й типи — бізнес-правил вона не знає. Запит createOrder(total: -100) схема пропустить без зауважень — total же число, — хоча за сенсом він абсурдний: від'ємна сума неможлива. Тобто валідність за схемою — це вхідний квиток, а не гарантія коректності. Логіка «сума не може бути від'ємною», «id належить іншому користувачу», «дата в минулому» лежить на резолверах — і саме на неї націлюється тест-дизайн. Тому негативні тести обов'язково включають валідні за схемою запити з поганими даними чи без прав, а не лише криві за формою.

Що таке over-fetching і under-fetching і що вони міняють для тестувальника?

Over-fetching — сервер віддає більше, ніж треба: мобільному застосунку потрібні ім'я й аватар, а REST-ендпоінт повертає повний об'єкт із адресою й історією. Under-fetching — навпаки, одного запиту мало, і щоб зібрати екран, доводиться робити ланцюжок послідовних запитів (класичний request waterfall). GraphQL розв'язує обидва: клієнт одним запитом замовляє точно потрібний набір полів на довільній глибині вкладеності. Для тестувальника це зміщує об'єкт перевірки: форму відповіді визначає запит, тож той самий user в одному місці приходить із трьома полями, а в іншому — з п'ятнадцятьма й вкладеними замовленнями. «Повний об'єкт» перевіряти нема чого — асерти пишуться на той набір полів, який замовила конкретна операція.

Чому в GraphQL немає сенсу перевіряти «повний об'єкт»?

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

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

Оскільки клієнт сам будує запит, він може побудувати зловмисно важкий запит — наприклад, через циклічні зв'язки (користувач має замовлення, замовлення має користувача, у якого знову замовлення) кількома рядками згенерувати запит, що навантажить сервер на порядки. Тому продакшн-сервери ставлять захист: обмеження глибини (depth limiting) відхиляє надто глибоку вкладеність, а аналіз складності/вартості (query complexity / cost analysis) рахує «ціну» кожного поля й відкидає запити, що вилазять за бюджет, ще до виконання. Для QA це окрема гілка негативних перевірок: заважкий запит має отримати зрозумілу відмову, а не покласти сервіс. Самі межі глибини й вартості — задокументована частина контракту, тож заслуговують на власний тест.

Що таке N+1 у GraphQL і чому це турбує QA?

N+1 — проблема продуктивності наївних резолверів. Уяви запит «список із 20 користувачів, і для кожного — його замовлення»: наївний резолвер дістає список одним запитом, а далі ходить у БД окремо по замовлення кожного користувача — разом 1 + 20 звернень. На великих списках продуктивність осідає. Лікують це на бекенді батчингом (batching): DataLoader чи аналогічний патерн акумулює окремі звернення й ходить у БД одним запитом замість двадцяти. Реалізовувати це — робота бекенду, а от упізнавати симптом мусить і QA: список із вкладеними полями відповідає в рази повільніше, ніж мав би, — першою перевіряй гіпотезу N+1. Це характерний для GraphQL клас деградації, хоч сама продуктивність під навантаженням — тема окремого розділу.

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

GraphQL-запит складається з двох частин: тексту операції та об'єкта змінних (variables), і сервер отримує їх як { query, variables }. Виносити значення в окремий об'єкт (variables: { id: '42' }) замість рядкової конкатенації в текст запиту треба з кількох причин: так робить реальний клієнт, код читається чистіше, і зникають проблеми з екрануванням (лапки, спецсимволи в рядкових значеннях). Вклеювання значень у текст запиту крихке й нагадує SQL-інʼєкцію за стилем помилок. Тому в автотесті postQuery(query, variables) — правильний патерн, а конкатенація рядків — джерело плаваючих багів.

Чи потрібен для GraphQL-автотестів спеціальний клієнт?

Ні. Під капотом GraphQL-запиту — звичайний POST із JSON { query, variables }, тож вистачає того самого APIRequestContext у Playwright (чи supertest, CodeceptJS), яким тестуєш REST. Жодної магії немає: надсилаєш текст запиту та змінні, читаєш JSON-відповідь, розбираєш data й errors. Спеціалізовані клієнти (Apollo, urql) дають зручності на кшталт кешу чи типізації, але для тестування контракту вони не обов'язкові. Єдина поправка проти REST-звички — перевіряй тіло (errors/data), а не статус.

Три кейси, де GraphQL ламає REST-звички: розбір конверта відповіді 200 OK із помилкою й частковими даними, Playwright-тести, де оракул успіху — тіло, а не статус, і таблиця рішень «валідація чи резолвер», яка визначає, куди заводити дефект. Скрізь — що дивитися і чому.

Кейс 1. Читаємо конверт: 200, а всередині помилка

Тест зелений: status === 200, data.user.id на місці. А користувач скаржиться, що email не показується. Перш ніж лізти у фронтенд, розберемо саме тіло відповіді — воно й пояснює, чому «все ок» насправді не ок.

{
  "data": {
    "user": { "id": "42", "email": null }
  },
  "errors": [
    {
      "message": "Not authorized to read email",
      "path": ["user", "email"],
      "locations": [{ "line": 1, "column": 34 }],
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

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

• Статус 200, а операція не вдалася повністю. У легасі-режимі application/json сервер віддає 200 навіть коли частина полів упала. Асерт на статус тут зелений і не бачить нічого — оракул провалу живе в errors.
• data й errors присутні одночасно — це часткові дані (partial data). user.id резолвнувся, а user.email — ні, тож у data він приїхав як null, а поруч у errors лежить причина. Тест, що дивиться лише на data.user.id, пропускає мовчазний null в email.
• path: ["user", "email"] локалізує проблему точно. Не треба гадати, чому в даних дірка — path показує саме те поле, що зламалося. Це перше, куди дивишся при несподіваному null.
• extensions.code: "FORBIDDEN" — для асерту надійніший за message. Текст «Not authorized to read email» розробники перепишуть будь-коли, а код зазвичай тримають стабільним. Але спершу переконайся, що ваш сервер узагалі заповнює extensions — специфікація його не гарантує.

Кейс 2. Playwright: оракул — тіло, а не статус

Логіка тесту GraphQL проста, якщо прибрати REST-звичку. Хелпер шле звичайний POST з тілом { query, variables }, а перевіряємо errors/data, а не статус. Спеціальний GraphQL-клієнт не потрібен — той самий APIRequestContext, що й для REST.

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

// GraphQL-запит — це звичайний POST; змінні виносимо в окремий об'єкт
async function postQuery(request: APIRequestContext, query: string, variables = {}) {
  const res = await request.post('/graphql', { data: { query, variables } });
  expect(res.status()).toBe(200); // легасі-режим: це «сервер живий», а НЕ «операція вдалася»
  return res.json();
}

test('позитив: немає errors, дані на місці', async ({ request }) => {
  const body = await postQuery(
    request,
    `query GetUser($id: ID!) { user(id: $id) { id email } }`,
    { id: '42' },
  );
  expect(body.errors).toBeUndefined();          // ось справжній оракул успіху
  expect(body.data.user.email).toBe('user@example.com');
});

Негативні сценарії розводять дві різні межі «неправильно». Перша — запит невалідний за схемою: резолвери не запускаються, data немає взагалі. Приклад нижче написаний під легасі-режим (звідси 200 у хелпері); сервер, що відповідає GraphQL over HTTP, на непройдену валідацію віддасть 422, і хелпер довелося б послабити до res.ok().

test('валідація: невідоме поле — data відсутнє повністю', async ({ request }) => {
  // поля phone у типі User немає — помилка ВАЛІДАЦІЇ, не резолвера
  const body = await postQuery(request, `{ user(id: "42") { phone } }`);
  expect(body.errors?.[0].message).toContain('Cannot query field');
  expect(body.data).toBeUndefined(); // виконання не почалось — ключа data немає
});

Друга — той самий валідний запит, але під користувачем, який не має права читати чужий email: резолвер кидає помилку доступу, отримуємо часткові дані й асертимо path.

test('резолвер: немає прав — data з діркою + errors[].path', async ({ request }) => {
  // request тут авторизований користувачем БЕЗ права читати email іншого
  const body = await postQuery(
    request,
    `query($id: ID!) { user(id: $id) { id email } }`,
    { id: '42' },
  );
  expect(body.data.user.id).toBe('42');         // сусіднє поле резолвнулось
  expect(body.data.user.email).toBeNull();      // проблемне поле — null
  expect(body.errors?.[0].path).toEqual(['user', 'email']); // локалізація провалу
  expect(body.errors?.[0].extensions?.code).toBe('FORBIDDEN');
});

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

• expect(res.status()).toBe(200) лишається, але як перевірка транспорту в легасі-режимі. Вона каже, що запит доїхав; успіх операції визначає errors/data. Плутати ці дві ролі статусу — головна пастка новачка в GraphQL; а перед тим, як зашивати 200 в хелпер, зʼясуй режим свого сервера.
• Ознака валідації — відсутнє data (toBeUndefined), а не null. Саме це відрізняє провал схеми від провалу резолвера. Якщо асертити toBeNull, тест збреше про природу помилки.
• При помилці резолвера перевіряй data й errors разом. Дивитися лише на data.user.id — і пропустиш email: null; дивитися лише на errors — і не побачиш, що сусідні поля резолвнулися. errors[].path прив'язує помилку до конкретного поля.
• Негативний тест, що чекає на 500, у легасі-режимі не спрацює. «Сервер упав» і відмова на рівні поля приїжджають як 200 із записом у errors. А от відмова цілому запиту — інша річ: специфікація велить віддати 401, 403 або подібний код, тож перед асертом на статус розділяй ці два випадки.

Кейс 3. Куди заводити дефект: таблиця рішень

Одна й та сама зовнішня ознака — «у відповіді є errors» — приховує різні класи багів. Перш ніж писати баг-репорт, треба визначити, на якому етапі впало: це відповідає на питання, чий це дефект.

Як цим користуватись:

• data відсутнє чи з дірками — це різні адресати дефекту. Відсутнє data означає, що виконання не почалося: винен запит клієнта або зміна контракту, а не резолвер. Дірка в data означає, що резолвер конкретного поля (дивись path) упав уже під час виконання — це бекенд або дані.
• errors немає, а результат абсурдний — це теж дефект, і найпідступніший. Схема гарантує лише форму й типи, не бізнес-правила. Валідний за схемою createOrder(total: -100) пройде всі етапи чисто, тож такий тест мусиш проєктувати свідомо — асерт на саме значення, а не на наявність errors.
• Помилку глибини/вартості не плутай із багом. Якщо сервер відбив надто глибокий запит осмисленою помилкою — це захист спрацював правильно; баг був би, якби такий запит поклав сервіс. Межі глибини й вартості — частина контракту, варта окремого позитивного й негативного тесту.
• N+1 не видно в тілі — його видно в часі. Відповідь коректна, errors немає, але запит зі списком і вкладеними полями драматично повільніший за очікуване — перша гіпотеза N+1. Це не функціональний баг конкретної відповіді, а клас деградації під навантаженням.

Статус і тіло відповіді

• Знаю, що в GraphQL один ендпоінт (POST /graphql), а що робити описано в тілі запиту, а не в URL і методі.
• Знаю, що в легасі-режимі application/json статус лишається 200 навіть при помилці, тож оракул успіху — відсутність errors і наявність очікуваних data, а не status === 200.
• Пам'ятаю, що сервер за специфікацією мусить підтримувати медіа-тип application/graphql-response+json, де статуси нормативні (400 — не розібрано документ запиту, 422 — не пройдено валідацію, 405 — мутація через GET), а сервер без нього специфікації не відповідає.

Часткові дані й масив errors

• Знаю, що конверт має два головні поля — data й errors (плюс опційне extensions); вони можуть бути присутні одночасно (partial data), бо резолвери виконуються поле за полем, тож errors перевіряю завжди, навіть коли data заповнене.
• Розрізняю null через реальну відсутність значення і null через помилку резолвера — розводить їх запис у errors із відповідним path; extensions.code стабільніший для асертів, ніж message, але extensions не гарантоване специфікацією.
• Розумію, що data: null цілком означає «виконання почалося, але валідної відповіді не вийшло»; провал non-null поля, що сплив угору по дереву до кореня, — один зі шляхів туди.

Валідація vs логіка резолверів

• Можу пояснити межу між помилкою валідації (до виконання, data відсутнє зовсім, резолвери не викликаються) і помилкою виконання резолвера (partial data: data з дірками плюс errors).
• Розрізняю в баг-репорті проблему клієнта/контракту (валідація) і проблему бекенду/даних (резолвер).
• Пам'ятаю, що схема гарантує лише форму й типи, а не бізнес-правила: валідний за схемою запит легко несе логічний баг (total: -100).

Схема, SDL та інтроспекція

• Розумію, що контракт GraphQL вбудований у сервіс — це схема мовою SDL, а не окрема специфікація як OpenAPI в REST; читаю типізацію (ID! — обов'язкове, [Order!]! — обов'язковий масив із non-null елементами).
• Знаю, що розбіжність nullability між схемою й реальною відповіддю (orders став null) — це баг контракту.
• Розумію, що таке інтроспекція (__schema, __type) і як на ній тримаються GraphiQL, автодоповнення й генерація типів.
• Можу пояснити, чому інтроспекцію часто вимикають на проді, і знаю рецепт: тримати еталонний SDL-файл у репозиторії, а не тягнути схему із середовища щоразу.

Форма відповіді: over-/under-fetching

• Можу пояснити over-fetching (зайві поля) і under-fetching (ланцюжок послідовних запитів) як болі REST, які й породили GraphQL.
• Розумію, що форму відповіді задає запит: немає сенсу перевіряти «повний об'єкт», а та сама сутність із різним набором полів — це різні перевірки з різними правами доступу.

Глибина, складність, N+1

• Знаю про depth limiting і query complexity/cost analysis як захист від зловмисно важких запитів і частину контракту, варту негативного тесту.
• Можу описати симптом N+1 (1 + N звернень до БД на список) і його лікування батчингом через DataLoader.

Інструменти

• Розумію, що логіка перевірки та сама скрізь — читаємо data й errors (GraphiQL/Apollo Sandbox — розвідка схеми, Postman/Insomnia/Bruno — ручні перевірки, код — автотести), а GraphQL-запит у коді — звичайний POST з тілом { query, variables }, без спеціального клієнта.
• Виношу змінні в окремий об'єкт variables, а не вклеюю значення в текст запиту рядковою конкатенацією.