Тест-дизайн для API: CRUD, параметри, межі

Тобі дали POST /orders з десятком полів. З чого починаєш тест-дизайн?

Не зі списку перевірок, а зі структури: спершу дістаю контракт — специфікацію (OpenAPI), схему тіла, статус-коди, — щоб знати типи, обмеження й обов'язковість полів, а не гадати. Далі розкладаю кожне поле на класи еквівалентності (валідні, невалідні за типом, невалідні за діапазоном) і беру граничні значення там, де є межі. Окремо проходжу обов'язкові/опціональні поля, null vs відсутнє vs порожній рядок, потім read-after-write через GET, негативні кейси й дублікати за unique-полем. Наприкінці пріоритезую: happy-path, потім межі ключових полів, потім рідше. Голий список happy-path — слабка відповідь; інтерв'юер слухає систему, а не кількість кейсів.

Як застосувати класи еквівалентності й граничні значення до поля API?

Це ті самі техніки чорної скриньки, що й для UI-форми, але на рівні API межі беруться з контракту, а не з візуальних здогадів. Клас еквівалентності — це група значень, у якій система поводиться однаково: один тест на клас, і кожен невалідний клас окремим кейсом, щоб перша помилка валідації не сховала другу. Граничні значення перевіряють off-by-one — типову плутанину >= і >: для числового поля з діапазоном 1–100 беру 0, 1, 100, 101, для рядка з maxLength: 50 — 49, 50, 51 символ. Плюс спецкласи даних: порожній рядок, пробіли, unicode й емодзі, дуже довгі значення, null — класика, на якій валиться валідація.

Чому null, відсутнє поле й порожній рядок — це три різні тест-кейси?

Бо для JSON це три різні стани, і сервер може реагувати на них по-різному: "phone": null, поля phone немає взагалі, "phone": "". Плутати їх — типова діра в покритті: перевірив відсутність обов'язкового поля, а "field": null не перевірив, і баг лишився. Ключ у тому, що required у JSON Schema перевіряє саме присутність ключа, а не його не-null значення. Тому «поле є, але null» може пройти валідацію обов'язковості й впасти вже глибше — або навпаки. Кожен із трьох станів заслуговує окремого кейса, особливо для полів, де порожнеча має бізнес-сенс.

Як явно перевіряти обов'язковість поля?

Обов'язковість — це окремий інваріант, і його треба перевіряти чотирма ситуаціями, а не однією. Обов'язкове поле відсутнє → 400/422 зі зрозумілою помилкою, що називає поле. Опціональне поле відсутнє → успіх, застосовано значення за замовчуванням або null. Невідоме зайве поле → здебільшого ігнорується, іноді 400 за strict-схеми. І окремо — обов'язкове поле = null, яке часто не те саме, що відсутнє. Пастка тут — вважати, що «відсутнє» й «null» валідуються однаково; часто ні, бо required перевіряє присутність ключа.

Що таке read-after-write і навіщо він, якщо POST уже повернув 201?

Read-after-write — це одразу після створення зробити GET /orders/{id} і звірити, що збереглося саме те, що надіслали. Потрібен він, бо 201 каже лише «запит прийнято», а не «всі поля лягли в базу». Класичний баг — сервер приймає поле, повертає 201, але при читанні його там немає: мовчки проковтнув. Без окремого GET така діра непомітна, тест зелений, а дані неповні. Тому статус-код — необхідна, але недостатня перевірка створення; оракул істини тут — саме читання.

У чому різниця між PUT і PATCH при тестуванні оновлення?

За семантикою PUT замінює ресурс цілком, а PATCH оновлює його частково, і це змінює набір кейсів. Типова помилка PUT — обнулення полів, яких не було в тілі запиту: надіслав тіло з двома полями, а третє, не згадане, сервер затер у null. Тому для PUT обов'язковий кейс «оновлюю частину — що стало з рештою полів». Для PATCH навпаки перевіряю, що незгадані поля лишились недоторканими, а згадані змінились. Плюс обидва треба гнати через read-after-write, бо відповідь 200 ще не гарантує, що зміна реально збереглася.

Чому CRUD треба тестувати як зв'язаний флоу, а не кожен ендпоінт окремо?

Бо CRUD-методи пов'язані станом на сервері, і найцікавіші баги живуть саме в стиках. Щоб прочитати ресурс, його спершу треба створити; щоб оновити — знати id, який повернув POST. Природний ланцюжок: POST → 201 з id і заголовком Location → read-after-write через GET → PUT/PATCH → DELETE → 204, після якого GET має дати 404. Ізольований тест кожного методу пропустить, наприклад, що DELETE начебто відпрацював, а ресурс усе ще читається. Окремий пласт — залежності цілісності: не можна видалити користувача із замовленнями (або каскад, або 409), і ці правила часто не документовані.

Як тестувати пагінацію, щоб нічого не пропустити?

Пагінація — це набір параметрів (limit/offset або page/size), до яких прикладаються граничні значення. Перевіряю: limit=0, limit=1, limit більший за розмір колекції, limit більший за дозволений максимум (а він взагалі є?), offset за межами всіх даних (має бути порожній список, не помилка), від'ємні й нечислові значення, дефолт при відсутньому параметрі. Головний наскрізний інваріант: пройшовши всі сторінки, отримуєш кожен елемент рівно раз — без дублів і пропусків. Саме цей інваріант ловить «дрейф» offset-пагінації, коли між сторінками хтось додав чи видалив запис.

У чому різниця між offset- і cursor-пагінацією для тестувальника?

Offset-based (limit+offset) простий, але «пливе»: якщо між запитами двох сторінок хтось додав або видалив запис, елементи на межах сторінок дублюються або зникають. Cursor/keyset-based передає курсор із попередньої відповіді й стабільніший до змін даних, тому на живих даних поводиться передбачуваніше. Для тестів це означає, що offset-пагінацію треба свідомо перевіряти на дрейф — модифікувати колекцію між сторінками й дивитись на наскрізний інваріант «кожен елемент рівно раз». А з cursor-пагінацією цей клас багів менш імовірний, зате з'являється своя перевірка: коректність і термін життя самого курсора.

Тест шле sort=badField, отримує 200 і список — це достатня перевірка сортування?

Ні, це фальшиво зелений тест. Сервер міг проігнорувати невідоме поле й повернути дефолтний порядок; статус 200 і наявність списку нічого не гарантують. Правильно — або асертити сам порядок елементів, або очікувати 400 на невалідне ім'я поля. По сортуванню перевіряю: валідне поле сортує правильно, невалідне дає 400 (а не мовчить), напрямок за замовчуванням, стабільність за однакових значень ключа (інакше пагінація «пливе») і сортування рядків з урахуванням регістру й локалі. Асерт має перевіряти саме інваріант — впорядкованість, — а не факт відповіді.

Фільтр не дав збігів. Яка правильна відповідь і де тут пастка?

Правильна відповідь — 200 з порожнім масивом [], а не 404. Порожній список — це валідний результат, а не помилка: даних, що підходять під фільтр, просто немає. Пастка двобічна: або тест чекає на дані й падає на порожньому результаті, або сам ендпоінт віддає 404 замість порожньої колекції, і це вже баг контракту. По фільтрації ще перевіряю комбінації кількох фільтрів (це AND чи ігнорування зайвого?), невідоме поле фільтра й спецсимволи в значенні — заодно смоук на ін'єкції, щоб лапка чи відсоток не валили 500.

Що таке переходи станів ресурсу і які кейси тут найцінніші?

Багато ресурсів — це скінченний автомат: замовлення чи платіж проходять статуси (Created → Paid → Shipped → Delivered), і не всі переходи дозволені. Техніка переходів станів лягає на API прямо: подією стає виклик методу, а в моделі мене цікавлять і дозволені стрілки, і їх відсутність. Найбільше багів дають саме заборонені переходи — оплата скасованого замовлення, відвантаження неоплаченого, скасування доставленого: сервер має відмовити через 409 Conflict або 422, тоді як 500 чи мовчазний успіх означають зіпсовані дані. Окремо перевіряю операції над ресурсом у кінцевому стані: DELETE уже видаленого, повторний cancel. Інтерфейс таких дій зазвичай і не пропонує — кнопки просто немає, — тому знайти цю діру можна лише прямим викликом API.

Що таке ідемпотентність і які HTTP-методи ідемпотентні?

Метод ідемпотентний, якщо N однакових запитів залишають сервер у тому самому стані, що й один; мірило — ефект на дані, а не однаковий код відповіді. За HTTP-семантикою (RFC 9110) ідемпотентні GET, HEAD, OPTIONS, TRACE, PUT, DELETE, а POST — ні. Практично: після другого PUT з тим самим тілом ресурс має виглядати так само, як після першого, і якщо повторне застосування щось докидає чи змінює — ідемпотентність зламано. POST не ідемпотентний, бо два POST /orders створять два замовлення, і саме тут виникає ризик подвійних платежів при повторі запиту.

Кандидат каже: «DELETE не ідемпотентний, бо вдруге дає 404». Де він помиляється?

Він плутає різний статус-код із порушенням ідемпотентності. DELETE двічі: перший дає 200/204, другий — найчастіше 404, бо ресурсу вже нема. Але ідемпотентність — про стан сервера, а не про код відповіді, і стан після обох викликів однаковий: ресурс відсутній. Тому різні коди тут — це нормально й ідемпотентності не порушує. Це одна з класичних пасток на співбесіді: сильна відповідь чітко розділяє «однаковий стан сервера від N викликів» і «однаковий статус кожного виклику».

Як не створити два платежі, коли клієнт повторив POST після обриву мережі?

Через заголовок Idempotency-Key: до запиту клієнт додає згенерований унікальний ключ (зазвичай UUID), а сервер зберігає результат першого виконання під цим ключем — і, побачивши повтор, віддає збережену відповідь, не виконуючи операцію вдруге. Це закриває вразливість саме POST, який неідемпотентний: мережа моргнула, клієнт не отримав відповідь, повторив — і без ключа виникло б два замовлення. QA тут перевіряє: повтор із тим самим ключем і тілом дає одну операцію й один ресурс; ключ живе обмежений час і має заявлену область дії; повтор із тим самим ключем, але іншим тілом коректний сервер відхиляє (422), а не тихо застосовує нове тіло під старим ключем. Це де-факто галузева конвенція (її популяризував Stripe).

Що таке lost update і як його протестувати?

Lost update (втрачене оновлення) — це коли два клієнти прочитали той самий ресурс, обидва відредагували й записали, і зміни першого мовчки зникли під записом другого. Захист — оптимістичне блокування через валідатор версії: разом із прочитаним ресурсом клієнт отримує ETag (або поле version) і при записі повертає його в заголовку If-Match; якщо ресурс тим часом встиг змінитися, валідатор уже застарілий, і сервер відхиляє запис із 412 Precondition Failed. Тестую так: два клієнти читають той самий ETag, перший PUT проходить (200, новий ETag), другий PUT зі старим ETag має отримати 412. Відтворити гонку в автотесті допомагає Promise.all для паралельного запуску.

У чому різниця між 409 Conflict і 412 Precondition Failed?

Обидва сигналять конфлікт, але про різне. 409 — запит конфліктує з поточним станом ресурсу як таким: невалідний перехід стану (оплатити скасоване), дублікат за unique-полем, спроба видалити сутність із залежностями. 412 — вужчий і про умовні запити: клієнт надіслав передумову (If-Match з ETag), і вона не виконалась, бо ресурс змінився з моменту читання. Тобто 409 — «так з цим ресурсом зараз не можна», 412 — «твоя копія застаріла, перечитай і спробуй ще». Плутати їх на співбесіді з оптимістичного блокування — типова помилка; правильна відмова простроченому ETag — саме 412.

Часу мало. Як пріоритезувати покриття API?

Повне покриття комбінацій параметрів неможливе — це комбінаторний вибух. Тому питання не «які кейси існують», а «які писати першими», і орієнтир — цінність за спаданням. Спершу happy-path кожної CRUD-операції (базовий смоук, що створення/читання/оновлення/видалення проходять узагалі). Потім state-changing операції понад читання: баг у POST/PUT/DELETE псує дані, баг у GET лише показує неправильне. Далі межі й невалідні класи ключових полів, потім заборонені переходи станів і залежності цілісності (те, чого не видно на UI), і насамкінець ідемпотентність та гонки для критичних операцій. Критерій «що критичне» — ризик: ймовірність збою × вплив, тому платіж отримує глибше покриття, ніж зміна аватарки.

Три кейси, що показують тест-дизайн API у дії: розкладання полів POST /users на класи й межі у вигляді таблиці рішень, зв'язаний CRUD-флоу з read-after-write і DELETE→404 у Playwright, і контрактні перевірки ідемпотентності та lost update. Скрізь — що перевіряємо і чому саме так.

Кейс 1. Розкладаємо POST /users на класи й межі

Дано ендпоінт із контракту:

# скорочено зі схеми OpenAPI (структура спрощена)
POST /users
required: [email, age]
properties:
  email:    { type: string, format: email, maxLength: 254 }
  age:      { type: integer, minimum: 18, maximum: 120 }
  nickname: { type: string, maxLength: 30 }   # опціональне

Замість «набити кейсів» проходимо кожне поле алгоритмом класи → межі → спецдані. Виходить компактна таблиця рішень — по одному тесту на клас:

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

• Межі age — це 17/18/19 і 120/121, а не «якесь мале й якесь велике». Саме на межі живе off-by-one: > замість >= пропустить 17 або зріже 18. Три точки навколо кожної межі ловлять цю плутанину.
• null і «відсутнє» — два рядки таблиці, не один. required перевіряє присутність ключа, тому "email": null може пройти валідацію обов'язковості й впасти глибше. Один кейс на обидва стани — типова діра.
• Кожен невалідний клас — окремий запит. Якщо в одному тілі одразу битий email і від'ємний age, перша ж помилка валідації сховає другу, і покриття буде уявним.
• Опціональне поле теж має інваріант. Відсутній nickname — це не «пропустити», а перевірити, що сервер підставив дефолт або null, а не впав.

Кейс 2. CRUD як флоу: read-after-write і DELETE → 404

Ізольований тест POST побачить 201 і заспокоїться. Зв'язаний флоу ловить баги в стиках: чи справді збереглося те, що надіслали, і чи DELETE реально прибрав ресурс.

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

test('CRUD flow: створення живе, оновлення застосовується, видалення прибирає', async ({ request }) => {
  const payload = { email: 'crud@test.io', age: 30, nickname: 'neo' };

  // POST → 201, дістаємо id і Location
  const created = await request.post('/users', { data: payload });
  expect(created.status()).toBe(201);
  const { id } = await created.json();
  expect(created.headers()['location']).toContain(`/users/${id}`);

  // read-after-write: 201 ще не значить «збереглося все»
  const read = await request.get(`/users/${id}`);
  expect(read.status()).toBe(200);
  expect(await read.json()).toMatchObject(payload); // проковтнуте поле спливе саме тут

  // PATCH оновлює частково — незгадані поля лишаються
  const patched = await request.patch(`/users/${id}`, { data: { nickname: 'trinity' } });
  expect(patched.status()).toBe(200);
  const afterPatch = await (await request.get(`/users/${id}`)).json();
  expect(afterPatch.nickname).toBe('trinity');
  expect(afterPatch.age).toBe(30); // PATCH не мав чіпати age

  // DELETE → 204, після чого ресурсу немає
  expect((await request.delete(`/users/${id}`)).status()).toBe(204);
  expect((await request.get(`/users/${id}`)).status()).toBe(404);
});

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

• matchObject після GET — головний оракул створення. Без нього баг «сервер прийняв поле, повернув 201, але не зберіг» лишається невидимим: асерт на статус його не ловить.
• PATCH перевіряємо на те, чого він НЕ чіпав. age після зміни nickname має лишитись 30. Якби це був PUT без age у тілі, тут спливло б обнулення незгаданого поля.
• DELETE доводимо читанням. 204 каже «прийняв», а GET → 404 доводить, що ресурс справді зник, а не «видалився» лише в статусі.
• Location — частина контракту 201. Перевірка заголовка ловить розбіжність між тілом і задекларованою адресою нового ресурсу.

Кейс 3. Ідемпотентність POST і захист від lost update

Дві найдорожчі помилки на state-changing операціях — подвійне створення при повторі й затерте оновлення при гонці. Обидві перевіряються контрактно.

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

test('Idempotency-Key: повтор POST не створює другий ресурс', async ({ request }) => {
  const key = crypto.randomUUID();
  const order = { ref: 'A-100', customerId: 42, amount: 500 };

  const first = await request.post('/orders', {
    headers: { 'Idempotency-Key': key }, data: order,
  });
  // повтор із тим самим ключем і тілом — імітація моргання мережі
  const retry = await request.post('/orders', {
    headers: { 'Idempotency-Key': key }, data: order,
  });

  expect(retry.status()).toBe(first.status());        // той самий збережений результат
  const listed = await (await request.get('/orders?customerId=42')).json();
  expect(listed.items.filter((o) => o.ref === order.ref)).toHaveLength(1); // рівно один
});

test('optimistic locking: прострочений ETag дає 412, а не тихе затирання', async ({ request }) => {
  // двоє читають ту саму версію
  const read = await request.get('/orders/7');
  const etag = read.headers()['etag'];

  // перший пише — версія стає новою
  const okUpdate = await request.put('/orders/7', {
    headers: { 'If-Match': etag }, data: { amount: 600 },
  });
  expect(okUpdate.status()).toBe(200);

  // другий пише зі старим ETag — має відлетіти в 412, а не затерти зміну першого
  const staleUpdate = await request.put('/orders/7', {
    headers: { 'If-Match': etag }, data: { amount: 999 },
  });
  expect(staleUpdate.status()).toBe(412);
});

Гонку на створення дубліката за unique-полем відтворюємо паралельним запуском:

test('два майже одночасні POST з unique-полем розходяться на 409', async ({ request }) => {
  const body = { email: 'race@test.io', age: 25 };
  const [a, b] = await Promise.all([
    request.post('/users', { data: body }),
    request.post('/users', { data: body }),
  ]);
  const codes = [a.status(), b.status()].sort();
  expect(codes).toEqual([201, 409]); // один створив, другий отримав конфлікт
});

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

• Оракул ідемпотентності — не статус, а кількість ресурсів. retry.status() може збігтися випадково; доказ істини — filter(...).toHaveLength(1) у списку. Саме він відрізняє «повтор дедуплікувався» від «створилось два замовлення».
• 412, а не 409, на простроченому ETag. Тут не виконалась передумова If-Match умовного запиту — це рівно 412 Precondition Failed. Асерт на 409 тут був би змістовною помилкою.
• Гонку на unique-полі розводить Promise.all. Правильний результат — [201, 409]: один запит створив, другий упав у конфлікт. [201, 201] означало б, що unique-обмеження обійшли, і в базі дублікат.
• Ці кейси не видно на UI. Кнопку «створити» користувач двічі за мілісекунду не натисне, а мережа моргне легко — тому такі баги ловляться лише прямими паралельними викликами API.

Техніки над полями і параметрами

• Розумію, що кожне поле тіла й кожен параметр (query, path, header) — вхід для класів еквівалентності й граничних значень, а межі беру з контракту (OpenAPI), не з візуальних здогадів.
• Можу застосувати граничні значення до числа (0, 1, 100, 101 для діапазону 1–100) і до рядка (maxLength: 50 → 49, 50, 51 символ).
• Даю кожному невалідному класу окремий кейс і пам'ятаю спецдані: порожній рядок, пробіли, unicode й емодзі, дуже довгі значення, null.

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

• Розумію, що "phone": null, відсутній ключ phone і "phone": "" — три різні стани JSON з різною реакцією сервера.
• Знаю, що required у JSON Schema перевіряє присутність ключа, а не не-null значення; обов'язковість гоню чотирма ситуаціями (обов'язкове відсутнє / опціональне відсутнє / зайве поле / обов'язкове = null).

CRUD як зв'язаний флоу

• Можу пояснити, чому CRUD — це флоу зі станом на сервері: POST → 201 з id і Location → read-after-write через GET → PUT/PATCH → DELETE → 204 → GET дає 404.
• Розумію, навіщо read-after-write: 201 не гарантує, що поля лягли — сервер міг мовчки проковтнути поле.
• Знаю різницю PUT (ризик обнулити незгадані поля) vs PATCH і пам'ятаю про залежності цілісності: видалення сутності із залежностями — це каскад або 409.

Колекції: пагінація, сортування, фільтрація

• Можу пояснити offset-based (limit+offset, «пливе» при змінах даних) vs cursor/keyset (стабільніший).
• Знаю граничні кейси пагінації (limit 0/1/більший за колекцію/більший за максимум, offset за межами → порожній список) і наскрізний інваріант «кожен елемент рівно раз».
• Розумію, чому sort=badField з 200 — фальшиво зелений тест (асертити порядок або 400), і що фільтр без збігів — це 200 [], а не 404.

Стани ресурсу і переходи

• Застосовую техніку переходів станів: перевіряю не лише дозволені, а й заборонені переходи (оплатити скасоване, відвантажити неоплачене).
• Знаю, що невалідний перехід — це 409/422, а не 500 чи мовчазний успіх, і що на UI такі переходи часто недоступні — ловляться лише прямим викликом API.

Ідемпотентність

• Можу визначити ідемпотентність як однаковий стан сервера від N запитів (про ефект на дані, не про статус) і назвати ідемпотентні методи (GET, HEAD, OPTIONS, TRACE, PUT, DELETE), а POST — ні.
• Розумію, чому DELETE двічі (204, потім 404) НЕ порушує ідемпотентність — стан сервера однаковий.
• Можу пояснити Idempotency-Key (клієнт шле UUID, сервер дедуплікує POST) і що повтор ключа з іншим тілом коректний сервер відхиляє (422).

Конкурентність і гонки

• Можу пояснити lost update і захист — оптимістичне блокування через ETag/If-Match з відповіддю 412 на прострочений валідатор.
• Розрізняю 409 Conflict (конфлікт зі станом ресурсу) і 412 Precondition Failed (не виконалась передумова умовного запиту); гонки відтворюю через Promise.all.

Пріоритезація покриття

• Можу впорядкувати покриття за цінністю: happy-path CRUD → state-changing операції → межі ключових полів → заборонені переходи й цілісність → ідемпотентність і гонки.
• Розумію, чому state-changing (POST/PUT/DELETE) пріоритетніші за GET, і знаю критерій ризику — ймовірність збою × вплив (платіж глибше за аватарку).